diff --git a/README.md b/README.md index c31d20b..1d81fce 100644 --- a/README.md +++ b/README.md @@ -247,6 +247,11 @@ type CustomPluginConfigOptions = type: 'interaction'; name: string; label?: string; + } + | { + type: 'action-trigger'; + name: string; + label?: string; }; ``` @@ -376,6 +381,10 @@ Additional Fields A configurable workbook interaction to interact with other charts within your workbook +**Action Trigger** + +A configurable action trigger to trigger actions in other elements within your workbook + #### PluginInstance ```ts @@ -437,6 +446,11 @@ interface PluginInstance { selection: WorkbookSelection[], ): void; + /** + * Triggers an action based on the provided action trigger Id + */ + triggerAction(id: string): void; + /** * Overrider function for Config Ready state */ @@ -677,6 +691,24 @@ The returned setter function accepts an array of workbook selection elements function setVariableCallback(value: WorkbookSelection[]): void; ``` +#### useActionTrigger() + +Returns a callback function to trigger one or more action effects for a given action trigger + +```ts +function useActionTrigger(triggerId: string); +``` + +Arguments + +- `triggerId : string` - The ID of the action trigger + +The function that can be called to trigger the action + +```ts +function triggerActionCallback(): void; +``` + #### useConfig() Returns the workbook element’s current configuration. If a key is provided, only diff --git a/src/client/initialize.ts b/src/client/initialize.ts index a651f19..a74cbca 100644 --- a/src/client/initialize.ts +++ b/src/client/initialize.ts @@ -14,6 +14,7 @@ export function initialize(): PluginInstance { let subscribedInteractions: Record = {}; let subscribedWorkbookVars: Record = {}; + const registeredActionTriggers = new Set(); const listeners: { [event: string]: Function[]; @@ -135,7 +136,18 @@ export function initialize(): PluginInstance { ) { void execPromise('wb:plugin:selection:set', id, elementId, selection); }, + triggerAction(id: string) { + if (!registeredActionTriggers.has(id)) { + throw new Error(`Invalid action trigger ID: ${id}`); + } + void execPromise('wb:plugin:action-trigger:invoke', id); + }, configureEditorPanel(options) { + registeredActionTriggers.clear(); + for (const option of options) { + if (option.type !== 'action-trigger') continue; + registeredActionTriggers.add(option.name); + } void execPromise('wb:plugin:config:inspector', options); }, setLoadingState(loadingState) { diff --git a/src/react/hooks.ts b/src/react/hooks.ts index 330ff65..384ca83 100644 --- a/src/react/hooks.ts +++ b/src/react/hooks.ts @@ -176,3 +176,17 @@ export function useInteraction( return [workbookInteraction, setInteraction]; } + +/** + * React hook for returning a triggering callback function for the registered + * action trigger + * @param {string} id ID of action trigger + * @returns {Function} A callback function to trigger the action + */ +export function useActionTrigger(id: string) { + const client = usePlugin(); + + return useCallback(() => { + client.config.triggerAction(id); + }, [client, id]); +} diff --git a/src/types.ts b/src/types.ts index 734ddb6..cc01b4a 100644 --- a/src/types.ts +++ b/src/types.ts @@ -166,6 +166,11 @@ export type CustomPluginConfigOptions = type: 'interaction'; name: string; label?: string; + } + | { + type: 'action-trigger'; + name: string; + label?: string; }; /** @@ -255,6 +260,12 @@ export interface PluginInstance { selection: WorkbookSelection[], ): void; + /** + * Triggers an action based on the provided action trigger Id + * @param {string} id ID from action-trigger type in Plugin Config + */ + triggerAction(id: string): void; + /** * Overrider function for Config Ready state * @param {boolean} loadingState Boolean representing if Plugin Config is still loading