menu-btn

Flash Messages

Flash Messages

Display a message about the outcome of a request.

Flash Messages are a handy way to let the user know the outcome of a request, either as a sucess or failure. Simply use the Flash facade to display a message after the request finishes. Flash messages are usually set inside AJAX handlers, inside Component logic or inside the page or layout PHP section.

function onSave()
{
    // Sets a successful message
    Flash::success('Settings successfully saved!');

    // Sets an error message
    Flash::error('Something went wrong...');

    // Sets a warning message
    Flash::warning('Please confirm your email address soon');

    // Sets an informative message
    Flash::info('The export is still processing. Please try again in a minute.');
}

Flash messages will disappear after an interval of 3 seconds. Clicking on a flash message will stop it from disappearing.

# Built-in Flash Messages

The AJAX framework has built-in support for flash messages, simply specify the data-request-flash attribute on a form to enable the use of flash messages on completed AJAX requests.

<form
    data-request="onSuccess"
    data-request-flash>
    <!-- ... -->
</form>

To ensure flash messages are also displayed when the browser is redirected, you should render a inline flash message when the page loads by placing this code in your page or layout.

{% flash %}
    <p
        data-control="flash-message"
        data-type="{{ type }}"
        data-interval="5">
        {{ message }}
    </p>
{% endflash %}

To only display a specific flash message type, you may pass the value to the attribute — success, error, info, warning or validate. Multiple values are separated by commas.

<form data-request-flash="success,warning"></form>

When using validation features in combination with the data-request-flash attribute, the validation errors take priority and suppress the flash message. To display both at the same time, include the validate type with the attribute.

<form
    data-request-validate
    data-request-flash="success,error,validate">

# Loading Flash Message

The data-request-message attribute can be used to display a flash progress message while the request runs. This is great particularly for long running processes.

<button
    data-request="onSubmit"
    data-request-message="Please wait while we process your request...">
    Submit
</button>

# Styling the Flash Message

To change the appearance of the flash message, target the .oc-flash-message CSS class.

.oc-flash-message.success {
    background: green;
}
.oc-flash-message.error {
    background: red;
}
.oc-flash-message.warning {
    background: orange;
}
.oc-flash-message.info {
    background: aqua;
}
.oc-flash-message.loading {
    background: aqua;
}

# Custom Flash Messages

See the Flash Twig Tag article to learn more about the {% flash %} tag.

To display inline flash messages or completely change the default flash message markup, create a new partial in your theme with the custom content. For example, create a new partial named flash-messages.htm and paste in the following content.

{% flash %}
    <div class="alert alert-{{ type }}">
        {{ message }}
    </div>
{% endflash %}

Next, include the partial in your form as a self-updating partial using the {% ajaxPartial %} tag. Referencing the partial name in data-request-update will automatically update this partial and disable the in-built flash messages.

<form>
    {% ajaxPartial 'flash-messages' %}

    <label>Title</label>
    <input name="title" />

    <button
        data-request="onSave"
        data-request-update="{ flash-messages: true }">
        Save
    </button>
</form>

Alternatively, you can include the partial inside a layout, and update it globally instead of adding the data-request-flash every element. Add the ajax-request-update meta tag in the head section of the page, and set the content attribute to update the partial globally.

<head>
    <meta name="ajax-request-update" content="{ flash-messages: true }" />
</head>
<body>
    <!-- Updates with every AJAX request -->
    {% ajaxPartial 'flash-messages' %}
</body>

# Working with JavaScript

Use the oc.flashMsg function to display a flash message using JavaScript. A type can be specified as either success, error or warning. An optional interval can be specified to control how long the flash message is displayed in seconds.

oc.flashMsg({
    message: 'Record has been successfully saved. This message will disappear in 1 second.',
    type: 'success',
    interval: 1
});

# See Also

← Pagination →