Running locally

Please run on node 16: nvm install 16 nvm use 16

You need the gulp-cli installed globally: npm install -g gulp-cli

Make sure you are using the correct version of node with NVM: run nvm use in the root of the repo. If you don't have nvm installed, add it: brew install nvm.

Install node modules: npm i

To run locally: npm start or gulp.

Test harness

When the dotcom team makes changes to the website, the local test harness needs to be updated to reflect the new reality.

Update article and DCR templates in test harness:

npm run update-harness

If the script doesn't work, that's an indication that there has been a breaking change on the website. In that case, try to find out what has changed and talk to the dotcom team. If the change does not affect the working of interactives but just the working of the script, then the harness/update-harness.js script needs to be updated.

Create a new atom

Duplicate an existing atom. Remember to change the path in the server/render.js file to point to the html file in the new atom.

Deploy to S3

To deploy to the Interactives S3 bucket you need AWS credentials for the Interactives account in your command line. You can get these from the Guardian's permissions manager system Janus. You need to be assigned these permissions and be on a Guardian network or VPN to see them on Janus.

Fill out config.json:

{
    "title": "Title of your interactive",
    "docData": "Any associated external data",
    "path": "year/month/unique-title"
}

Deploy: gulp deploylive

Get the deployed links: gulp url

The link can be pasted into a Composer file

Testing in apps

To test on the Guardian apps - follow our Testing in Apps guide here

To test with dark mode on apps - see Testing in Dark Mode

Reusable React components

If your project uses React and is likely to use generic web components like search bars etc, it might save time to use the Digital Team's resuable components library. Intro to their components library here.

Loading resources (e.g. assets)

Resources must be loaded with absolute paths, otherwise they won't work when deployed. Use the template string <%= path %> in any CSS, HTML or JS, it will be replaced with the correct absolute path.

<img src="<%= path %>/image.png" />

.test {
    background-image: url('<%= path %>/image.png');
}

var url = '<%= path %>/image.png';

Using the ScrollyTeller module

The ScrollyTeller module is written as a class. You can check the scrollyteller-example branch for a full example.

Import it as normal into your project

import ScrollyTeller from "./scrollyteller"

Instantiate a new instance of it and pass in a config object

const scrolly = new ScrollyTeller({
    parent: document.querySelector("#scrolly-1"),
    triggerTop: 1/3, // percentage from the top of the screen that the trigger should fire
    triggerTopMobile: 0.75,
    transparentUntilActive: true
});

Add your trigger points:

scrolly.addTrigger({num: 1, do: () => {
    console.log("Console log 1");
}});

And finally start off the scroll listener:

scrolly.watchScroll();

You'll also need to comment in the _scrolly.scss code in main.scss, as well as structuring your HTML in the following way:

<div id="scrolly-1">
    <div class="scroll-wrapper">
        <div class="scroll-inner">
            <svg id="data-viz">
            </svg>
        </div>
        <div class="scroll-text">
            <div class="scroll-text__inner">
                <div class="scroll-text__div">
                    <p>1</p>
                </div>
            </div>
            <div class="scroll-text__inner">
                <div class="scroll-text__div"> 
                    <p>2</p>
                </div>
            </div>
            <div class="scroll-text__inner">
                <div class="scroll-text__div">
                    <p>3</p>
                </div>
            </div>
        </div>
    </div>
</div>

Using ScrollyTeller Progress code

This module should do what the module above but also returns two numbers - one the total progress of the scrolly teller from 0 to 1, 1 being scrolling complete, and also the progress within any given section or box, generated by the scrolly.gradual function.

In your app.js file you'll need to do something like this.

const scrolly1 = document.querySelector("#scrolly-1")

const callback = () => console.log("do something") 

const scrolly = new ScrollyTeller({
    parent: scrolly1,
    triggerTop: 1/3, // percentage from the top of the screen that the trigger should fire
    triggerTopMobile: 0.75,
    transparentUntilActive: true,
    callback:callback,
    overall: () => {}
})

scrolly.gradual( (progressInBox, i, abs, total) => {
        console.log("in box progress", progressInBox)
})

scrolly.overall((overallProgress) => {
    console.log("overall progress?", overallProgress)
})


// And finally start off the scroll listener
scrolly.watchScroll()

maplibre-tiles