Appointment Generator

Add to Chart:

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

const appointmentGenerator = controller.addGenerator('AppointmentGenerator');

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

Types

type AppointmentCategory = {
    /** 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, appointments for this type will not be requested. */
        key: string,
        /** optional hint to display in the UI */
        hint?: string,
    },
    /** this generator has a different display for dividends */
    isDividend: boolean;
    /** this generator has a different display for splits */
    isSplit: boolean;
};

type Appointment {
    getId(): number;

    getCategoryId(): string;
}

type AppointmentData = {
    id: number,
    date: string,
    category: string,
};

type DividendData = {
    exDate: string,
    value: number,
};

type SplitData = {
    exDate: string,
    ratio: number,
    numerator: number,
    denominator: number,
};

type BundledAppointmentRequest = { instrument: string, categories: string[], start?: Date, end?: Date };
type AppointmentFetcher = (aptRequest: BundledAppointmentRequest, cb: (data: AppointmentData[]) => void) => void;

type DividendRequest = { instrument: string, currency: string | undefined };
type DividendFetcher = (options: DividendRequest, cb: (data: DividendData[]) => void) => void;

type SplitRequest = { instrument: string };
type SplitFetcher = (options: SplitRequest, cb: (data: SplitData[]) => void) => void;

Events:

The generator emits three different events:

#appointmentClicked

• Type

  interface AppointmentGenerator {
      emit(type: 'appointmentClicked', values: {
          event: MouseEvent,
          appointments: Appointment[],
          instrument: string,
      }): void;
  }

• Details

  Emitted when the user clicks on one of the AppointmentTools. Emits an object containing the click event and the instrument's identifier.

• Example

  // example usage:
  appointmentGenerator.on('appointmentClicked', (values) => {
      /* values
       * {
       *    event: MouseEvent,
       *    appointments: [Appointment, Appointment],
       *    instrument: "133962"
       * }
       */
  });

#dividendClicked

• Type

  interface AppointmentGenerator {
      emit(type: 'dividendClicked', values: {
          instrument: string,
      }): void;
  }

• Details

  Emitted when the user clicks on a dividend button. Emits an object containing the instrument's identifier.

• Example

  // example usage:
  appointmentGenerator.on('dividendClicked', (values) => {
      /* values
       * {
       *    instrument: "133962"
       * }
       */
  });

#fundamentalClicked

• Type

  interface AppointmentGenerator {
      emit(type: 'fundamentalClicked', values: {
          instrument: string
      }): void;
  }

• Details

  Emitted when the user clicks on a fundamentals button. Emits an object containing the instrument's identifier.

• Example

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

Public methods:

The generator exposes several public methods.

#static setCustomCategories

• Type

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

• Details

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

#static setDataInterface

• Type

  declare class AppointmentGenerator {
      static setDataInterface(dataFns: { dividendFetcher: DividendFetcher, splitFetcher: SplitFetcher, appointmentFetcher: AppointmentFetcher  }): void
  }

• Details

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

  The appointmentFetcher is used to fetch historic appointment data. A BundledAppointmentRequest object will be passed to the function, which needs to return an AppointmentData array. The BundledAppointmentRequest contains the instrument, the categories to fetch appointments for, as well as the start and end date of the requested time span.

#addAppointments

• Type

  interface AppointmentGenerator {
      addAppointments(dividends: AppointmentData[]): void;
  }

• Details

  addAppointments takes an AppointmentData array and adds these appointments to the chart. May be used as a very simple alternative to the setDataInterface method when all appointments should be loaded regardless of the selected time span.

#addDividends

• Type

  interface AppointmentGenerator {
      addDividends(appointments: DividendData[]): void;
  }

• Details

  addDividends takes a DividendData array and adds these appointments to the chart. May be used as a very simple alternative to the setDataInterface method when all dividends should be loaded regardless of the selected time span.

#addSplits

• Type

  interface AppointmentGenerator {
      addSplits(splits: SplitData[]): void;
  }

• Details

  addSplits takes an SplitData-array and adds these appointments to the chart. May be used as a very simple alternative to the setDataInterface-method when all splits should be loaded regardless of the selected time span.

Optional Buttons

The Appointment Generator has a dividend button which is visible by default. It can be used to open a list of dividends in a different view. If this button is not relevant for you, it may be hidden by removing the EXPOSED flag

// examples
BG.charts.utils.rmOptionFlag(appointmentGenerator, 'dividendButton', BG.charts.Object.EOptionFlags.EXPOSED); // belongs to the dividendClicked event

It also has a fundamentals button, also visible by default. It can be used to open a fundamental chart in a different view. If this button is not relevant for you, it may be hidden by removing the EXPOSED flag

// examples
BG.charts.utils.rmOptionFlag(appointmentGenerator, 'fundamentalsButton', BG.charts.Object.EOptionFlags.EXPOSED); // belongs to the fundamentalClicked 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 AppointmentGenerator.

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.