Dashboard Technical Reference
Dashboard State
DashboardState
Dashboard section of Adaptable State, including Initial State.
The Dashboard sits above the grid. Tabs are named groups of toolbars (the default is an empty list). PinnedToolbars sit above the grid and are not inside a tab. ActiveTabIndex is the zero-based index of the open tab. IsCollapsed leaves the header visible and hides the tab contents. IsFloating shows a draggable dashboard; FloatingPosition is its pixel position. IsHidden removes it until it is shown again from the Column Menu or Tool Panel.
number
Zero-based index into Tabs of the tab that is open.
Pixel position of the Dashboard while IsFloating is true. x and y are offsets in pixels.
boolean
Is Dashboard collapsed; if true, header is visible (but not Tabs' contents)
false
boolean
Is Dashboard floating; if true, it appears in a draggable form (double-click to revert to the default position)
false
AdaptableDashboardToolbars | string[]
Toolbars shown above the grid, outside any tab.
Named groups of toolbars. Each tab has a Name and the Toolbars it shows.
Empty Array
Tabs
DashboardTab
One Dashboard tab.
Name is the label in the header. Toolbars are the toolbars shown while this tab is the active one (ActiveTabIndex).
string
Name of the Dashboard Tab as it appears in the Dashboard header
AdaptableDashboardToolbars | string[]
List of Toolbars to show in the Tab
boolean
Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')
Floating Position
AdaptableCoordinate
Pixel position of the floating Dashboard.
number
Horizontal offset, in pixels.
number
Vertical offset, in pixels.
boolean
Sets Entity to ReadOnly (overwriting a Strategy Entitlement of 'Full')
Dasboard Options
DashboardOptions
Options related to the Dashboard in Adaptable.
boolean
Whether the Dashboard can be floated; if true (the default), double-clicking Dashboard puts it in float mode
true
Toolbars provided by Users which contain custom content
Buttons
buttonsLocation is a DashboardButtonsLocation:
| Value |
|---|
'left' |
'right' |
customDashboardButtons is a list of AdaptableButton objects. The click handler receives a DashboardButtonContext.
AdaptableButton
A button on a form, alert or toolbar.
label is the text. onClick runs when it is clicked and receives the button and the form or event context. buttonStyle and icon are optional. disabled and hidden are functions that return whether the button is disabled or hidden.
(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean
Function that disables / enables the button based on its evaluation result
AdaptableIcon| ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) =>AdaptableIcon)
Icon for Button - can be object or function that provides a AdaptableIcon object
string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)
Label for Button - can be string or function that provides string
(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void
Function to invoke when button is clicked
string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)
Tooltip for Button - can be string or function that provides string
ButtonStyle
Appearance of an AdapTable button.
variant is 'text', 'outlined' (the default) or 'raised'. tone is the colour: 'neutral' (the default), 'success', 'error', 'warning', 'info', 'accent' or 'none'. className adds a CSS class.
string
CSS Classname to use for the Button
'success' | 'error' | 'neutral' | 'none' | 'warning' | 'info' | 'accent'
Button's Tone - values: 'success', 'error', 'neutral', 'none', 'warning', 'info', 'accent'
'neutral'
'text' | 'outlined' | 'raised'
How Button appears - values: 'text', 'outlined', 'raised'
'outlined'
DashboardButtonContext
Context required by functions when using a Dashboard Button
Current Dashboard State
Custom application Context provided in AdaptableOptions.adaptableContext
Custom Toolbars
CustomToolbar
Custom Toolbar (which AdapTable will manage) enabling devs to populate Dashboard with bespoke content.
The Framework-specific (Angular, React or Vue) component to be rendered
string
How Toolbar is referenced (e.g. in Dashboard Popup when managing toolbars)
(formData: TData, context:CustomToolbarFormContext<TData>) => void
Callback invoked whenever the user changes a value in the toolbar form
(customRenderContext:CustomRenderContext) => string | null
Function to provide custom content when NOT using a Framework wrapper
string
Title to display in Toolbar; if unset or empty string, nothing will show
Actions available in a Custom Dashboard Toolbar
AdaptableForm<CustomToolbarFormContext<TData>, TData>
Optional inline form to render in the Toolbar (e.g. selects, checkboxes,
inputs).
Use this when you want to expose interactive controls - rather than just
buttons - in your Custom Toolbar without resorting to bespoke render
or frameworkComponent content.
The form's fields are rendered side-by-side using the inline form
layout. When the user changes any value the
callback is invoked. Buttons declared on the form receive a
which includes the current formData.
toolbarActions is 'close' or 'configure'.
toolbarButtons is a list of AdapTable Buttons. The click handler receives a CustomToolbarButtonContext:
CustomToolbarButtonContext
Context required by functions when using a Custom Toolbar Button
Custom Toolbar which hosts the Button
Custom application Context provided in AdaptableOptions.adaptableContext
toolbarForm is an AdaptableForm:
AdaptableForm
Expand
Defines the form. fields is a list of fields, rows of fields, or field groups. buttons are the form buttons. layout is rows (the default) or inline.
AdaptableForm
Defines a form which appears dynamically; used by Alerts, Export Custom Destinations and Dashboard Custom Toolbars.
string
Additional information to appear in the Form
Collection of Dynamic Fields and Field Groups to display.
Items can be:
- a single (rendered on its own row in the
default rows layout, or as one cell in the inline layout),
- an array of (rendered side-by-side on the
same row in the rows layout), or
- an (a labelled section that
visually groups related fields).
How the form's fields are arranged on screen.
- rows (default): each field on its own row, label on the left and
input on the right. Suitable for popups / wizards.
- inline: fields are placed side-by-side on a single horizontal line,
with the label rendered immediately before its input. Designed for
compact contexts such as Dashboard Custom Toolbars where vertical
real-estate is scarce.
'rows'
(formData: TData, context: T) => void
Optional form-level submit hook.
Fired when the user presses Enter while focus is inside any field
input AND the form is currently valid. The full formData is passed
through, typed as TData if you've supplied a custom shape.
Use this as an ergonomic shortcut to avoid wiring an explicit "Submit"
button - or in addition to one, so power users can press Enter to
commit. If the form is invalid the hook is not invoked.
string
Title to appear in the Form
Each field is an AdaptableFormField:
AdaptableFormField
Defines a Field that appears in an Adaptable Form
boolean
For single select fields only. When the user clears the combobox,
whether to restore instead of leaving the field empty.
Defaults to true when defaultValue is set, otherwise false.
Set to false when an empty selection is a distinct state from the default.
string | boolean | number | Array<string | number | boolean>
Field Default Value - can be of type string, boolean, number, or forselect fields with multi: true an array of those.
For single select fields, this is also the value restored when the user
clears the combobox (unless is false).
boolean | ((formData:AdaptableFormData, context:BaseContext) => boolean)
Disable the field's input. Either a boolean or a function evaluated
against the current form data. Disabled fields render but the user
cannot edit them.
Field Type - dictates which UI control is rendered
string
Inline help text rendered immediately below the field's input. Useful
for short explanations such as "format: YYYY-MM-DD" or "min 3 chars".
string
Label to display in the Field
number | string
Maximum allowed value. For number and slider: the highest accepted
number. For date, time and datetime: the latest allowed value in
ISO format.
number
Maximum length for text and textarea fields.
number | string
Minimum allowed value. For number and slider: the lowest accepted
number. For date, time and datetime: the earliest allowed value
in ISO format (YYYY-MM-DD / HH:mm / YYYY-MM-DDTHH:mm).
number
Minimum length for text and textarea fields.
boolean
For select fields only. When true the field renders as a
multi-select combobox; the field's value is an array of selectedoption.values rather than a single value.
false
string
Name of the Field
(value: any, context:BaseContext) => void
Optional callback invoked whenever value of this field changes
AdaptableFormFieldOption[] | ((formData:AdaptableFormData, context:BaseContext) =>AdaptableFormFieldOption[] | Promise<AdaptableFormFieldOption[]>)
Items to populate the select and radio fieldTypes.
Either a static array, or a function that derives the options from the
current form data and Adaptable context. The function form may return
a Promise for asynchronously-loaded options - the form will render the
field with no items until the promise resolves.
string
Regular expression that the value of a text field must match.
string
Placeholder text shown inside text, textarea, number, date,time and datetime inputs when empty. For select fields it is
rendered as the empty-state label when no value is selected.
When omitted on a select field with a , the label of
the matching options entry is used as the empty-state label.
(params:AdaptableFormFieldRenderParams) => React.ReactNode
For custom fields only. Renders an arbitrary React node as the
field's input. Receives the current value, a setValue setter
(controlled), the current form data, the Adaptable context and the
resolved disabled state.
Use this as an escape hatch when none of the built-in fieldTypes
fit - e.g. to render a star-rating widget, a tag editor or any
bespoke control.
boolean
If true the field is treated as required. An empty value ('',null, undefined, or unchecked checkbox) will produce a validation
error.
number
Stepping interval for number, slider, time and datetime
fields.
string
Tooltip shown when hovering the field's label.
(value: any, formData:AdaptableFormData, context:BaseContext) => string | null | undefined
Custom field-level validation. Return an error message string to mark
the field invalid, or null/undefined if the value is valid.
Custom validation runs after built-in checks (required, min,max, pattern, etc.) - the first failing check wins.
fieldType is an AdaptableFormFieldType:
| Value |
|---|
'text' |
'textarea' |
'select' |
'radio' |
'date' |
'time' |
'datetime' |
'number' |
'slider' |
'color' |
'checkbox' |
'textOutput' |
'custom' |
Select and radio options are AdaptableFormFieldOption objects:
AdaptableFormFieldOption
One choice in a select or radio form field.
layout is an AdaptableFormLayout:
| Value |
|---|
'rows' |
'inline' |
buttons are AdaptableButton objects:
AdaptableButton
A button on a form, alert or toolbar.
label is the text. onClick runs when it is clicked and receives the button and the form or event context. buttonStyle and icon are optional. disabled and hidden are functions that return whether the button is disabled or hidden.
(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => boolean
Function that disables / enables the button based on its evaluation result
AdaptableIcon| ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) =>AdaptableIcon)
Icon for Button - can be object or function that provides a AdaptableIcon object
string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)
Label for Button - can be string or function that provides string
(button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => void
Function to invoke when button is clicked
string | ((button:AdaptableButton<CONTEXT_TYPE>, context: CONTEXT_TYPE) => string)
Tooltip for Button - can be string or function that provides string
buttonStyle is a ButtonStyle:
ButtonStyle
Appearance of an AdapTable button.
variant is 'text', 'outlined' (the default) or 'raised'. tone is the colour: 'neutral' (the default), 'success', 'error', 'warning', 'info', 'accent' or 'none'. className adds a CSS class.
string
CSS Classname to use for the Button
'success' | 'error' | 'neutral' | 'none' | 'warning' | 'info' | 'accent'
Button's Tone - values: 'success', 'error', 'neutral', 'none', 'warning', 'info', 'accent'
'neutral'
'text' | 'outlined' | 'raised'
How Button appears - values: 'text', 'outlined', 'raised'
'outlined'
Dashboard API
DashboardApi
Functions relating to the AdapTable Dashboard.
void
Collapses Dashboard so only Dashboard Header is visible (and not Toolbars' contents)
void
Docks Dashboard so it 'snaps back' into its customary position above the grid
void
Expands Dashboard so Toolbars in Active Tab are fully visible
void
Floats Dashboard so only Dashboard Header is visible (in reduced size); can be dragged to a new location
DashboardTab | undefined
Returns current Active Tab (if there is one)
number | undefined
Returns current Active Tab index (if there is one)
AdaptableDashboardToolbars | string[]
Retrieves all Toolbars in Active Tab
Returns Custom Toolbar with the given name
HTMLElement | null
Returns the HTML Element for the given Custom Toolbar. This should only be used in Vanilla AdapTable for toolbars created via a render function.
Retrieves all Custom Toolbars
Retrieves Dashboard section from Adaptable State
AdaptableDashboardToolbars | string[]
Retrieves pinned toolbars
Retrieves the Tab from State that matches inputted name
Retrieves the Tabs in the Dashboard
void
Hides the Dashboard so cannot be seen
boolean
Is Dashboard Collapsed
boolean
Is Dashboard Docked
boolean
Is Dashboard Expanded
boolean
Is Dashboard Floating
boolean
Is Dashboard Visible
boolean
Checks if a given Toolbar is visible
void
Opens Settings Panel with Dashboard section selected and visible
void
Refreshes entire Dashboard, including Toolbars and Buttons; particularly relevant for AdapTable built-in elements, as framework components are dependent on the framework specific change detection mechanisms
Resets the data of a Custom Toolbar's toolbarForm back to thedefaultValues declared on its fields - clearing any user input
without unmounting / re-mounting the toolbar.
Useful for "Clear filters" buttons that need to wipe both the grid
filter AND the toolbar form's internal state in a single click.
void
Selects the Dashboard tab with this name.
void
Selects the Dashboard tab at this index.
Renders the given HTML string in the given Custom Toolbar. This should only be used in Vanilla AdapTable for toolbars created via a render function!
void
Sets the title shown in the Dashboard header.
void
Pins toolbars so they stay visible when the active tab changes.
void
Replaces the tabs shown in the Dashboard.
void
Makes the Dashboard visible
AdapTable Events
There are 2 Adaptable Events which are fired by AdapTable related to the Dashboard:
Dashboard Changed
The Dashboard Changed Event fires when anything has changed in the Dashboard.
The DashboardChangedInfo object which is provided, includes the trigger for the Change and new and old versions of Dashboard State.
It includes these properties:
DashboardChangedInfo
Payload of the DashboardChanged event.
Fires when Dashboard State changes, and once shortly after startup (actionName ADAPTABLE_READY). It is not fired when the old and new state are equal.
Extends , so adaptableApi is included.
string
What changed.ADAPTABLE_READY is the first event, shortly after startup.
Otherwise it is the Redux action type:DASHBOARD_SET_IS_COLLAPSED, DASHBOARD_SET_IS_HIDDEN, DASHBOARD_SET_IS_FLOATING, DASHBOARD_SET_FLOATING_POSITION, DASHBOARD_SET_MODULE_BUTTONS, DASHBOARD_SET_TABS, DASHBOARD_ACTIVE_TAB_INDEX_CHANGE, DASHBOARD_CLOSE_TOOLBAR.
Dashboard State after this change.
Dashboard State before this change.null when actionName is ADAPTABLE_READY.
Custom application Context provided in AdaptableOptions.adaptableContext
And these methods:
DashboardChangedInfo
Payload of the DashboardChanged event.
Fires when Dashboard State changes, and once shortly after startup (actionName ADAPTABLE_READY). It is not fired when the old and new state are equal.
Extends , so adaptableApi is included.
boolean
Whether toolbarName became visible because of this change.
True when the toolbar entered the active tab, or it was already in the active tab and the Dashboard was expanded or unhidden.
Custom Toolbar Configured
The Custom Toolbar Configured Event fires when the Configure button has been clicked in a Custom Toolbar.
The CustomToolbarConfiguredInfo simply provides the particular Custom Toolbar where the button was clicked:
CustomToolbarConfiguredInfo
Payload of the CustomToolbarConfigured event.
Fires when the user clicks Configure on a custom toolbar that includes the configure action.
Extends , so adaptableApi is included.
Custom toolbar whose Configure button was clicked.
Custom application Context provided in AdaptableOptions.adaptableContext
Events Subscription
Subscribing to the Events is done the same as with all Adaptable Events:
api.eventApi.on('DashboardChanged', (eventInfo: DashboardChangedInfo) => {
});
api.eventApi.on('CustomToolbarConfigured', (eventInfo: CustomToolbarConfiguredInfo) => {
});