Use a Controller object to add the generator to a chart:
const appointmentGenerator = controller.addGenerator('Appointments');
All appointments passed to the generator must already be filtered to the selected instrument in the chart.
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 `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) => AppointmentData[];
type DividendRequest = { instrument: string, currency: string | undefined };
type DividendFetcher = (options: DividendRequest) => DividendData[];
type SplitRequest = { instrument: string };
type SplitFetcher = (options: SplitRequest) => SplitData[];
The generator emits three different events:
Type
interface Appointments {
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"
* }
*/
});
Type
interface Appointments {
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"
* }
*/
});
Type
interface Appointments {
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"
*/
});
The generator exposes several public methods.
Type
declare class Appointments {
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.
Type
declare class Appointments {
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.
Type
interface Appointments {
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.
Type
interface Appointments {
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.
Type
interface Appointments {
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.
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
utils.rmOptionFlag(appointmentGenerator, 'dividendButton', ObjectEOptionFlags.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
utils.rmOptionFlag(appointmentGenerator, 'fundamentalsButton', ObjectEOptionFlags.EXPOSED); // belongs to the fundamentalClicked event
The generator has a built-in permission check, which is called in its onStart method. It calls the provided checkPermission method (via Controller) with the key Appointments.
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.