npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@financial-times/x-live-blog-wrapper

v14.7.7

Published

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` componen

Downloads

467

Readme

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.

Installation

This module is supported on Node 16 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). Also worth noting, this component handles visibility tracking when passed postTrackerConfig property. The postTrackerConfig property contains the follow fields:

  • onEntersViewport: Callback function with an event parameter
  • OnRead: Callback function with an event parameter
  • OnError: Callback function with an event parameter
  • usePostTracker: Boolean. When set to true LiveBlogWrapper component creates and manages an instance of PostTracker and reports read, view, error events. All fields are required to use post tracking.

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';

// example props. Not exhaustive but shows use of tracking
const props = {
    posts: [],
    id: 'live-blog-wrapper',
    articleUrl: `https://www.ft.com/content/${id}`,
    showShareButtons: true,
    postTrackerConfig: {
        onEntersViewport: (event) => console.log(event, 'view'),
        onRead: (event) => console.log(event, 'read'),
        onError: (event) => console.log(event, 'error'),
        usePostTracker: true,
    }
}

// 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.

The x-live-blog-wrapper component also exports PostTracker, a class used to track post visibility. It reports a read and a view event for individual posts in the LiveBlogWrapper component. If you choose to handle post tracking yourself, this class should be used as an alternative.

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

const onEntersViewPort = (event) => {} // Enrich event with app context and report to tracking medium.
const onRead = (event) => {} // Enrich event with app context and report to tracking medium.
const onError = (event) => {} // Enrich event with app context and report to tracking medium.
const liveBlogPackageId = '00000-00000-00000-00000'

/**
 * @type {import('@financial-times/x-live-blog-wrapper').PostTracker.PostTrackerConfig}
 */
let config = {
  query: 'article[data-trackable="live-post"]', // required
  minMillisecondsToReport: 5000,
  returnVisibleElement: true,
  observerUpdateEventString: 'LiveBlogWrapper.INSERT_POST', // required
  liveBlogWrapperQuery: `div[data-live-blog-wrapper-id="${liveBlogPackageId}"]`, // required, where id = liveblogpackage.id
  liveBlogWrapper: this.props.liveBlogWrapperElementRef
    ? this.props.liveBlogWrapperElementRef.current
    : undefined,
  onEntersViewport: (event) => onEntersViewport(event), // required
  onRead: (event) => onRead(event), // required
  onError: (event) => onError(event) // required
}
const tracker = new PostTracker(config)

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. | | renderRichText | Component | A component to use for rendering structured content, e.g. RichText from cp-content-pipeline-ui. Required when rendering with data from cp-content-pipeline-api.

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