Serial Navigation

The Serial Nav component is a useful way to advertise the existence multiple stories (whether they actually are serial episodes or not). The component is delivered by asset swap and is configured by an external json file.

Tip

All links in your JSON can be absolute since they are converted to relative links programmatically for easy sharing across the network.

Asset swap

As with all swapped-asset components, it is a best practice to create a presto asset that serves a similar function as the serial nav, so that readers on distributed platforms can have a similar experience. In this case, the presto asset probably should be an embed with spike links to the next and previous story in the series.

Configuring JSON for the episodes

The primary driver behind the serial nav is an external json file, which lists all the episodes. It can be uploaded via the in-depth upload feature, and should be an array of objects:

[
    {
        "number": 1,
        "title": "Part One",
        "link": "https://www.northjersey.com/in-depth/news/2019/03/27/nj-charter-schools-nj-tax-money-disappearing/2139903002/",
        "isLive": true
    },
    {
        "number": 2,
        "title": "Part Two",
        "link": "https://www.northjersey.com/in-depth/news/2019/03/27/nj-charter-schools-nj-tax-money-disappearing/2139903002/",
        "isLive": false
        "absolute": true
    }
]

You can include as many episodes (or stories) as you need. Separate them with commas.

Required configuration

For each episode, there are four required properties:

Value Type Purpose Default
number number The order of the episodes, with the first episode being 1. Regardless of the order the episodes are presented in the JSON, the episodes will be ordered by this value. -
title string This is the text for each episode as it will appear in the nav. The best titles will be no longer than a few words each. -
link string The production link for the story. Links that fail validation (because of typos or other reasons) will be skipped. -
absolute Boolean By default, links are rendered as relative (without domains). If this is set to true then the whole link is used. false
isLive true or false If the story is live (true), a link will be rendered. If not (false), the episode title will render with the coming soon text. false

Tip

If you get errors trying to upload the file, try checking your data for mistakes/errors using any of the myriad JSON tools available online, such as JSONLint. The necessary formatting/syntax is specific in certain ways and writing data like this can be tricky. Don't hesitate to reach out in the In-Depth channel in Microsoft Teams for help.

Configuring the nav in In-Depth

Like many In-Depth features, the serial nav is a swapped asset: It replaces a presto asset. It's probably best to start with a Presto embed containing a link to a project landing page. If there isn't one (which is fine, too) then Perhaps just collecting the links of the stories in the project. Doing this ensures that readers on AMP, Apple News and Facebook Instant Articles, are aware of the whole project, which is the purpose of the serial nav.

Tip

You don't need a published link to put an embed in the story. You can use a placeholder until the published link is available.

Example configuration:

{assets.6756576789768}
storytellingComponent: serialnav
layout: center-well
kicker: A series in five parts
comingSoonText: Coming soon
iconUrl: https://www.gannett-cdn.com/usat-storytelling/bergen-charter-schools/NJ_Bergen_Badge_Grdnt_FullClr_RGB.svg
jsonUrl: https://www.gannett-cdn.com/usat-storytelling/bergen-charter-schools/bergen-serial-data.json
align: center
{}

Configuration options

Value Purpose Required Default
swapID The asset id of the embed to be replaced with the serial nav Yes -
storytellingComponent This is required to be "serialnav" to activate the serial nav. Yes -
jsonUrl The absolute link (begins with https://) to the episode data. (You can get that from the In-Depth asset uploader) Yes -
layout Standard layout options are limited to only center-well and full-width No full-width
kicker The label for the nav No -
comingSoonText How unavailable episodes will be labeled. No "Coming soon"
iconUrl Want a badge or other icon in the nav? Put it's CDN url here. No -
align The direction the text and icons align. No center

Caution

The chapter highlighting (as in Part One, above) will not work until the stories are live.

What about AMP and Apple News?

The serial nav will not appear on any platform other than Gannett websites and mobile apps. Be sure the embed asset you target contains similarly useful information.