News Generator

Add to Chart:

Use a BG.charts.Controller object to add the generator to a chart:

const newsGenerator = controller.addGenerator('NewsGenerator');

All news passed to the generator must already be filtered to the selected instrument in the chart.

Types

type NewsCategory = {
    /** name displayed in the UI */
    name: string,
    /** letter displayed in the legend entry/news bubble */
    shortName: string,
    /** number of news-elements that will be automatically created. If the limit is reached, the user needs to interact with the tool for more news to be loaded/created. */
    limit: number,
    /** whether this category should be enabled by default */
    enabled: boolean,
    /** optional object for permission checks. */
    permission?: {
        /** string used for calls to `BG.charts.TContext.env.checkPermission`. If the return value is not truthy, articles for this type will not be requested. */
        key: string,
        /** optional hint to display in the UI */
        hint?: string,
    },
};

type Article {
    getId(): number;

    getCategoryId(): string;
}

type ArticleData = {
    id: number,
    date: string,
    categories: string[],
};

type CategorySubscriptionRequest = { instrument: string, category: string };
type CategorySubscriptionCallback = (data: ArticleData, identifier: string) => void;

type CategorySubscriberFn = (options: CategorySubscriptionRequest, cb: CategorySubscriptionCallback) => { unbind: () => void };

type BundledArticleRequest = { instrument: string, identifiers: string[], start?: Date, end?: Date };

type ArticleFetcher = (options: BundledArticleRequest, cb: (articles: ArticleData[]) => void) => void;

Events:

The generator emits three different events:

#articlesClicked

• Type

  interface NewsGenerator {
      emit(type: 'articlesClicked', values: {
          event: MouseEvent,
          articles: Article[],
          instrument: string,
      }): void;
  }

• Details

  Emitted when the user clicks on one of the NewsTools. Emits an object containing the click event, an array with all articles belonging to the NewsTool, and the instrument-identifier.

• Example

  // example usage:
  newsGenerator.on('articlesClicked', (values) => {
      /* values
       * {
       *    event: MouseEvent
       *    articles: [Article, Article, Article]
       *    instrument: "133962"
       * }
       */
  });

#articlePushed

• Type

  interface NewsGenerator {
      emit(type: 'articlePushed', values: {
          articles: Article[],
          instrument: string,
      }): void;
  }

• Details

  Similar to articlesClicked, except only emitted when an article is pushed to the category of the NewsTool last clicked on by the user. E.g. when using day candles, and the user already selected 'all' categories for the tool on the day candle, the application needs to know whether to refresh/add new articles to an article list that is already open.

• Example

  // example usage:
  newsGenerator.on('articlesPushed', (values) => {
      /* values
       * {
       *    event: MouseEvent
       *    articles: [Article]
       *    instrument: "133962"
       * }
       */
  });

#newsClicked

• Type

  interface NewsGenerator {
      emit(type: 'newsClicked', values: {
          instrument: string
      }): void;
  }

• Details

  Emitted when the user clicks on the Newsfeed button. Can be used to show all news for an instrument regardless of categories.

• Example

  // example usage:
  newsGenerator.on('newsClicked', ({ instrument }) => {
      /* instrument
       * "133962"
       */
  });

Public methods:

The generator exposes several public methods.

#static setCustomCategories

• Type

  declare class NewsGenerator {
      static setCustomCategories(categories: Record<string, NewsCategory>): void;
  }

• Details

  setCustomCategories allows overriding the default stock3 news categories. The keys/ids of the categories object can be something of your own choosing, while the value needs to adhere to the NewsCategory type.

#static setDataInterface

• Type

  declare class NewsGenerator {
      static setDataInterface(dataFns: { subscriptionFn: CategorySubscriberFn, articleFetcher: ArticleFetcher }): void
  }

• Details

  setDataInterface adds the callbacks to the generator which are required for loading data.

  The subscriptionFn will be used to subscribe to webpush and automatically add new articles to the chart. An instrument and the category will be passed to the function, which needs to return an object { unbind: Function } to terminate the subscription.

  The articleFetcher is used to fetch historic article data. A BundledArticleRequest object will be passed to the function, which needs to return an ArticleData array. The BundledArticleRequest contains the instrument, the categories to fetch articles for, as well as the start and end date of the requested time span.

#addArticles

• Type

  interface NewsGenerator {
      addArticles(articles: ArticleData[]): void;
  }

• Details

  addArticles takes an ArticleData array and adds those articles to the chart. May be used as a very simple alternative to the setDataInterface method when all articles should be loaded regardless of the selected time span.

Optional Buttons

The News Generator has a NewsFeed button which is visible by default. It can be used to open a list of articles for the given instrument regardless of the categories. If this button is not relevant for you, it may be hidden by removing the EXPOSED flag

// examples
BG.charts.utils.rmOptionFlag(newsGenerator, 'newsfeedButton', BG.charts.Object.EOptionFlags.EXPOSED); // belongs to the newsClicked event

Permissions

The generator has a built-in permission check, which is called in its onStart method. It calls the provided checkPermission method (via BG.charts.Controller) with the key NewsGenerator.

Furthermore, categories may also have a permission check. Simply add a permission property to the category provided via setCustomCategories with a key of your choice, and the generator will call checkPermission with the provided key upon starting.