Origami Frontend Components & Services

Readme: o-gallery

A configurable content gallery. For carousels, slideshows and thumbnail strips.

Definitions

A shown item does not necessarily have to be selected, and vice versa.

The following wireframes show two example galleries: A) a gallery with single items per page, with a title and caption; B) a gallery with multiple items per page and no captions (ie, a thumbstrip). Galleries would often be used together in these forms to create a single coherent interface for viewing and navigating slideshows of images.

Wireframe

Browser support

Gallery supports the same browsers as FTScroller (which it uses for touch/mouse input and transition behaviour), but also adds graceful degradation for IE8 and IE9.

In IE8 and IE9 there is no option for touch input support and there are no transitions (items & pages will change instantly). Usage of the Polyfill service is necessary in IE, and you need to request the default set of polyfills and, if you want it to work on IE8, also add the DOMContentLoaded one.

Creating Galleries

Gallery content can come from either HTML already in the DOM, or data passed explicitly to Gallery javascript via a configuration object. See the declarative demo for an example of the HTML structure required.

In both cases there must be an root element already in the DOM to construct the Gallery in. The root element must not be set to display: none, either directly or via an ancestor element, otherwise the Gallery will be unable to calculate its item widths and will not work correctly.

Note: a Gallery may behave oddly when an ancestor element is set to display: table causing issues with the Gallery sizing (see https://github.com/Financial-Times/o-gallery/issues/44 for more details).

Galleries can be constructed in three ways:

  1. Declaratively from HTML source
  2. Imperatively from HTML source
  3. Imperatively from JS data

1. Declaratively from HTML source

With the HTML already in the page, the following method can be called to search for Gallery HTML elements and automatically construct a Gallery for each one:

var galleries = Gallery.init();

Any gallery objects that are constructed will be returned.

Alternatively, a o.DOMContentLoaded event can be dispatched on the document to auto-construct a o-gallery object for each element with a data-o-component="o-gallery" attribute:

document.addEventListener("DOMContentLoaded", function() {
    document.dispatchEvent(new CustomEvent('o.DOMContentLoaded'));
});

Optionally, a DOM element can be passed to limit the search to a particular area of the page:

var galleries = Gallery.init(document.getElementByClassName(".ft-article-body")[0]);

2. Imperatively from HTML source

With the HTML already in the page, a Gallery object can be constructed like so:

var gallery1 = new Gallery(document.getElementById('#gallery1');

An optional configuration object can be passed as second argument:

var gallery2 = new Gallery(document.getElementById('#gallery2', {
    // config options
});

3. Imperatively from JS data

With just an HTML container element already in the page, a Gallery object can be constructed by passing the content as data via the config object:

var gallery = new Gallery(document.getElementById('#gallery', {
    items: [ <itemObject>, <itemObject>, <itemObject> ...]
});

Where an itemObject can consist of the following properties:

content

Type: String (required)

The HTML content of the item.

caption

Type: String (optional)

The HTML content of the item's caption.

selected

Type: Boolean

Default: false

Whether this item is selected. If more than one item is set to be selected, then only the first one will be selected.

For example:

{
    content: '<img src="http://ft-static.com/image1.jpg" alt="Slideshow image 1">',
    caption: '<p>Slideshow caption text.</p>',
    selected: true
}

Configuration

Galleries can be configured by HTML data-attributes or the JS configuration object, or a combination of the two. Where both are supplied, the JS values will take precedence.

Once the config options have been gathered, the HTML data-attributes are added/updated to show the configuration actually in use.

Multiple items per page

HTML source: attribute data-o-gallery-multipleitemsperpage on root element

JS property: multipleItemsPerPage

Type: Boolean

Default: false

Sets whether multiple items should be allowed to show per page. For example a normal slideshow would set this to false, but its thumbnail strip would set it to true.

Sync ID

HTML source: attribute data-o-gallery-syncid on root element

JS property: syncID

Type: String

Default: o-gallery-[timestamp]

Sets the ID used in events fired and listened to by a Gallery instance. Setting two Gallery objects to the same sync ID will cause them to control each other - for example where Gallery 1 is a slideshow, and Gallery 2 is its thumbnail strip.

Touch

HTML source: attribute data-o-gallery-touch on root element

JS property: touch

Type: Boolean

Default: false

Controls whether touch events will be listened to. See ftscroller for more details.

Title

HTML source: Element inside container with a class of o-gallery__title.

JS property: title

Type: String

The [optional] Gallery title. Displayed in the top left of the viewport and remains in place for all items.

Captions

HTML source: attribute data-o-gallery-captions on root element

JS property: captions

Type: Boolean

Default: true

Whether captions will be shown at all. With this set to true, a blank area will always be shown for every item, even if there is no caption data for an item.

Caption min/max height

HTML source: attributes data-o-gallery-captionminheight, data-o-gallery-captionmaxheight on root element

JS property: data-o-gallery-captionmaxheight, captionMaxHeight

Type: Integer

Default: 24, 52

The height constraints of the caption area. The min value is used to position the caption area below the gallery item. If the content of the caption forces the caption height to increase, then it will increase upwards, in front of the gallery item, up to the maximum height set.

Events

The following events will be dispatched on the Gallery's root DOM element:

In IE8, these events will only be dispatched if the EventTarget API has been polyfilled.

API

Note that showing and selecting are two separate concepts and are independent of each other.

There must always be one item selected, even if the selected state is not made visible in the UI.

Each gallery item has an index number. Pages do not have index numbers as the number of pages can vary when a gallery has a variable width (e.g. in a responsive layout).

When a next/prev method is called, if there is no next or previous, then it will do nothing.

The desired behaviour of the left & right UI controls for single- and multiple-item-per-page galleries will be different. For example, in a slideshow (single item per page), the right arrow control should select and show the next item, but in a thumbnail strip (multiple items per page), it should show the next page without affecting what it selected.

The following simplified methods are provided to handle this logic:

These method may be useful for adding keyboard control to a Gallery.

Sass

By default the Sass is in silent mode, meaning there will be no CSS output.

If you're @importing the Sass into your product or component, and you want to turn off silent mode, then set the following Sass variable:

$o-gallery-is-silent: false;

If requesting the CSS from the build service, silent mode will automatically be switched off.

In silent mode, instead of the CSS classes listed below, use the mixins documented here.

Themes

By default, Gallery only provides the minimum styling for a Gallery to be functional - e.g. mostly just positioning, and the previous/next UI controls.

Two themes are provided: for slideshows and thumbnails.

To use the slideshow theme, set a 'o-gallery--slideshow' class on the root Gallery element:

<div class="o-gallery o-gallery--slideshow" data-o-component="o-gallery">

To use the thumbnails theme, set a o-gallery--thumbnails class on the Gallery root element:

<div class="o-gallery o-gallery--thumbnails" data-o-component="o-gallery">

If creating your own theme, see the Origami section on themes.

The following Gallery classes are applied to elements in the Gallery structure:

In addition to this, a aria-selected="true" attribute is set on the selected Gallery item. It is up to a product to use this attribute to apply styles as required. This class is only likely to be useful when multipleItemsPerPage is set to true. This class is also used to identify the initially selected item when constructing a Gallery from HTML source.

Themes must only be used with the default o-gallery classes.

Migration Guide

Migrating from v2.x.x -> v3.x.x

This update introduces the new major of o-colors. Updating to this new version will mean updating any other components that you have which are using o-colors. There are no other breaking changes in this release.


License

This software is published under the MIT licence.

Switch component view

GitHub Repository

Install o-gallery

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

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

Help & Support

o-gallery is maintained directly by the Origami team. If you have any questions about o-gallery 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