Skip to content

JavaScript Event Reference

The admin dashboard modules make extensive use of the JavaScript event system. This page documents how each event is used.

configure-widget-type-{{WIDGET_TYPE_ID}}

This event is fired when the admin user selects a widget type to create or chooses to edit an existing widget instance. It is responsible for triggering the display of the widget configuration form modal.

When configuring a new widget instance, {{WIDGET_TYPE_ID}} is replaced with the relevant widget type ID e.g. conversion_rate or recent_orders etc.

When editing the configuration of an existing widget instance, {{WIDGET_TYPE_ID}} is replaced with the relevant widget instance ID.

dashboard-charts-ready

This event is fired once the ApexCharts library has loaded and is available through the window.ApexCharts object.

See our ApexCharts documentation for more information.

disabled-widget-container-edit-mode

This event is fired when the admin user disables the dashboard "Edit Mode" by saving their positioning and sizing changes.

See the Dashboard Organisation user guide for more information.

enabled-widget-container-edit-mode

This event is fired when the admin user enables the dashboard "Edit Mode" by clicking either the widget menu's Resize action or the dashboard toolbar's customize Dashboard button.

See the Dashboard Organisation user guide for more information.

force-close-widget-config-form

This event is fired when the admin user clicks the Cancel button in the customisation toolbar while any of the widget configuration forms have unsaved changes.

new-widget-menu

This event is fired when the admin user clicks the Add Widget button. It is responsible for displaying the widget selection modal.

reset-widget-order

This event is fired when the admin user clicks the Cancel button in the customisation toolbar. It is responsible for restoring the dashboard to its last stable state.

sort-checklist-items

This event is fired by the checklist widget's sort action component. It is responsible for triggering the reordering of checklist items so that completed items are moved to the bottom of the list.

The event detail contains the widget instance ID: {id: instanceId}.

update-chart-size-{{INSTANCE_ID}}

This event is fired when the admin user opens or closes the full screen view of a widget or when a widget is resized and causes the widget chart size to update appropriately.

update-toast

This event is fired whenever a message needs to be surfaced to the admin user - usually to highlight successful or failing actions.

widget-config-form-close

This event is fired when the admin user closes the widget configuration modal for an existing widget instance.

widget-config-form-dirty-close

This event is fired when the admin user closes the widget configuration modal while it has unsaved changes. It is responsible for triggering the display of the confirmation modal which prompts the admin user to confirm they are happy to lose their unsaved changes.

widget-config-form-open

This event is fired when the admin user opens the widget configuration modal for an existing widget instance.

widget-config-form-reset

This event is fired when the admin user closes the widget configuration modal.

widget-container-edit-mode-enabled

This event is fired by the widget container when "Edit Mode" is enabled. It is responsible for disabling the customize Dashboard button.

See the Dashboard Organisation user guide for more information.

widget-container-edit-mode-disabled

This event is fired by the widget container when "Edit Mode" is disabled. It is responsible for re-enabling the customize Dashboard button after the admin has saved their positioning and sizing changes.

See the Dashboard Organisation user guide for more information.

widget-container-initialised

This event is fired by the widget container once it has initialised.

widget-container-updated

This event is fired by the widget container once it has initialised and whenever a widget is added or removed from it.

widget-dashboard-clear

This event is fired when the user opts to clear their dashboard. It is responsible for opening the modal the user can use to either cancel or confirm the action.

widget-filter-update

This event is fired by the framework filter action component when the admin user selects a filter option. It is responsible for notifying widget instances to update their displayed content based on the selected filter value.

The event detail contains the widget instance ID and the selected filter value: {id: instanceId, value: selectedFilter}.

widget-instance-created

This event is fired when the widget configuration form for a new widget instance has been saved successfully. It is responsible for telling the widget container component to insert a new widget.

widget-instance-data-updated

This event is fired when a widget instance successfully has its content updated - this happens once when the widget component is first initialised and subsequently when the admin user updates its configuration.

widget-instance-{{INSTANCE_ID}}-{{PROPERTY_TYPE}}-{{INPUT_NAME}}-updated

This event is fired by the widget instance property switcher component whenever the user changes the selected value.

String Replacement

Underscores (_) in any of the {{INSTANCE_ID}}, {{PROPERTY_TYPE}}, and {{INPUT_NAME}} values are replaced by dashes (-).

Property Switcher

The property switcher component is most often found in the header of the widget instance output. The core Hyvä admin dashboard widgets make use of this component for things like the interval value switcher seen on some sales-related widgets.

widget-instance-updated-{{WIDGET_INSTANCE_ID}}

This event is fired when the widget configuration form for an existing widget instance has been saved successfully. It is responsible for telling the widget container component to update the widget instance content for the widget whose instance ID matches {{WIDGET_INSTANCE_ID}}.