@financial-times/n-scrollytelling-image NPM

Scrollytelling Image Component (@n-scrollytelling/components/image)

This is a component to help with displaying Scrollytelling images.

Scrollytelling images are a sequence of images that scroll and fade into each other, sometimes with overlay text that scrolls over the images.

Something similar to these:

scrollytelling-example

scrollytelling-images

Purpose

This component encapsulates everything we need to produce a Scrollytelling image experience. To achieve this, the package has two entry points - one for server-side content transforms, and one for client-side rendering.

Installation

Install the package in your project directory with the relevant command:

// with npm
npm install @Financial-Times/n-scrollytelling-image

// with yarn
yarn add @Financial-Times/n-scrollytelling-image

Usage

Server-side usage

The server side handles the transforms of XML to HTML. It's been designed to work with Next ES-Interface. When the server-side entry point is used, this package accepts and returns a cheerio instance.

E.g.:

import scrollytellingImages from '@n-scrollytelling-image';
or
const scrollytellingImages = require('@n-scrollytelling-image').default;

const scrollyImages = scrollytellingImages(cheerioInstance);

scrollyImages.html();

Client-side usage

The client side handles the application of styles and enhanced JavaScript. When the client-side entry point is used, this package accepts the article body and returns it with the enhanced JavaScript applied, and the consumer pulls in the styling.

JavaScript:

import * as scrollytellingImage from '@financial-times/n-scrollytelling-image';

scrollytellingImage.init(articleBody);

Styling:

@import '@financial-times/n-scrollytelling-image/main';

Demos

The demos are published onto our public GitHub Pages version of Storybook: Link to Storybook demos

To build the demos locally, run:

npm run demo-local -- --component=image

Testing

When writing tests, they should be explicit and comprehensive, so that they can double as documentation for people looking to understand the code.

To run the tests: jest components/image to run tests just for Image component, or npm test to run all components. Note: This should theoretically be npm test components/image, but we're running jest through dotcom-tool-kit which doesn't seem to understand that command with our current set-up - please update this when the issue is resolved

Releasing

To release a new version of the package, create a new Github Release prefacing the tag with n-scrollytelling-image-, and using Semantic Versioning conventions to decide the version number. NPM will then automatically deploy a new package version.

If the client side of this package is changed, the new package version will need to be used in Next Article. If the server side of this package is changed, the new package version will need to be used in Next ES-Interface.

How it works

The basic functionality of n-scrollytelling-image is to create Scrollytelling articles. To do this, it receives an XML input, transforms it into an HTML output, and applies styles and enhanced JavaScript behaviour. This package was designed to work within the existing FT architecture, and has two entry points - server-side and client-side.

For a more in-depth explanation of the technical details, see this additional doc.

Server side

The server side of this package integrates with and accepts input from Next ES-Interface. Next ES-Interface uses the Scrollytelling transforms to turn the XML input into HTML with a series of Cheerio actions, which do things such as identifying the image blocks, creating the HTML structure, and applying the extra classes that relate to the Theme and Options specified by the XML. These actions can be found in transformUsingCheero.js. If the server side of this package is changed, the new package version will need to be used in Next ES-Interface.

Expected Schema

To see a working example of the expected schema, view the .xml files contained in /stories. To see the corresponding HTML output, build the Storybook demos locally (see Demos for details on how to do this) and view the corresponding .html files.

Discussions and documentation regarding the schemas can also be found in the Github Issues section.

See the Themes doc and Options doc for more information about the 'Themes' and 'Options' parts of the schema.

Error handling

It uses n-logger to log server-side errors to Splunk.

Client side

After the server side has transformed the XML into HTML, the consumer handling the front end (e.g. Next Article, the App or the Edit) uses the client side to handle the scrolly functionality. It constructs a ScrollytellingImage class (as seen here) which instantiates Slide classes for each slide, and switches active slides as different slides scroll into the viewport. It also applies styling for Themes and Options using the class names applied by the Cheerio actions on the server side, using BEM methodology. If the client side of this package is changed, the new package version will need to be used in Next Article.

Error handling

It uses o-errors for client-side error handling.

Extra usage

Themes usage

Themes set the base styling for a Scrolly article, such as font style and spacing. A Theme is set by the theme attribute in the XML. For example, when an XML scrollable block has the theme="1" attribute, the attribute will be transformed into a data-scrollytelling-theme="sans" attribute, and the corresponding class names will be added to the HTML output of the server-side entry point of this package. This enables the correct client-side JavaScript and styles to be applied to the HTML to deliver that theme experience.

For detailed documentation on what Themes are available, refer to the Themes doc.

Options usage

Options are how we customise parts of the themes, such as changing the position of the slides or turning text into headings. When present in the XML input, they get transformed server-side into classes in the HTML output which are then used to change the client-side styling in the Scrollytelling article.

For detailed documentation on what Options are available, refer to the Options doc.

Contributing to the package

Creating themes

Themes set the base styling for a Scrolly article, such as font style and size. A new Theme will be required when the design for a new article style is significantly different to existing Themes. If what you're hoping to achieve is similar to an existing theme, you may want to create a new Option instead. When a new Theme is created, we will need to liase with Spark and Content & Metadata to ensure that all parts of the pipeline can allow the new Theme.

Make sure the Themes doc is updated to explain any new Themes.

Make sure any new Themes are covered by unit tests. Be explicit and comprehensive with the tests, so that they can double as documentation for people looking to understand the new Theme.

Creating options

Options are how we customise parts of the themes, such as changing the position of the slides or turning text into headings. For all Options, the schema needs to be agreed by all teams that will use it. In most cases, this will be Storytelling, Spark, and Content & Metadata. Examples of past schemas can be found in Issues. Use Issues to propose and document future schemas.

Make sure the Options doc is updated to explain any new Options.

Make sure any new Options are covered by unit tests. Be explicit and comprehensive with the tests, so that they can double as documentation for people looking to understand the new Option.

Troubleshooting

General tips

If a Scrollytelling article doesn't look how we expect, check the HTML using the elements tab of DevTools to see if the correct classes and data parameters are present. I.e., data-scrollytelling-theme="sans", class="n-scrollytelling__overlay-text-slide--position-right".
If we're outputting the wrong HTML, check the XML we're receiving to make sure it fits the schema we expect.