Toppers

A topper is the first thing a user sees when opening a story. It should entice, it should inform, and if nothing else, it should get a user moving down the page and into the story.

Much of what is described in this section can be seen in the demos. See examples of what's possible here: https://lab-microservices.production.gannettdigital.com/lab-microservices/in-depth/demos/#toppers

Configuration

As with all things In-Depth, toppers are configured using ArchieML and have their own block inside the In-Depth editor:

{​​​​​storyTopper}​​​​​
// configure options here...
{​​​​​}​​​​​

Visual elements

The most important part of a topper is the visual element. In-Depth toppers can take an image or a looped, silent video. Either requires the file(s) be stored on the CDN and the full/absolute path ... you should be able to put the file's CDN path into a browser and see the image/video — if you can't, then it's not correct.

What type of file should I use?

Images should be JPG for photographs or illustration with photos, PNG for non-photo illustrations or SVG for vector drawings. Videos should be MP4. They all should be stored on the CDN. This can be done using upload panel.

Example config:

{​​​​​​​​​storyTopper}​​​​​​​​​
image: https://gannett-cdn.com/path/to/image.jpg
video: https://gannett-cdn.com/path/to/video.mp4
{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​

If a video and an image are configured in the same topper, the video will not display.

Using different images for different devices

You can set a specific image for different pixel width "breakpoints. It is a best practice to include an alt-text description of your image. Describe what is in the photo as if the reader cannot see it.

Example config:

{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​storyTopper}
microImage: https://gannett-cdn.com/path/to/very-small-image.jpg
mobileImage: https://gannett-cdn.com/path/to/mobile-sized-image.jpg
tabletImage: https://gannett-cdn.com/path/to/larger-image.jpg
desktopImage: https://gannett-cdn.com/path/to/very-large-image.jpg
topperImageAltText: This is what is in the image
{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​

How big should my images be?

Images are scaled to fit every screen, and won't fit perfectly inside the topper on every device.  However, you can use the dimensions below as a guideline to maximize visibility of your image. You might need to experiment a bit to get the exact look you want. Micro and mobile images are strongly vertical. The tablet image is closer to square and the desktop image is a landscape rectangle. Regardless of the image's actual size, each topper image will be scaled to the widths listed below automatically to ensure speedy page load.

Only the mobile and desktop are required, but employing all four will make a cleaner, smoother presentation. The mobile size is the default.

For the flat topper: The recommended image dimensions are slightly different for the flat topper. For most devices/widths, the flat topper image uses a 21x9 ratio, which ends up being approximately 56% of screen height:

How can I use different videos on different screens?

Just like using multiple images in toppers, In-Depth allows you to set as many as three different video backgrounds for different screen widths (phone, tablet and desktop). As with images, the videos must be hosted on the CDN, and absolute urls are required. The following breakpoints are supported:

The tablet breakpoint is optional and will default to the mobile video.  A single poster image (the image displayed while the video is downloading) also is supported, using poster, and is strongly recommended.

It is possible to adjust the breakpoints, if it is really necessary. Talk to a Storytelling Studio representative if you have such a need.

Example config:

{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​storyTopper}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
videoMobile: https://media.gannett-cdn.com/28911775001/28911775001_5979107043001_5979105635001.mp4
videoTablet: https://www.gannett-cdn.com/usat-storytelling/guerrero/loop-blend_wide-light-2.mp4
videoDesktop: https://www.gannett-cdn.com/labs/deadly-deliveries/topper-opts/grid-line-topper200.mp4
poster: https://www.gannett-cdn.com/usat-storytelling/maternal-harms/images/heroFull.png
{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​

How can I add an overlay image to my visual?

Overlays work well when they are PNGs that use transparency. They can be used to add frames around the visual or to add a texture.

{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​storyTopper}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
overlay: https://gannett-cdn.com/path/to/very-large-image.jpg
{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​​

This is particularly useful with the notch topper. This design is used here.

How do I adjust the color scheme?

The topper will use, by default, the theme color defined in the {​​​​​​​​theme}​​​​​​​​ block. To override this with a valid CSS color (hex, named or RGBA only) in the topper only, use

{​​​​​​​​​​​​​​​storyTopper}​​​​​​​​​​​​​​​​​​​​​​​​​​​​​
themeColor: <valid CSS color>
{​​​​​​​​​​​​​​​​​​​​​​​​​​​​​}