Origami Frontend Components & Services

JSDoc: o-message

CharacterHighlight

Properties

  • 0 - (type: string) the character in the suggestion
  • 1 - (type: boolean) should it be highlighted?

Type

Array

Links

PopulateOptions(options)

parameter type default description
options Array.<*> The options which match the rext which was typed into the autocomplete by the user

Returns

  • void

Type

function

Links

Source(query, populateOptions)

parameter type default description
query string Text which was typed into the autocomplete by the user
populateOptions PopulateOptions Function to call when ready to update the suggestions dropdown

Returns

  • void

Type

function

Links

MapOptionToSuggestedValue(option)

parameter type default description
option * The option to transform into a suggestion string

Returns

  • string - The string to display as the suggestions for this option

Type

function

Links

onConfirm(option)

parameter type default description
option * The option the user selected

Returns

  • void

Type

function

Links

AutocompleteOptions

Properties

  • defaultValue - (type: string) Specify a string to prefill the autocomplete with
  • source - (type: Source) The function which retrieves the suggestions to display
  • mapOptionToSuggestedValue - (type: MapOptionToSuggestedValue) Function which transforms a suggestion before rendering
  • onConfirm - (type: onConfirm) Function which is called when the user selects an option

Type

object

Links

MessageOptions

An object of options to configure a message instance.

Properties

  • type - (type: string) The o-message type e.g. 'action', 'alert' and 'notice'.
  • state - (type: string) The o-message state e.g. `success`, `neutral`, `error`, `inform-inverse`.
  • autoOpen - (type: boolean) [true] - Whether to show the message automatically.
  • parentElement - (type: string) [null] - The element to append the message to. If none is declared it will leave any existing message elements in place or append to the body when creating a new message element.
  • content - (type: object) Configuration for the message copy.
  • content.detail - (type: string) Copy for of the message e.g "Thing saved to the place you requested.".
  • content.highlight - (type: string) [null] - Highlighted copy to prepend the main message copy "Success!".
  • content.additionalInfo - (type: string) [null] - More copy with additional information – only applies to a message with an `inner` layout.
  • actions - (type: Object) Links to display on the message.
  • actions.primary - (type: Object) Show a link in the style of a primary button within the message.
  • actions.primary.text - (type: string) The copy for the link.
  • actions.primary.url - (type: string) The url for the link.
  • actions.primary.openInNewWindow - (type: boolean) [false] - Opens in a new tab/window when set to `true`.
  • actions.secondary - (type: Object) Show a link with less emphasis that the primary action.
  • actions.secondary.text - (type: string) The copy for the link.
  • actions.secondary.url - (type: string) The url for the link.
  • actions.secondary.openInNewWindow - (type: boolean) [false] - Opens in a new tab/window when set to `true`.
  • close - (type: boolean) [true] - Whether or not to display a close button.

Type

object

Links

highlightSuggestion(suggestion, query)

Global Function

parameter type default description
suggestion string Text which is going to be suggested to the user
query string Text which was typed into the autocomplete by the user

Returns

  • Array.<CharacterHighlight> - An array of arrays which contain two items, the first is the character in the suggestion, the second is a boolean which indicates whether the character should be highlighted.

Links

createLoadingContainer

Global Function

Create DOM for the loading container.

Returns

  • HTMLDivElement - The loading container.

Links

showLoadingPane(instance)

Global Function

Show the loading panel

parameter type default description
instance Autocomplete The autocomplete instance whose loading panel should be shown

Returns

  • void

Links

hideLoadingPane(instance)

Global Function

Hide the loading panel

parameter type default description
instance Autocomplete The autocomplete instance whose loading panel should be hidden

Returns

  • void

Links

createClearButton(id)

Global Function

Create the DOM tree which corresponds to <button class="o-autocompleteclear" type="button" aria-controls=${autocompleteEl.id} title="Clear input"> <span class="o-autocompletevisually-hidden">Clear input</span> </button>

parameter type default description
id string The id of the autocomplete input to associate the clear button with

Returns

  • HTMLButtonElement - The clear button DOM tree

Links

initClearButton(instance)

Global Function

Attach the clear button and corresponding event listeners to the o-autocomplete instance

parameter type default description
instance Autocomplete The autocomplete instance to setup the clear button for

Returns

  • void

Links

new Autocomplete(autocompleteEl, options)

Class constructor.

parameter type default description
autocompleteEl (optional) HTMLElement The component element in the DOM
options (optional) AutocompleteOptions {} An options object for configuring the component

