Messages
Documentation > Forms > Messages
BoltWire has an advanced messaging system to help you in debugging forms, or just to communicate with your form users. Some messages are communicated automatically by the system, others can be introduced. The messaging system is easy to use, but there are many options to give you fine toothed control over what gets sent back to the browser.
Simple Messages
To see system messages, simply put [messages] somewhere on your page with the form. Any automatic messages will be displayed. In many skins, this is automatically inserted into the page, and you do not need to insert it into a page.
Some prefer to have system messages normally only visible to admins. In this situation, you would put [if admin][messages][if] on the page (or skin).
To replace the default system messages with a custom message add this to your form:
[session msg "My message."]
This will replace all system messages with your one message. Leave the value blank to clear all system messages.
Form Messages
You can add custom messages to the system messages by adding an id to the message command. For example, you could put
[session msg_one "First message. "]
in your form and that message would be added to the other system messages. It would not replace or clear out other system messages. Note the extra space at the end of the message. This is to separate it from any form or system message appearing later in the form.
System messages can also be cleared or rewritten if you know the message key. For a list of message keys, go to site.messages. For example, before the "Form submitted." message, you will notice the key "form_submit". To override the default message in a specific form, simply do one of the following:
[session msg_form_submit]
[session msg_form_submit "Yo! Got the form... "]
The first clears that one single message. The second overrides the default system message. If you really like the new system message, you can edit the site.messages page and change it automatically on every form.
Note: this could cause problems with translation modules.
Warnings
You can also use the command warn in a similar way. The difference is "warn" automatically aborts the form submission process. It is often used in input validation. Note, you need to place a blank warn field at the point you want it to stop or it will be appended to the end of the form and not stop until the entire form as been processed. Consider the two examples:
BAD
<code>
</code> GOOD <code> </code>
For more information about form validation, see the forms validation tutorial.
Advanced Messaging
If you wish to have a specific Form Message appear somewhere in the page, you can use the following syntax
[messages one]
This will show the content of field msg_one in the specified place. The following form gives an example of how this works.
<code>all:
1:
2:
3:
</code>
A more useful example would be a series of validation checks with appropriate messages at specific points in an input form to explain what was wrong with their form. If someone develops a nice example, feel free to update the snippet above. Or add it.
