Skip to content

Latest commit

 

History

History
108 lines (75 loc) · 3.98 KB

README.md

File metadata and controls

108 lines (75 loc) · 3.98 KB

UI Actions

This plugin exposes a global event bus for the OpenSearch Dashboards UI that allows other plugins to expand the ui capabilities of the application using actions and triggers. Plugins can not only register actions and triggers that trigger an action, but also use existing triggers and actions for their own use case. Multiple actions can be associated with a single trigger. All the capabilities are exposed using the uiActions service.

Some of the uses in Dashboards for UI Actions are:

  1. For the context menus in a dashboard panel
  2. Interacting directly with a visualization to trigger filters and to select time ranges.

API

You can use the UI Actions service API's for the following use cases:

  • creating custom functionality (actions)
  • creating custom user interaction events (triggers)
  • attaching and detaching actions to triggers.
  • emitting trigger events
  • executing actions attached to a given trigger.
  • exposing a context menu for the user to choose the appropriate action when there are multiple actions attached to a single trigger.

The API for the service can be found in ./public/service/ui_actions_service.ts

Usage

Creating an action

const ACTION_ID = 'ACTION_ID';

// Declare the context mapping so that it is clear to the user what context the action should receive
declare module '../../../src/plugins/ui_actions/public' {
  export interface ActionContextMapping {
    [ACTION_ID]: ActionContext;
  }
}

// Create the action
const action = createAction<typeof ACTION_ID>({
  execute: async (context: ActionContext) => {}, // Action to execute when called
  id: ACTION_ID,
  // ...other action properties
});

// Register the action with the service
uiActions.registerAction(action);

Creating a trigger

const TRIGGER_ID = 'TRIGGER_ID';

// Declare the context mapping so that it is clear to the user what context the trigger should be called with
declare module '../../../src/plugins/ui_actions/public' {
  export interface TriggerContextMapping {
    [TRIGGER_ID]: TriggerContext; // The context that the trigger will execute with
  }
}

// Create the trigger
const trigger: Trigger<'TRIGGER_ID'> = {
  id: TRIGGER_ID,
};

// Register the trigger
uiActions.registerTrigger(trigger);

Attach an action to a trigger

There are two ways to do this:

  1. Attach a registered action to a registered trigger
uiActions.attachAction(TRIGGER_ID, ACTION_ID);
  1. Register a action to a registered trigger (If the action is not registered, this method also registers the action)
uiActions.addTriggerAction(TRIGGER_ID, action);

Trigger an event

Triggering an action is very simple. Just get the trigger using its ID and execute it with the appropriate context.

uiActions.getTrigger(trigger.id).exec(context);

Explorer

Use the UI actions explorer in the Developer examples to learn more about the service and its features. It can be started up using the --run-examples flag and found under the Developer examples option in the main menu.

yarn start --run-examples

Action Properties

Refer to ./public/actions/action.ts for all properties, keeping in mind it extends the presentable interface. Here are some properties that provide special functionality and customization.

  • order is used when there is more than one action matched to a trigger and within context menus. Higher numbers are displayed first.
  • getDisplayName is a function that can return either a string or a JSX element. Returning a JSX element allows flexibility with formatting.
  • getIconType can be used to add an icon before the display name.
  • grouping determines where this item should appear as a submenu. Each group can also contain a category, which is used within context menus to organize similar groups into the same section of the menu. See examples explorer for more details about what this looks like within a context menu.