Methods

Properties

Links

new Message(messageElement, options)

Initialises an `o-message` component.

parameter type default description
messageElement HTMLElement [undefined] - The `o-message` element (optional).
options MessageOptions An options object for configuring the message.

Methods

Examples

Example #1

To construct all elements on the page with the `data-o-component="o-message"` attribute.
     Message.init();

Example #2

To construct a specifc o-message on the page.
			const myMessageElement = document.querySelector('.my-message');
     const myMessage = new Message(myMessageElement, {});

Example #3

To construct a message which does not already exist on the page.
     const errorAlert = new Message(null, {
			type: 'alert',
			state: 'error',
			content: {
				highlight: 'Something has gone wrong.',
				detail: 'The quick brown fox did not jump over the lazy dogs.'
			}
     });

Links

new Overlay(...)

Represents an Overlay.

Construct an overlay.

parameter type default description
id HTMLElement String. A unique identifier for the overlay within the page. (Required)
opts object An options object for configuring the Overlay. This object MUST have either `src` or `html` set. (Required)
opts.heading.title string Your overlay's title
opts.heading.visuallyhidetitle boolean If you want to provide a different title style, this option will prevent the title span from being added to the overlay. (In this case the title is only used for aria labelling) Default: false.
opts.heading.shaded boolean Whether to shade the background of the header. Default: to false
opts.modal boolean Whether the overlay should have modal behaviour or not. Setting this as true will add a translucent shadow between the page and the overlay
opts.compact boolean If true, the .o-overlay--compact class will be added to the overlay that reduces heading font-size and paddings in the content.
opts.src string Either a url from which HTML to populate the overlay can be loaded, or a querySelector string identifying an element from which the textContent should be extracted.
opts.html string String or HTMLElement. Raw HTML (cannot be set declaratively)
opts.trigger string querySelector expression or HTMLElement. When there's a trigger set, a click event handler will be added to it that will open or close the overlay accordingly. (cannot be set declaratively)
opts.zindex string Value of the CSS z-index property of the overlay. Default set via CSS: '10'
opts.preventclosing boolean Prevents closure of overlay via standard x button or escape key. For use when you are directing the user to somewhere else. Only valid with modal set to true.
opts.customclose boolean If you do not use the heading, but want to provide a close button in your html / src (with a class of o-overlay__close), setting customclose to true will attach o-overlay's close handler function to that button.
opts.parentnode string Should be a query selector for a DOM element. If set, the overlay will be appended as a child of this rather than the document body or target. If multiple nodes are matched, it will use the first. If nothing matches this selector, the body will be used.
opts.nested boolean If set to true, the resize, escape, and layer listeners will not be set up. This boolean should be used in conjunction with the parentnode setting to allow an overlay to be positioned within a DOM element rather than overlaid on top of everything. Default: false.
opts.nofocus boolean If set to true, the tabindex will not be set on the wrapper element. Useful in conjunction with the nested and parentnode options. Default: false.
opts.fullscreen boolean If set to true, the overlay will display full screen. This overlay disables scroll on the underlying document and is dismissible with the back button.

Methods

  • show - (instance) Show the overlay

Links

new Tooltip(tooltipEl, opts)

Represents a tooltip.

parameter type default description
tooltipEl HTMLElement The tooltip element in the DOM (Required)
opts object An options object for configuring the tooltip (Optional)

Methods

  • getOptions(tooltipEl) - (static) Get the data attributes from the tooltipEl. If the tooltip is being set up declaratively, this method is used to extract the data attributes from the DOM.
  • checkOptions(opts) - (static) Check the options passed in are valid, and that the required option (target) is present
  • render - (instance) Render the tooltip. Adds markup and attributes to this.tooltipEl in the DOM
  • show - (instance) Show the tooltip. Adds event handlers for clicks, touches, keypresses and viewport resizes. Uses FTDomDelegate to implement the event delegate pattern. Calls DrawTooltip.
  • toggle - (instance) Toggle the tooltip open and close
  • closeAfter(seconds) - (instance) Close the tooltip after set time
  • showAfter(seconds) - (instance) Show the tooltip after set time
  • destroy - (instance) Destroy the tooltip.
  • close(...) - (instance) Close the tooltip. (Visually hide it and remove event listeners)
  • closeOnKeyUp(ev)
  • resizeListener - (instance) Respond to resize events. Redraw the tooltip in case the target has moved.
  • drawTooltip - (instance) Calculates the best place to position the tooltip based on space around the target and a preference set by the app developer.
  • width
  • height

