Origami Frontend Components & Services

Readme: o-message

o-message is a messaging component used for alerting, informing or making calls to action.

o-message uses Sass and Javascript to show and hide a message component.

It can be initialised declaratively if markup is provided on the page, or it can be initialised imperatively when using the manual build process.

Message Types

o-message provides three types of messages: action, alert, and notice.

You can find a demo for each of the messages above in the Origami registry.

A default message is designed to span across a page in whatever container it is placed in.
An 'inner' message is meant to sit within a smaller container, as it stacks information, instead.

In addition to layout, messages can accept another variation: state.
However, not every message accepts every state, or every layout, and not every message works for every brand. Please check the table below against the needs of your product. If you need a message that is not available to you, please get in touch with the Origami team.

state support layout support brand support
action message inform, inform-inverse default internal, whitelabel
alert message success, neutral, error default, inner all
notice message inform, warning, warning-light default, inner master: inform state only
internal: all states
whitelabel: inform state only

Markup

All messages have the same markup. What will style them differently are the following modifiers:

Note: as mentioned in the description of the message types, not all states will work for all message types. In addition to that, the layout modifier only applies to alert and notice type messages.

This example illustrates the basic markup for a successful alert message:

<div class="o-message o-message--alert o-message--success" data-o-component="o-message">
    <div class="o-message__container">
        <div class="o-message__content">
            <p class="o-message__content-main">
                <span class="o-message__content-highlight">Oops.</span>
        </div>
    </div>
</div>

You can add more information about the message with the following markup:

<div class="o-message o-message--alert o-message--success" data-o-component="o-message">
    <div class="o-message__container">
        <div class="o-message__content">
            <p class="o-message__content-main">
                <span class="o-message__content-highlight">Oops.</span>
+                <span class="o-message__content-detail">
+                    Something went wrong!
+                    The quick brown fox did not jump over the lazy dogs.
+                </span>
            </p>
        </div>
    </div>
</div>

And you can also add actions, such as a button and/or a link to your message:

<div class="o-message o-message--alert o-message--success" data-o-component="o-message">
    <div class="o-message__container">
        <div class="o-message__content">
            <p class="o-message__content-main">
                <span class="o-message__content-highlight">Oops.</span>
                <span class="o-message__content-detail">
                    Something went wrong!
                    The quick brown fox did not jump over the lazy dogs.
                </span>
            </p>
+            <div class="o-message__actions">
+                <a href="#" class="o-message__actions__primary">Button</a>
+                <a href="#" class="o-message__actions__secondary">Text link</a>
+            </div>
        </div>
    </div>
</div>

If you have applied the o-message--inner modifier to your message, you can add additional, entirely optional, content:

-<div class="o-message o-message--alert o-message--error" data-o-component="o-message">
+<div class="o-message o-message--alert o-message--inner o-message--error" data-o-component="o-message">
    <div class="o-message__container">
        <div class="o-message__content">
            <p class="o-message__content-main">
                <span class="o-message__content-highlight">Oops.</span>
                <span class="o-message__content-detail">
                    Something went wrong!
                    The quick brown fox did not jump over the lazy dogs.
                </span>
            </p>
+            <p class="o-message__content-additional">
+                Did you know that that sentence uses all of the letters in the alphabet at least once?
+            </p>
            <div class="o-message__actions">
                <a href="#" class="o-message__actions__primary">Button</a>
                <a href="#" class="o-message__actions__secondary">Text link</a>
            </div>
        </div>
    </div>
</div>

For any message, you can highlight any portion of copy within a paragraph by using the markup like this:

<div class="o-message o-message--alert o-message--success" data-o-component="o-message">
    <div class="o-message__container">
        <div class="o-message__content">
            <p class="o-message__content-main">
                The quick brown fox did <span class="o-message__content-highlight">not</span> jump over the lazy dogs.
            </p>
        </div>
    </div>
</div>

For action messages only, you can centralise the text with a specific class (.o-message__content--center-align):

<div class="o-message o-message--action o-message--inform" data-o-component="o-message">
    <div class="o-message__container">
-        <div class="o-message__content">
+        <div class="o-message__content o-message__content--center-align">
            <p class="o-message__content-main">
                This will be a call to action. Feedback, please.
            </p>
        </div>
    </div>
</div>

JavaScript

No code will run automatically unless you are using the Build Service. You must either construct an o-message object or fire an o.DOMContentLoaded event, which o-message listens for.

Construction

If you have set up your message declaratively, use the following to initialise your message.

const oMessage = require('o-message');
oMessage.init();

oMessage will initialise its element with a close button by default. With a declaratively set up message, this can be avoided by adding data-close="false" to the message element.

If you're setting up a message without existing DOM elements, oMessage will construct an element for you. As long as your markup contains an element with the data attribute data-o-component=o-message, you can initialise a message with specific options.

const oMessage = require('o-message');
const importantMessage = new oMessage(null, {
    type: 'alert',
    status: 'error',
    content: {
        highlight: 'Something has gone wrong.'
        detail: 'The quick brown fox did not jump over the lazy dogs.'
    }
});

Options

o-message allows for several configuration options that will change the type of message and its visual styling.

The only required options are listed in the example above. These are:

The following options are not required, and all have a default value:

Sass

You can include all styles and variations for every message type by calling:

@include oMessage();

You can also be more specific about which message styles and variations you would like to output by using an $opts map:

@include oMessage($opts: (
    'types': ('action', 'notice'),
    'states': ('inform', 'warning'),
    'layouts': (inner)
));

Migration

State Major Version Last Minor Release Migration guide
✨ active 3 N/A migrate to v3
⚠ maintained 2 2.4 migrate to v2
╳ deprecated 1 1.0 N/A

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.

Switch component view

GitHub Repository

Install o-message

If using the Build Service, add o-message@^3.1.2 to your script and link tags.

If running a Manual Build, run bower install --save "o-message@^3.1.2".

Help & Support

o-message is maintained directly by the Origami team. If you have any questions about o-message or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com