newHeatmapWidget
newHeatmapWidget is a constructor function for creating the Heatmap widget.
Widget Constructor
Call newHeatmapWidget to create a widget instance inside a browser DOM
element.
import { newHeatmapWidget } from '@dx-display/widgets-heatmap'
const domNode = document.getElementById('widget-container')
const dataProviders = {
ipfPath: '/your-path/ipf',
ipfAuthHeader: 'your-header',
scannerPath: '/api/scanner',
scannerAuthHeader: 'your-header',
schedulePath: '/api/schedule'
}
const widget = newHeatmapWidget({
element: domNode,
providers: dataProviders,
})
Signature
newHeatmapWidget(props: WidgetConstructorProps): WidgetAPI
Returns
An WidgetAPI object.
WidgetConstructorProps
| Name | Type | Description |
|---|---|---|
| element | HTMLElement | A DOM element where the widget should be attached. |
| providers | Providers | An object with configuration for data providers. Refer to the Data Providers section for details |
| config optional | Config | Initial configuration of the widget |
| state optional | State | Initial state of the widget |
| theme optional | ThemeName | Theme | Initial theme of the widget. Refer to the Styling section for details |
Widget API
getConfig
Gets the current widget config.
Signature
getConfig(): Config
Returns
setConfig
Sets widget config.
Signature
setConfig(config: Config): void
Parameters
| Name | Type | Description |
|---|---|---|
| config | Config | Configuration object. Omitted or undefined properties will be set to default |
getState
Gets the current widget state.
Signature
getState(): State
Returns
updateState
Updates widget state.
Signature
updateState(state: Partial<State>): void
Parameters
| Name | Type | Description |
|---|---|---|
| state | Partial<State> | State object. Merges with the previous state object. |
addStateListener
Sets up a function that will be called whenever the state or specified field is changed.
Signature
addStateListener(stateChangeCallback: (state: State) => void): void
addStateListener(field: keyof State, fieldChangeCallback: (field: State[keyof State]) => void): void
Parameters
| Name | Type | Description |
|---|---|---|
| stateChangeCallback | (state: State) => void | Function that will be called whenever the state is changed. |
Or
| Name | Type | Description |
|---|---|---|
| field | keyof State | The state field to listen for. |
| fieldChangeCallback | (value: State[keyof State]) => void | Function that will be called whenever the specified field is changed. |
removeStateListener
Removes an state listener previously registered with addStateListener
Signature
removeStateListener(stateChangeCallback: (state: State) => void): void
removeStateListener(field: keyof State, fieldChangeCallback: (field: State[keyof State]) => void): void
Parameters
| Name | Type | Description |
|---|---|---|
| stateChangeCallback | (state: State) => void | Listener that will be removed. |
Or
| Name | Type | Description |
|---|---|---|
| field | keyof State | The state field for which to remove a listener. |
| fieldChangeCallback | (value: State[keyof State]) => void | Listener that will be removed. |
getData
Gets the current widget data.
Signature
getData(): Data
Returns
addDataListener
Sets up a function that will be called whenever the data or specified field is changed.
Signature
addDataListener(dataChangeCallback: (data: Data) => void): void
addDataListener(field: keyof Data, fieldChangeCallback: (field: Data[keyof Data]) => void): void
Parameters
| Name | Type | Description |
|---|---|---|
| dataChangeCallback | (data: Data) => void | Function that will be called whenever the data is changed. |
Or
| Name | Type | Description |
|---|---|---|
| field | keyof Data | The data field to listen for. |
| fieldChangeCallback | (value: Data[keyof Data]) => void | Function that will be called whenever the specified field is changed. |
removeDataListener
Removes an data listener previously registered with addDataListener
Signature
removeDataListener(dataChangeCallback: (data: Data) => void): void
removeDataListener(field: keyof Data, fieldChangeCallback: (field: Data[keyof Data]) => void): void
Parameters
| Name | Type | Description |
|---|---|---|
| dataChangeCallback | (data: Data) => void | Listener that will be removed. |
Or
| Name | Type | Description |
|---|---|---|
| field | keyof Data | The data field for which to remove a listener. |
| fieldChangeCallback | (value: Data[keyof Data]) => void | Listener that will be removed. |
setSlot
Inserts custom markup into widget UI. Refer to the Extend widget UI section for details.
Signature
setSlot(slot: Slot, element: HTMLElement): void
Parameters
| Name | Type | Description |
|---|---|---|
| slot | Slot | The place where a provided element is inserted. |
| element | HTMLElement | An element that is inserted. |
setTheme
Sets widget theme.
Signature
setTheme(theme: Theme | ThemeName): void
unmount
Destroys the widget.
Signature
unmount(): void
Data Providers
The Data Providers object supplies an information about the endpoints required by the widget, such as the path to the endpoint and the authorization key.
interface HeatmapWidgetDataProviders {
ipfPath: string
ipfAuthHeader: string
scannerPath: string
scannerAuthHeader: string
schedulePath: string
}
Properties
| Name | Type | Description |
|---|---|---|
| ipfPath | string | A string containing the path to the endpoint. |
| ipfAuthHeader | string | A string containing the authentication header for the endpoint. |
| scannerPath | string | A string containing the path to the endpoint. |
| scannerAuthHeader | string | A string containing the authentication header for the endpoint. |
| schedulePath | string | A string containing the path to the endpoint. |
Configuration
Configuration is an object that defines the basic behavior of a widget and allows enabling or disabling widget features that cannot be configured within the widget's user interface.
Type
interface HeatmapWidgetConfig {
colorBySelectorViewMode?: ToolbarSelectorViewMode,
groupBySelectorViewMode?: ToolbarSelectorViewMode,
sizeBySelectorViewMode?: ToolbarSelectorViewMode,
heatMultiplierSelectorViewMode?: ToolbarSelectorViewMode,
heatMultiplierPanelEnabled?: boolean,
symbolSearchViewMode?: SymbolSearchViewMode,
breadcrumbs?: boolean,
symbolScheduleStatusEnabled?: boolean,
locale?: LocaleSettings,
}Properties
| Name | Type | Default | Description |
|---|---|---|---|
| colorBySelectorViewMode Optional | ToolbarSelectorViewMode | 'available' | View mode of the color-by select in the toolbar. |
| groupBySelectorViewMode Optional | ToolbarSelectorViewMode | 'available' | View mode of the group-by select in the toolbar. |
| sizeBySelectorViewMode Optional | ToolbarSelectorViewMode | 'available' | View mode of the size-by select in the toolbar. |
| heatMultiplierSelectorViewMode Optional | ToolbarSelectorViewMode | 'available' | View mode of the heat multiplier select in the toolbar. |
| heatMultiplierPanelEnabled Optional | boolean | true | A flag that controls the heat multiplier information panel visibility in the toolbar. |
| symbolSearchViewMode Optional | SymbolSearchViewMode | available | View mode of the symbol search in the toolbar. |
| breadcrumbs Optional | boolean | true | If true, clicking on the group cell will pin the group as the chart's root and show the breadcrumbs. |
| symbolScheduleStatusEnabled Optional | boolean | false | A flag that controls a visibility of symbol schedule status in widget toolbar |
| locale Optional | LocaleSettings |
{
language: 'en',
dateLocale: 'en-GB',
numberLocale: 'en-GB'
} | An object that defines the language and regional settings of the widget. |
State
State is an object that represents the state of the widget.
Type
interface HeatmapWidgetState {
symbols: string[],
selectedSymbol?: string,
colorBy: ColorById,
sizeBy: SizeById,
heatMultiplier: HeatMultiplier,
groupBy: GroupBy,
}Properties
| Name | Type | Default | Description |
|---|---|---|---|
| symbols | string[] | [] | A list of strings containing symbols. If symbols.length === 1 symbol is treated as an indexand the widget will try to fetch its constituents. If symbols.length > 1 then widget shows heatmap for provided symbols. |
| selectedSymbol Optional | string | undefined | A string containing the symbol of selected index component from the chart. |
| colorBy | ColorById | 'changePercent-1h' | A string value that specifies a data-point that used to color symbols in the heatmap. |
| sizeBy | SizeById | 'market-cap' | A string value that specifies a data-point that used to calculate sizes of symbols in the heatmap. |
| heatMultiplier | HeatMultiplier | 'x1' | A string value that specifies multiplier to a parameters, based on which the symbols in the heat map are colored. |
| groupBy | GroupBy | 'sector' | The 'sector' value groups index components by sectors. The 'none' value don't apply any grouping. |
Data
Data is an object that represents the readonly data of the widget.
Type
type HeatmapWidgetData = Record<string, HeatmapWidgetDataItem>Type Reference
HeatmapWidgetDataItem
Type
{
sector?: string,
industryGroup?: string,
industry?: string,
sizeBy?: number,
colorBy?: number,
}ColorById
Type
'changePercent-1h' | 'changePercent-4h' | 'changePercent-1d' | 'changePercent-1w' | 'changePercent-1mo' | 'changePercent-1y' | 'changeFromOpenPercent-1d' | 'gapPercent-1d'SizeById
Type
'price-cash-ratio' | 'price-book-ratio' | 'price-sales-ratio' | 'volume-1h' | 'volume-4h' | 'volume-1d' | 'volume-1w' | 'volume-1mo' | 'volume-1y' | 'average-volume-10' | 'average-volume-30' | 'average-volume-60' | 'average-volume-90' | 'dividend-yield-percent' | 'earnings-per-share' | 'market-cap'