Links

new Typography(typographyEl, opts)

Class constructor.

parameter type default description
typographyEl (optional) HTMLElement The root element to apply typography classes.
opts (optional) object {loadOnInit: true, rejectOnFontLoadFailure: false, fontLoadedCookieName: 'o-typography-fonts-loaded'} An options object for configuring o-typography.

Methods

Links

<anonymous>~customSource

Inner Property

Type

  • Source

Links

Autocomplete#mapOptionToSuggestedValue

Instance Property

Type

  • MapOptionToSuggestedValue

Links

Autocomplete#options.source(query, populateOptions)

Static Method

parameter type default description
query string Text which was typed into the autocomplete by the user
populateOptions PopulateOptions Function to call when ready to update the suggestions dropdown

Returns

  • void

Links

Autocomplete#options.source~callback(options)

Inner Function

parameter type default description
options Array.<string> The options which match the rext which was typed into the autocomplete by the user

Returns

  • void

Links

templates.suggestion(option)

Static Method

Used when rendering suggestions, the return value of this will be used as the innerHTML for a single suggestion.

parameter type default description
option * The suggestion to apply the template with.

Returns

  • string | undefined - HTML string to represent a single suggestion.

Links

templates.inputValue(option)

Static Method

Used when a suggestion is selected, the return value of this will be used as the value for the input element.

parameter type default description
option * The suggestion which was selected.

Returns

  • string | undefined - String to represent the suggestion.

Links

Autocomplete#suggestionTemplate(suggestedValue)

Instance Method

Used when rendering suggestions, the return value of this will be used as the innerHTML for a single suggestion.

parameter type default description
suggestedValue string The suggestion to apply the template with.

Returns

  • string - HTML string to be represent a single suggestion.

Links

<anonymous>~characters

Inner Property

Type

  • Array.<CharacterHighlight>

An array of arrays which contain two items, the first is the character in the suggestion, the second is a boolean which indicates whether the character should be highlighted.

Links

Autocomplete.getDataAttributes(autocompleteEl)

Static Method

Get the data attributes from the AutocompleteElement. If the element is being set up declaratively, this method is used to extract the data attributes from the DOM.

parameter type default description
autocompleteEl HTMLElement The component element in the DOM

Returns

  • object - An options object which can be used for configuring the component

Links

Autocomplete.init(rootElement, options)

Static Method

Initialise o-autocomplete component/s.

parameter type default description
rootElement HTMLElement | string The root element to intialise the component in, or a CSS selector for the root element
options (optional) object {} An options object for configuring the component

Returns

  • Autocomplete | Array.<Autocomplete> - The newly constructed Autocomplete components

Links

Banner#render

Instance Method

Render the banner.

Returns

  • void

Links

Banner#open

Instance Method

Open the banner.

Returns

  • void

Links

Banner#close

Instance Method

Close the banner.

Returns

  • void

Links

Banner#buildBannerElement(bannerElement)

Instance Method

Build a full banner element. This is used when no banner or a partial banner exists in the DOM.

parameter type default description
bannerElement (optional) HTMLElement The banner element to build around

Returns

  • HTMLElement - Returns the new banner element

Links

Banner#buildCloseButtonElement

Instance Method

Build a close button element.

Returns

  • HTMLElement - Returns the new close button element

Links

Banner.getOptionsFromDom(bannerElement)

Static Method

Get the data attributes from the bannerElement. If the banner is being set up declaratively, this method is used to extract the data attributes from the DOM.

parameter type default description
bannerElement HTMLElement The banner element in the DOM

Returns

  • Object.<string, any> - - The options

Links

Banner#destroy

Instance Method

Undo the init method

Links

Banner.init(rootElement, options)

Static Method

Initialise banner components.

parameter type default description
rootElement (optional) HTMLElement | string The root element to intialise banners in, or a CSS selector for the root element
options (optional) object {} An options object for configuring the banners

Returns

  • Banner | Array.<Banner> - - The newly instantiated Banner (or Banners, if rootElement was not a banner)

Links

module.exports.message()

Static Method

Build a full message element. Used when there is no message element in the DOM.

parameter type default description

Returns

  • HTMLElement - Returns the new message element

Links

module.exports.closeButton

Static Method

Build a close button

Returns

  • HTMLElement - Returns a new element to close the message

