Configurable custom overlay box that can be used to show overlay windows. The overlays can also be switched to display differently on small screens.
o-overlay can be instantiated in two ways:
Set options as data- attributes on any element that has a o-overlay-trigger class, to create an overlay and open it when that element is clicked.
<button class="o-overlay-trigger" data-o-overlay-src="#overlay1-content" data-o-overlay-id="overlay1">Open!</button>
<script type="text/template" id="overlay1-content">
<p>Content of overlay</p>
</script>To activate overlays declared in markup, you can:
o.DOMContentLoaded event (which will also initialise all other compatible Origami modules on the page); oro-overlay#init([el]) (optionally pass a parent element to search for trigger elements, which will form its o-layers context. The default is document.body)The constructor function accepts two arguments:
var myOverlay = new Overlay('myOverlay', {
html: 'Hello world',
trigger: '.blah'
});heading: Object. Options for the Overlay header.title: String. Your overlay's title.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..shaded: Boolean. Whether to shade the background of the headermodal: Boolean. Whether the overlay should have modal behaviour or not. This will add a translucent shadow between the page and the overlay. Modal overlays also disable scroll on the underlying document. Default: true.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.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.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.html: String or HTMLElement. Raw HTML (cannot be set declaratively)class: String. The custom classes to apply to to the overlay e.g. o-overlay--my-modifier.trigger: String or HTMLElement. 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)zindex: String. Value of the CSS z-index property of the overlay. Default set via CSS: '10'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.customclose: Boolean. If you do not use the header, 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.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.nested: Boolean. If set to true, the resize and escape key 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.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.layer: Boolean. If set to true, the overlay will be treated as an o-layer, firing oLayers.new and oLayers.close events when created and destroyed, and closing itself when another oLayers.new event fires. You may want to set this to false if using a nested overlay. Default: true.The only option that must be set is either src or html. The html option can't be set as a data- attribute, and if you set both, the html one will override src.
For compact overlays, headings can't be shaded as this looks weird too.
Data- attributes have the same name as in the JSON format, but with dashes. So for src it will be data-o-overlay-src and for the heading.title it will be data-o-overlay-heading-title.
o-overlays will throw an error if the options aren't set correctly.
O-overlay contains styles for the container (eg border and shadow) and layout styles (to place the overlay above the page content). It does not come with typographic styles, background colours, or buttons. Implementing projects should add these.
o-overlay supports silent mode, so there are mixins for the different elements. If you want to get all the classes styled by default, you'll need to turn of silent mode:
$o-overlay-is-silent: false;getOverlays(): Returns an array of all overlays on the pageinit([el]): Instantiates Overlays for all o-overlay-trigger elements within el (or document.body if not specified)destroy(): Destroys all Overlay objects and unbinds event handlers from trigger elements.open: Display the overlay. Content is loaded every time the overlay is opened.close: Close (hide) the overlay.realign: Realign the overlay. Useful when overlay content changes whilst the overlay is open.We implement o-layers events:
oLayers.new: It's dispatched right before the layer appearsoLayers.close: It's dispatched right after the layer is removedWe also dispatch custom events:
oOverlay.ready: Dispatched when the overlay is loaded in the DOMoOverlay.destroy: Dispatched when the overlay is removed from the DOM.focus() function on an element when oOverlay.ready is dispatched to simulate the behaviour.@oOverlayCloseIcon mixin.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.
This software is published by the Financial Times under the MIT licence.