x live blog wrapper

x-live-blog-wrapper

This module displays a list of live blog posts using x-live-blog-post component. It also connects to an event stream which provides updates for the list. Based on these update events this component will add, remove and update x-live-blog-post components in the list.

Quick Links

• GitHub code
• NPM
• Storybook

Installation

This module is supported on Node 12 and is distributed on npm.

npm install --save @financial-times/x-live-blog-wrapper

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.

Usage

The components provided by this module are all functions that expect a map of 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 { LiveBlogWrapper } from '@financial-times/x-live-blog-wrapper';

// A == B == C
const a = LiveBlogWrapper(props);
const b = <LiveBlogWrapper {...props} />;
const c = React.createElement(LiveBlogWrapper, 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.

Client side rendering

This component can be used at the client side.

import { LiveBlogWrapper } from '@financial-times/x-live-blog-wrapper';

<LiveBlogWrapper articleUrl="https://www.ft.com/content/live_blog_package_uuid"
    showShareButtons={true}
    id="live-blog-wrapper"
    posts={posts}
    />

Server side rendering and hydrating

When rendering this component at the server side, hydration data must be rendered to the document using Serialiser and HydrationData components which are provided by x-interaction.

To successfully hydrate this component at the client side, the id property must be provided when rendering it at the server side. x-interaction will add this id to the markup as a data-x-dash-id attribute. This property can later be used to identify the markup.

The consuming app needs to ensure that the id is unique.

import { Serialiser, HydrationData } from '@financial-times/x-interaction';
import { LiveBlogWrapper } from '@financial-times/x-live-blog-wrapper';

const serialiser = new Serialiser();

<LiveBlogWrapper articleUrl="https://www.ft.com/content/live_blog_package_uuid"
    showShareButtons={true}
    id="live-blog-wrapper"
    posts={posts}
    serialiser={serialiser} />
<HydrationData serialiser={serialiser} />

To hydrate this component at the client side, use hydrate() function provided by x-interaction.

import { hydrate } from '@financial-times/x-interaction';

hydrate();

Inserting posts on the client side

When live updates come in you can insert a new post by dispatching an action to the component's wrapper.

Client side:

import { hydrate } from '@financial-times/x-interaction';

hydrate();

const wrapperElement = document.querySelector(
    `[data-live-blog-wrapper-id="x-dash-element-id"]`
);

const post = {
    id: '00000000-0000-0000-0000-000000000000',
    ...
};

const action = 'insert-post';
// wrapperElement must be the last argument.
const args = [
    post,
    wrapperElement
];

wrapperElement.dispatchEvent(
    new CustomEvent('x-interaction.trigger-action', {
        detail: { action, args },
        bubbles: true
    })
);

Client side events

This component dispatches the following client side events to notify the consuming app about live updates. Consuming apps typically use these events to initialise Origami components on the newly rendered markup.

<LiveBlogWrapper articleUrl="https://www.ft.com"
    showShareButtons={true}
    id="x-dash-element-id"
    posts={posts}
    serialiser={serialiser} />

...

const wrapperElement = document.querySelector(
      `[data-live-blog-wrapper-id="x-dash-element-id"]`
);

wrapperElement.addEventListener('LiveBlogWrapper.INSERT_POST',
      (event) => {
            const { post } = event.detail;

            // post object contains data about a live blog post
            // post.id can be used to identify the newly rendered
            // LiveBlogPost element
      });

Properties

Feature	Type	Notes
articleUrl	String	URL of the live blog - used for sharing
showShareButtons	Boolean	if true displays social media sharing buttons in posts
posts	Array	Array of live blog post data
id	String	(required) Unique id used for identifying the element in the document.

Configuring the next-live-event-api endpoint URL.

If you want to configure the URL for next-live-event-api, add the following plugin in your Webpack configuration file:

new webpack.DefinePlugin({
      LIVE_EVENT_API_URL: JSON.stringify('http://localhost:3003')
})