Origami Frontend Components & Services

Readme: o-topper

o-topper is experimental. This component is not guaranteed to be ready for production use, and the API should be considered unstable.

This component is for displaying header sections at the top of articles

v1 Usage Warning

Use of this component is not recommended outside FT.com / app.ft.com. The Javascript helper which currently extracts themes, colors, and other topper display data is deeply tied to the FT.com content store and includes hardcoded UUIDs and business logic. In future this will be moved into another layer of the FT.com stack, and the new configuration used to control topper display and functionality will be documented, at which stage this topper will be more suitable for wider use.

Usage

Markup

The basic markup structure for a topper will look something like this:

<div class="o-topper o-topper--basic o-topper--color-paper">
    <div class="o-topper__content">
        <div class="o-topper__tags">
            <a href="https://www.ft.com/german-election" class="o-topper__topic">German election</a>
        </div>
        <h1 class="o-topper__headline">
            Merkel reaches ‘grand coalition’ breakthrough with Social Democrats
        </h1>
        <div class="o-topper__standfirst">Move raises hopes of end to political deadlock that has gripped Germany since September</div>
    </div>

    <div class="o-topper__background"></div>
</div>

Toppers support a wide array of elements and can be customised using several themes and background colors. For a full list of examples, including example markup, see o-topper in the Registry.

Supported elements

Element Use case
.o-topper__content Main content area of topper. Required parent of all elements except __visual and __background.
.o-topper__tags Wrapper element for the article concept tag elements __brand, __topic and __opinion-genre.
.o-topper__brand A concept tag that represents a brand, e.g. "The Big Read".
.o-topper__topic A concept tag that represents a topic or generic concept.
.o-topper__opinion-genre A concept tag that represents the abstract Opinion genre.
.o-topper__columnist Wrapper element for __columnist-name. Should be placed below the headline and standfirst.
.o-topper__columnist-name Represents the columnist that wrote an Opinion genre article.
.o-topper__headline The main headline of the article.
.o-topper__standfirst A short introduction to the article.
.o-topper__background Element used to display the editorially-chosen colored background of the topper. Must be empty.
.o-topper__visual Wrapper for the visual elements __picture and __image. Should be a <figure> tag.
.o-topper__picture A <picture> tag visual element.
.o-topper__image An <img> tag visual element, usually used as fallback for a <picture>.
.o-topper__image-credit Element showing credit/copyright for the __picture or __image. Should be a <figcaption> tag.

Themes

These themes affect the layout and visual style of all elements. See the demos for examples.

.o-topper--basic
.o-topper--branded
.o-topper--opinion
.o-topper--full-bleed-image-left
.o-topper--full-bleed-offset
.o-topper--split-text-left
.o-topper--split-text-center

Colors

These colors affect the background of the .o-topper__background and .o-topper__visual elements, and select a contrasting text color for all other elements. See o-colors for examples of the colors.

.o-topper--color-paper
.o-topper--color-wheat
.o-topper--color-white
.o-topper--color-black
.o-topper--color-claret
.o-topper--color-oxford
.o-topper--color-slate
.o-topper--color-crimson
.o-topper--color-sky
.o-topper--color-velvet

Sass

As with all Origami components, o-topper has a silent mode. To use its compiled CSS (rather than incorporating its mixins into your own Sass) set $o-topper-is-silent : false; in your Sass before you import the o-topper Sass:

$o-topper-is-silent: false;
@import 'o-topper/main';

Using Sass mixins

Javascript

This component includes a Javascript helper, which should be used to select the correct topper themes and colors, as well as other topper-overriden data, given a particular JSON-formatted FT article (such as from the Content API).

const {mapContentToTopper} = require('o-topper');

const topper = mapContentToTopper(ftArticle);

Topper data

Data returned by the topper helper should be used in the product's templates. Other keys may be returned but should not be relied on as documented behaviour.

Key Usage
headline Should be used in place of the standard article headline
standfirst Should be used in place of the standard article standfirst
modifiers Should be included as o-topper--[modifier] classes on the o-topper wrapper element
backgroundColor Should be included as an o-topper--color-[color] class on the wrapper element
themeImageRatio Used to differentiate split and full-bleed topper images
includesImage Use to disable main article image to prevent duplicate images when topper includes one
largeHeadline Indicates whether to use o-topper__headline--large on o-topper__headline

Contact

If you have any questions or comments about this component, or need help using it, please either raise an issue, visit #ft-origami or email Origami Support.

Licence

This software is published by the Financial Times under the MIT licence.

Switch component view

GitHub Repository

Install o-topper

If using the Build Service, add o-topper@^2.3.2 to your script and link tags.

If running a Manual Build, run bower install --save "o-topper@^2.3.2".

Help & Support

o-topper is maintained directly by the Origami team. If you have any questions about o-topper or Origami in general, we are happy to help. 😊

Slack: #ft-origami
Email: origami.support@ft.com

Feedback / Issues

To report a bug or request features please create an issue on Github. For support or general feedback please get in touch 😊

Slack: #ft-origami
Email: origami.support@ft.com