@financial-times/x-teaser

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

Feature	Type	Notes
showMeta	Boolean
showTitle	Boolean
showTitlePrefix	Boolean
showStandfirst	Boolean
showPremiumLabel	Boolean
showExclusiveLabel	Boolean
showStatus	Boolean
showImage	Boolean
showByline	Boolean	Takes precedence over headshot
showBylineHeadshot	Boolean
showHeadshot	Boolean	Takes precedence over image
showVideo	Boolean	Takes precedence over image or headshot
showGuidance	Boolean	Show video captions guidance
showRelatedLinks	Boolean
showCustomSlot	Boolean
showPromotionalContent	Boolean

General Props

Property	Type	Notes
id	String	Content UUID
url	String	Canonical URL
relativeUrl	String	URL path, will take precendence over url
type	String	Content type (article, video, etc.)
indicators	indicators
dataTrackable	String	Tracking data for the teaser

Meta Props

Property	Type	Notes
metaPrefixText	String	Deprecated. When metaLinks property is present, this text is not displayed in the tag. It is being phased out in favour of titlePrefix, which will be used more sparingly
metaSuffixText	String
metaLink	meta link	Deprecated - use metaLinks property instead
metaAltLink	meta link	Deprecated - use metaLinks property instead
metaLinks	Array of [ string, string ]	Array of [linkText, relativeUrl]
promotedPrefixText	String	Will take precedence over links
promotedSuffixText	String

Title Props

Property	Type	Notes
title	String
titlePrefix	String
altTitle.	String	Used for testing content variations

Standfirst Props

Property	Type	Notes
standfirst	String
altStandfirst	String	Used for testing content variations

Status Props

Property	Type	Notes
publishedDate	String, Number, Date	Last published date
firstPublishedDate	String, Number, Date
useRelativeTime	Boolean	Display time since publish
status	String	Live blog status

Image Props

Property	Type	Notes
image	media
imageSize	String	XS, Small, Medium, Large, XL or XXL
imageLazyLoad	Boolean, String	Output image with data-src attribute. If this is a string it will be appended to the image as a class name.
imageHighestQuality	Boolean	Calls image service with "quality=highest" option, works only with XXL images
imageOptions	Object	Calls Image Service with specified props, takes precedence over other image options such as imageSize and imageHighestQuality

Byline Props

Property	Type	Notes
byline	Array of [string, string(optional), string(optional)]	[text, relativeUrl, headshotUrl][]

Headshot Props

Property	Type	Notes
headshot	String	Only displayed if showHeadshot and columnist indicator is true
headshotTint	String	See the image service API for usage

Video Props

Property	Type	Notes
video	media	Requires o-video to create a video player
systemCode	String	Required by o-video to pass with requests.
	Should be the Biz-Ops code for the implementing system

Related Links Props

Property	Type	Notes
relatedLinks	Array of link

Context Props

Property	Type	Notes
headlineTesting	Boolean	Enables alternative content for headline testing
parentLabel	String	Shows the alternative meta link when the label matches
parentId	String	Shows the alternative meta link when the ID matches

Variant Props

Property	Type	Notes
layout	String	"small", "large", "hero", or "top-story"
theme	String	Package theme, setting this will override any other indicators
parentTheme	String	Theme inherited from any parent package
modifiers	String[]	Extra modifier class names to append

Meta Link Props (Deprecated)

Property	Type	Notes
prefLabel	String
url	String	Canonical URL
relativeUrl	String	URL path, will take precedence over url

Link Props

Property	Type	Notes
id	String	Content UUID
url	String	Canonical URL
relativeUrl	String	URL path, will take precedence over url
type	String	Content type (article, video, etc.)
title	String

Media Props

Property	Type	Notes
url	String	Content UUID or, in the case of images, data: or blob: URL
width	Number
height	Number

Indicator Props

Property	Type	Notes
accessLevel	String	"premium", "subscribed", "registered", or "free"
isOpinion	Boolean
isColumn	Boolean
isPodcast	Boolean
isEditorsChoice	Boolean
isExclusive	Boolean	Controls whether the Exclusive badge is displayed
isScoop	Boolean

Special Styling Props

Property	Type	Notes
allowLiveTeaserStyling	Boolean	Apply o-teaser--live class to Container. Consumers need to include the o-teaser styling in their applications too.

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 })