x-teaser

This module provides templates for use with o-teaser. Teasers are used to present content.

Installation

npm install --save @financial-times/x-teaser @financial-times/o-teaser

The x-engine module is used to inject your chosen runtime into the component. Please read the x-engine documentation first if you are consuming x- components for the first time in your application.

Concepts

Features

Because teasers are very complex with thousands of possible permutations the component has been split into logical groups of features. These are:-

• Meta, the element above the title categorising the content
• Title, the title of the content
• Standfirst, a subtitle or description of the content
• Status, the date of, or time since the content was published
• Related links, An additional list of links to related content
• Image, the poster image for the content
• Headshot, an image of the content author when content is published in their column
• Video, for video content able to play videos in-situ
• Custom slot, a free slot to insert custom components or markup
• Promotional content, a slot to insert promotional content of different types such as but not limited to: clips, interactive graphics, etc.

Indicators

Teasers display content but our content items are also decorated with hints and traits which further describe them. Content items may only be available to premium subscribers, excluded from syndication licenses, or selected as an editor's choice. This extra data may not always produce visible output, or be visible to all users. However, they can be used in addition to the content itself to make decisions with.

Rules

Because there are so many teaser properties some options can conflict. In these cases one option must take precedence over the others. These sitations are resolved by using a ruleset. A ruleset is a function which implements a series of conditions in order of precedence. When a condition evaluates to true it must return.

For example to decide which media type to display (a video, headshot, or image) we define the following ruleset:

const media = (props) => {
  if (props.showVideo && props.video && props.video.url) {
    return 'video'
  }

  if (props.showHeadshot && props.headshot && props.headshot.url && props.indicators.isColumn) {
    return 'headshot'
  }

  if (props.showImage && props.image && props.image.url) {
    return 'image'
  }
}

Usage

The components provided by this module are all functions that expect a map of teaser properties. They can be used with vanilla JavaScript or JSX (If you are not familiar check out WTF is JSX first). For example if you were writing your application using React you could use the component like this:

import React from 'react'
import { Teaser } from '@financial-times/x-teaser'

// A == B == C
const a = Teaser(props)
const b = <Teaser {...props} />
const c = React.createElement(Teaser, props)

All x- components are designed to be compatible with a variety of runtimes, not just React. Check out the x-engine documentation for a list of recommended libraries and frameworks.

Child components

All the sub-components used to build a complete teaser may be imported and used individually. Every component can be given the full set of teaser properties.

import { Title, Standfirst } from '@financial-times/x-teaser'

const TeaserIsh = (title, standfirst) => (
  <div className="teaser-ish">
    <Title title={title} />
    <Standfirst standfirst={standfirst} />
  </div>
)

TypeScript

A TypeScript definitions file is included which covers all of the properties expected by this component. You can use it like this:

import { TeaserProps } from './Props'

const props: TeaserProps = {}

Properties

As covered in the features documentation the teaser properties, or props, have also been split into logical groups. No props are mandatory and no defaults are set, but presets are available for common combinations. In cases where props conflict rules should decide which should take precedence. There is a TypeScript definition available for props.

Feature Props

General Props

Meta Props

Title Props

Standfirst Props

Status Props

Image Props

Byline Props

Headshot Props

Video Props

Related Links Props

Context Props

Variant Props

Meta Link Props (Deprecated)

Link Props

Media Props

Indicator Props

Special Styling Props

Presets

Because there are so many options presets are available for the most commonly used configurations, these are:-

• Small
• SmallHeavy
• Large
• Hero
• HeroNarrow
• HeroVideo
• HeroOverlay
• TopStory
• TopStoryLandscape

To use a preset import the presets property along with the teaser component and mix your chosen preset in with your other properties.

import { Teaser, presets } from '@financial-times/x-teaser'

const html = Teaser({ ...props, ...presets.Hero, showStatus: false })