Join Now

Click here to join our
growing community:

JOIN LOGIN



Docs

Welcome Tour
Handbook
      Markups
      Variables
      Conditions
      Functions
      Forms
      Commands
      Concepts
Extensions
Pro Modules
Developers



Copyright © 2020
Terms of Use
Privacy Policy
BoltWire

Handbook

Msg

This command taps into BoltWire's messaging system, allowing you to give messages back to the user on form submission. It can also clear or modify system messages.

Here's a simple form to illustrate how it works:

[form]
[submit]
[command msg 'You clicked the button']
[form]

[messages]

The user clicks the button. The msg is added to the message array. And then when the page reloads, it is displayed by the message markup.

Here's a slightly more interesting example:

[form]
[submit RED] [submit BLUE]
[command if "equal {=submit} RED ? msg='You clicked the RED button' : msg='You clicked the BLUE button'"]
[form]

[messages]

System Messages

BoltWire generates many messages on its own indicating there has been some problem with a form submission or to notify you of success. You can either define the message, or BoltWire will generate one from the site.messages page. If you do not like a default system message, find it on the site.messages page and modify it.

Let's say for example you required input on this form field:

[form]
[text test required=true]
[submit]
[form]

If they fail to enter something, the default message will be returned: "Invalid input for field: test." Suppose you wanted to modify that. You can change the form like this and it will do what you would expect:

[form]
[text test required=true msg='Hey, fill in the field']
[submit]
[form]

Clearing Messages

Suppose you retrieved some information from two pages into a form like this:

[form]
[submit]
[command source some.page:title]
[command source another.page:title]
[form]

BoltWire automatically generates a message for each command that the information is retrieved: "Source retrieved for page some.page. Source retrieved for page another.page." To modify that, I can clear all messages, clear a certain category of message, or clear individual messages.

To clear all messages add this line to your form. Make sure it is near the end of your form, as it only clears messages generated up to that point in the forms processing.

[form]
[submit]
[command source some.page:title]
[command source another.page:title]
[command msg id=all]
[form]

If you look on the site.messages page, you will see that the id for these messages is func_source. To clear all messages with this id use this line:

[command msg id=func_source]

If you want to clear only the second message, for example, use this line:

[command msg id=func_source~2]

Note: messages from input fields work differently than messages in commands, because a failed input keeps form processing from even starting. The msg parameter in an input field is used to replace any message from the aborted input, regardless of why it fails. To eliminate an input abort message, set the message equal to a single space (msg=' ').

Replacing Messages

Normally, when I use the message command a new message is simply added to the message array. So this page will return a string with three messages:

[form]
[submit]
[command source some.page:title]
[command source another.page:title]
[command msg 'My new message']
[form]

I can, however, replace system messages with my own custom text using the msg command. I can replace the entire message output, messages of a certain type, or specific messages. I only need to indicate the id and supply a new message. So to replace the entire message output, use this form:

[form]
[submit]
[command source some.page:title]
[command source another.page:title]
[command msg 'My new message.' id=all]
[form]

To replace all messages using a specific id with a single message, use this line:

[command msg 'Source files retrieved.' id=func_source]

If you want to replace only the second message, for example, use this line:

[command msg 'Got the 2nd page too!' id=func_source~2]

Displaying Messages

As noted above, [messages] is a special markup used to display system messages. You can put it on specific pages, or somewhere in your skin, like a side menu or header. You can also wrap it in conditional like [if admin], etc, so only admins see your messages. It is not processed like normal markup, as it must wait until all processing is complete to gather all messages, and only inserted at the very end of the page generation.

By default, all messagesare displayed-- but you can change it to only display certain messages. For example, suppose you had the following form:

[form]
[submit]
[command source some.page:title]
[command source another.page:title]
[command msg 'hello']
[command msg 'goodbye']
[command msg test id=test]
[form]

Normally, this would generate two func_source messages (func_source~1 and func_source~2) and three command messages. The first two would have ids msg_1 and msg_2. The third would have id test. Knowing the id's I can retrieve any of the following (all of which are pretty self-explanatory):

[messages func_source]
[messages func_source~2]
[messages msg_1]
[messages test]
[messages func_source~1,msg_2,test]
Both func_source messages
The 2nd func_source message
The word 'hello'
The msg with the id set to test
Just the three specified messages

I can also retrieve some messages in one part of the page, and others in another. And perhaps limit some messages to certaini users. Consider this example:

[form]
[submit]
[command source some.page:title]
[command source another.page:title]
[command msg 'Files Uploaded']
[form]

[if admin][messages][else][messages msg][if]

Admins get to see all the messages, users get to see a simplified message. The messaging system in BoltWire gives you virtually unlimited control of over messages users see, and where they are displayed.

Note: the [messages] markup cannot be escaped using the backtick operator. That is `[messages] will not be escaped as expected. Other escaping mechanisms do work.

Styling Messages

By default messages are assigned a "message" class, defined in your style sheet. You can however add an id, class, or style parameter to the message markup to customize the display as desired.

Function Messaging

The BoltWire messaging system extends to functions, though it is turned off by default. That is, functions sometimes generate messages--but they are not seen unless you turn them on. To turn on the messages coming back from an individual function, add messages=true to the parameters of the function. To turn them on sitewide, set funcMessages: true in site.config. You can also turn them on dynamically in config.php or a plugin by changing the config value based on your needs. This might be useful if you only want admins to see these messages.

Note: Function messages cannot be suppressed or overwritten by the msg command in BoltWire, as they are generated either before or after the form is submitted.

Attributes

By default the message output is enclosed in a div with class=message. You can add a few additional parameters to the div, including an id, class, or style argument. This gives you powerful control over how the div appears in your page.