Messages
Learn about using the Messages object across requests.
Messages are a simple way to communicate a one-time notice, alert, or message. They are intended for a single user/visitor to see on the very next page view (GET). Messages may be more typically added during redirects.
Messages are intended for information purposes only, and should not contain sensitive or secure information. For example, do not include a user's name, email, etc.
New Messages
The Messages
object is always available and pre-imported.
There are 4 message levels and typical uses:
success
‐ Expected action was taken / something occurred.info
‐ Default / neutral / informational notification.error
‐ Action not be taken, invalid input, or unexpected error.warning
‐ Softer error, that may not require further action by the user.
Global Messages
Messages.success('A new Article was created');
Field Specific
Messages may be associated with a specific field name. The field name must be interpreted client-side, as it may represent a custom named form input field.
Messages.fieldError('title', 'Titles may not contain special characters.');
Mustache Rendering
For standard handling of form POSTs and message display, you'll be emitting the messages via a Mustache template.
Bootstrap CSS
The following example maps the message types to Bootstrap classes and displays the messages as an "alert" class:
<!--TEMPLATE mustache-->
{{% choose-string-map message error=alert-danger *=alert-* }}
{{#Messages.all}}
<div class="alert {{% choose-string message this.type }}">
{{this.value}}
</div>
{{/Messages.all}}
Bulma CSS
The following example maps the message types to Bulma classes and displays the messages as a "notification" class:
<!--TEMPLATE mustache-->
{{% choose-string-map message error=is-danger *=is-* }}
{{#Messages.all}}
<div class="notification {{% choose-string message this.type }}">
{{this.value}}
</div>
{{/Messages.all}}
API Rendering
If form handling is being done as an API call, then it's still recommended to use the Messages object and API for code readability and convenience.
In this case you'll want to emit the messages as JSON, immediately on the server-side, rather than waiting until the next GET.
import {Article} from '📦';
import {title} from 'form';
new Article().title(title);
Messages.success('Successfully created new Article');
if (title == 'great')
Messages.fieldInfo('title', 'Great title for the Article!');
({messages: Messages.now()});
Calling Messages.now()
will emit a JSON array.
It will also cause all messages to be flushed out so they are not visible on the next GET.
It is the responsibility of the client making the request to
interpret this array and display messages accordingly.
{
"messages":[
{"type": "success", value: "Successfully created new Article"},
{"type": "info", field: "title", value: "Great title for the Article!"}
]
}
Throwing Messages
Messages may also be thrown as an error:
throw Messages.fieldError('title', 'Not Good');
Results in client side JSON with HTTP status code 422:
{
"messages":[
{"type": "error", "field": "title", "value": "Not Good"}
]
}
Passing Data
Messages may also be used to pass arbitrary string data from one request to another.
Given a POST which sets data and redirects to /
:
Messages.data('thing', 'one');
Redirect.home();
For the very next GET only, the value of thing
will be available:
<!--TEMPLATE mustache-->
{{#Messages.data.thing}}
Hello thing: {{Messages.data.thing}}
{{/Messages.data.thing}}
{{^Messages.data.thing}}
No thing
{{/Messages.data.thing}}