Alerting Generator

Add to Chart:

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

const alertsGenerator = controller.addGenerator('AlertsGenerator');

All alerts passed to the generator must already be filtered and adjusted to the selected exchange in the chart.

• In this case, "filtered" means that only alerts with the same instrumentId should be given to the generator.
• "Adjusted to the selected exchange" means that the value of the alert must have already been calculated with the correct exchange/crossrate if the alert currency differs from the one shown in the chart.

Types

type Alert = {
    comment?: string | null;
    id: string;
    ts: number;
    value: number;
    referenceId?: string | null;
    commentPrefix?: string | null;
    validUntil?: number | null;
}

• comment: optional comment set by the user
• id: unique id of the alert
• ts: timestamp of the creation of the alert. Will be used to show the user in the chart when it was created
• value: value of the alert. Will be used to show the user where the alert is placed
• referenceId: id of another alert. Can be used to submit changes for a specific alert to the generator. The new Id will replace the referenced one. Will only work if the referenced alert still exists in the generator.
• commentPrefix: string that will be placed before the user comment, e.g. Kursalarm PREFIX: My Custom Comment.
• validUntil: timestamp that the alert is valid until

Events:

The generator emits several different events:

#changeAlert

• Type

  interface AlertsGenerator {
      emit(type: 'changeAlert', alert: {
          id: string,
          value: number,
          comment: string,
      }): void;
  }

• Details

  Emitted when the user changes the value or the comment of an existing alert. Emits an object containing the id of the alert as well as the value and the comment.

• Example

  // example usage:
  alertsGenerator.on('changeAlert', (alert) => {
      /* alert
       * {
       *    id: '1845666989'
       *    comment: 'test'
       *    value: 500
       * }
       */
  });

#deleteAlert

• Type

  interface AlertsGenerator {
      emit(type: 'deleteAlert', alert: Alert): void;
  }

• Details

  Emitted when the user presses the Delete button of an alert, or selects Delete in the context action menu. Alerts still need to be manually removed from the chart by calling alertsGenerator.removeAlert(alert).

• Example

  // example usage:
  alertsGenerator.on('deleteAlert', (alert) => {
      /* alert
       * {
       *    id: '18616816858',
       *    value: 500,
       *    comment: 'test',
       * }
       */
  });

#manageAlerts

• Type

  interface AlertsGenerator {
      emit(type: 'manageAlerts'): void;
  }

• Details

  Emitted when the user clicks on the settings button to open the alert manager widget.

• Example

  // example usage:
  alertsGenerator.on('manageAlerts', () => {});

#newAlert

• Type

  interface AlertsGenerator {
      emit(type: 'newAlert'): void;
  }

• Details

  Emitted when the user clicks on the settings button to create a new alert.

• Example

  // example usage:
  alertsGenerator.on('newAlert', () => {});

#showIndicatorAlerts

• Type

  emit(type: 'showIndicatorAlerts'): void;

• Details

  Emitted when the user clicks on the settings button to open indicator alerts.

• Example

  // example usage:
  alertsGenerator.on('showIndicatorAlerts', () => {});

Public methods:

The generator exposes several public methods.

#setAlert

• Type

  interface AlertsGenerator {
      setAlert(alert: Alert): AlertsTool | null;
  }

• Details

  setAlert takes an Alert object, which requires the properties id, ts and value to be set. Objects without any of these properties will generate a warning. It will return the tool, or null if the tool could not be created.

#setAlerts

• Type

  interface AlertsGenerator {
      setAlerts(alerts: Array<Alert>): Array<AlertsTool | null>;
  }

• Details

  setAlerts works similarly, but takes an Array<Alert> instead. Alerts in the array without the required properties will trigger warnings. It will return an Array with the tools or null at their specific position.

#removeAlert

• Type

  interface AlertsGenerator {
      removeAlert(alert: Alert): void;
  }

• Details

  removeAlert takes an Alert object and removes the alert line identified by the Id of the alert from the chart.

#getPrecision

• Type

  interface AlertsGenerator {
      getPrecision(): number;
  }

• Details

  getPrecision returns the precision of the chart.

#getExchangeId

• Type

  interface AlertsGenerator {
      getExchangeId(): number | undefined;
  }

• Details

  getExchangeId returns the exchange Id present in the chart or undefined if no exchange is present.

#getInstrumentId

• Type

  interface AlertsGenerator {
      getInstrumentId(): number | undefined;
  }

• Details

  getInstrumentId returns the Id of the instrument present in the chart or undefined, if no instrument is present.

#getCurrency

• Type

  interface AlertsGenerator {
      getCurrency(): string;
  }

• Details

  getCurrency returns the currency of the chart or 'N/A' if none is available.

Public methods (AlertsTool):

#getAlert

• Type

  interface AlertsGenerator {
      getAlert(): Alert
  }

• Details

  getAlert returns the alert of the tool

#set / #get

• Type

  interface AlertsGenerator {
      set('delete'): void
  }

• Details

  Appears as a button in the UI. Emits the deleteAlert event

---

• Type

  interface AlertsGenerator {
      get('comment'): string
      set('comment', value: string): void
  }

• Details

  Gets/sets the user comment for the specific alert.

---

• Type

  interface AlertsGenerator {
      get('descriptionAlignment'): 'right' | 'bottom-right' | 'left' | 'bottom-left'
      set('descriptionAlignment', value: 'right' | 'bottom-right' | 'left' | 'bottom-left'): void
  }

• Details

  Gets/sets the comment alignment, denoting whether it should be above or below the alert line. To change between above and below the line, use right and bottom-right.

Optional Buttons

The Alerts Generator has two optional settings buttons that are hidden by default: "manageAlerts" and "showIndicatorAlerts". The former should be used to open a quote alert management tool, while the latter should be used to open an indicator alert management tool. These are disabled by default as they may not be relevant for all platforms. To enable one of these buttons, you will have to set the exposed flag to true.

// examples
BG.charts.utils.addOptionFlag(alertsGenerator, 'manageAlerts', BG.charts.Object.EOptionFlags.EXPOSED);
BG.charts.utils.addOptionFlag(alertsGenerator, 'inda', BG.charts.Object.EOptionFlags.EXPOSED); // belongs to the showIndicatorAlerts event