Skip to content

Latest commit

 

History

History
90 lines (61 loc) · 3.39 KB

interactives.md

File metadata and controls

90 lines (61 loc) · 3.39 KB

This document explains how to create interactive content on theguardian.com.

Interactives

An interactive comprises of a stand-alone javascript application wrapped in an AMD interface compatible with the next-gen project.

The interactive AMD module must return a function called boot.

What the interactive modules does after this is largely up to whoever is writing it.

This module can be uploaded in to s3 along with the rest of the interactive application and associated assets.

Here is a simple boilerplate using this pattern.

define(['your/dependencies'], function (dependency) {
    return {

        /**
         *
         * @param el        : The Element of the interactive that is being progressively enhanced. 
         * @param context   : The DOM context this module must work within.
         * @param config    : The configuration object for this page. 
         *
        **/

        // 'boot' is a standard interface for our application to start the interactive
        boot: function (el, context, config) {

                // do something to bootstrap the interactive

            }
        }
    });

Embedding the interactive in a page

Embedding the interactive in a page is the same as today. A page is created in r2, a URL is assigned, and an editor can publish it, at which point it will appear in the Content API.

When the page is delivered to the user the frontend code scans the DOM for interactives and loads each one.

Currently any URL with the ng-interactive will be routed to the interactive server.

Examples

Note how, in each of these examples, there is a <figure> element in the source of the HTML with a data-interactive attribute.

Note, also how, in your web inspector network panel, the boot.js file is loaded, and subsequently loads the interactive application.

Notes

Previewing interactives on a localhost

The simplest way of previewing the interactive content on non-production environments is to run the applications server locallly.

Follow instructions on the project README.

Composer

Composer is used to write (i) a basic accessible description of the interactive from within an article, (ii) define the URL to an interactive application associated with that block.

For example, such a block might look like this as it comes out of Content API:-

<body>
    <h1>Headline</h1>
    <p>
        Article paragraph that has been written in Composer.
    </p>

    <!-- An accessible description of the interactive -->
    <figure class="interactive" data-interactive="http://path/to/interactive/boot.js">
        ...
        <caption>
            This is a chart describing the most polluted roads in London. 
        </caption>
    </figure>
    ...
</body>