Links

Message#render

Instance Method

Render the message.

Returns

  • void

Links

Message#open

Instance Method

Open the message.

Returns

  • void

Links

Message#close

Instance Method

Close the message.

Returns

  • void

Links

Message.getDataAttributes(messageElement)

Static Method

Get the data attributes from the messageElement. If the message is being set up declaratively, this method is used to extract the data attributes from the DOM.

parameter type default description
messageElement HTMLElement The message element in the DOM

Returns

  • object - - An object of options defined via data attributes on the message element

Links

Message.init(rootElement, opts)

Static Method

Initialise message component.

parameter type default description
rootElement HTMLElement | string The root element to intialise a message in, or a CSS selector for the root element
opts MessageOptions Options for customizing the message

Returns

  • Message | Array.<Message> - The newly constructed message component or components

Links

Overlay#show

Instance Method

Show the overlay

Fires Event

Links

oOverlay#event:ready

Type: object

Ready event

property type description
instance the firing instance

Links

Tooltip.getOptions(tooltipEl)

Static Method

Get the data attributes from the tooltipEl. If the tooltip is being set up declaratively, this method is used to extract the data attributes from the DOM.

parameter type default description
tooltipEl HTMLElement The tooltip element in the DOM (Required)

Returns

  • Object.<string, any> - a dictionary of options

Links

Tooltip.checkOptions(opts)

Static Method

Check the options passed in are valid, and that the required option (target) is present

parameter type default description
opts object An Object with configuration options for the tooltip

Returns

  • object - opts

Links

Tooltip#render

Instance Method

Render the tooltip. Adds markup and attributes to this.tooltipEl in the DOM

Links

Tooltip#show

Instance Method

Show the tooltip. Adds event handlers for clicks, touches, keypresses and viewport resizes. Uses FTDomDelegate to implement the event delegate pattern. Calls DrawTooltip.

Links

Tooltip#toggle

Instance Method

Toggle the tooltip open and close

Links

Tooltip#closeAfter(seconds)

Instance Method

Close the tooltip after set time

parameter type default description
seconds number how long to wait until closing

Links

Tooltip#showAfter(seconds)

Instance Method

Show the tooltip after set time

parameter type default description
seconds number how long to wait until showing

Links

Tooltip#destroy

Instance Method

Destroy the tooltip.

Links

Tooltip#close(...)

Instance Method

Close the tooltip. (Visually hide it and remove event listeners)

parameter type default description
_event any ignored
_target any ignored
fireCloseEvent boolean true should we fire the oTooltip.close event?

Returns

  • boolean - false

Links

Tooltip#closeOnKeyUp(ev)

Instance Method

parameter type default description
ev Event calls close on the tooltip if the key is Esc

Links

Tooltip#resizeListener

Instance Method

Respond to resize events. Redraw the tooltip in case the target has moved.

Links

Tooltip#drawTooltip

Instance Method

Calculates the best place to position the tooltip based on space around the target and a preference set by the app developer.

Returns

  • void - this function is recursive!

Links

Tooltip#width

Instance Method

Returns

  • number - the offset width of the tooltip element

Links

Tooltip#height

Instance Method

Returns

  • number - the offset height of the tooltip element

Links

Typography.getOptions(typographyEl)

Static Method

Get the data attributes from the typographyEl. If typography is being set up declaratively, this method is used to extract the data attributes from the DOM.

parameter type default description
typographyEl HTMLElement The typography element in the DOM (Required)

Returns

  • Object.<string, any> - An option dictionary

Links

Typography.checkOptions(opts)

Static Method

Check the options passed in are valid, otherwise set defaults

parameter type default description
opts object An Object with configuration options for typography

Returns

  • object - opts

Links

Typography.init(rootElement, options)

Static Method

Initialise o-typography.

parameter type default description
rootElement HTMLElement | string The root element to intialise o-typography on, or a CSS selector for the root element
options (optional) object {} An options object for configuring o-typography

Returns

  • Typography - The Typography instance

Links

module.exports.message()

Static Method

Build a full message element. Used when there is no message element in the DOM.

parameter type default description

Returns

  • HTMLElement - Returns the new message element

Links

Status
active
Switch component view

GitHub: o-message@5.4.1

Install o-message

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

If using the npm package manager for a Manual Build, run npm install --save-peer "@financial-times/o-message@^5.4.1".

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: #origami-support
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: #origami-support
Email: origami.support@ft.com