Using the Action API

• Buttons in the toolbar of custom views and dashboards, using the option Configure Toolbar. For more details, please refer to Section Understanding the Custom Views and Dashboards.

• The Button widget. For more details, please refer to Section Using the Button Widget.

• Custom entries in the Actions menu available for each scenario displayed in the Scenario List widget. For more details, please refer to Section Using the Scenario List Widget.

• web/src/app/modules/sample-actions/actions/sample-action-copy-url.ts allows to perform a copy to clipboard of the current application URL.

• web/src/app/modules/sample-actions/actions/sample-action-hello-world-with-data.ts allows to use parameters and dynamic data.

• web/src/app/modules/sample-actions/actions/sample-action-open-webpage.ts allows to open a URL through a new web browser page, with preconditions.

• web/src/app/modules/sample-actions/actions/sample-action-scenario-info.ts allows to display information on a scenario and, through dynamic data and parameter resolution, add it to the Actions menu in the Scenario List widget.

• A GeneActionExecutor, which is a function that will be called to execute the action. This method will return an observable of GeneActionResult<R> where R is a type of result.

• An optional execution parameter, which will be a value of a given type passed as a parameter of the action (if applicable).

• An optional parametersConfigurator, which, when provided, is a TypeScript class of the widget to use to configure the action parameter. The expected widget type must implement the GeneActionParametersAware interface.

• An optional parametersResolver function, which, when provided, will resolve the parameter to use before the action execution. This is useful when an action parameter requires contextual runtime parameters that can not be configured beforehand.

• An optional list of GenePrecondition, which, when provided, are evaluated and must all return {canExecute:true} to allow the user to execute the associated action. If one of the provided preconditions evaluates to {canExecute:false}, the web client will not let the user execute the action.

import { GeneAction, GeneActionExecutor, GeneActionManifest } from "@gene/widget-core";
import { GeneClipboardUtils } from "@gene/widget-data";
import { of } from "rxjs";

/**
 * A sample action that copies the current URL to the clipboard
 */
export const SAMPLE_ACTION_COPY_URL: GeneActionManifest = {
    id: "sample-copy-url",
    name: "Sample Action — copy current URL",
    icon: 'copy'
};

/**
 * Executor function for SAMPLE_ACTION_COPY_URL action. Copy the current URL to the clipboard.
 */
export const copyUrlExecutor = ((_: GeneAction<string>) => {
    const success = GeneClipboardUtils.copyUrlToClipboard();
    return of( { success });
}) as GeneActionExecutor;

• Registering a simple action with no precondition: When executed, this action copies the current URL to the clipboard. It requires no preconditions and takes no parameters.

  /**
   * A sample action that copies the current URL to the clipboard
   */
  const SAMPLE_ACTION_COPY_URL: GeneActionManifest = {
      id: "sample-copy-url",
      name: "Sample Action — copy current URL",
      icon: 'copy'
  };
  
  /**
   * Executor function for SAMPLE_ACTION_COPY_URL action. Copy the current URL to the clipboard.
   */
  const copyUrlExecutor = ((_: GeneAction<string>) => {
      const success = GeneClipboardUtils.copyUrlToClipboard();
      return of( { success });
  }) as GeneActionExecutor;
  
  // Register the action
  actionService.registerAction({
              manifest: SAMPLE_ACTION_COPY_URL,
              executor: copyUrlExecutor
  } as GeneActionRegistrationDescriptor<string>);

• Registering an action with preconditions: This action opens a new web browser page on a parameter URL. It has the precondition of having a parameter URL set and uses the ActionTextInputConfiguratorComponent component to configure the parameter URL.

  /**
   * A sample action that opens a custom web page which URL is passed as parameter
   */
  const SAMPLE_ACTION_OPEN_WEB_PAGE: GeneActionManifest = {
      id: "sample-open-web-page",
      name: "Sample Action — open a custom web page",
      icon: 'link',
      hasParameters: true
  };
  
  /**
   * Executor function for SAMPLE_ACTION_OPEN_WEB_PAGE action. Open a new tab with the URL passed as parameter of the action.
   */
  const openCustomWebPageExecutor = ((action: GeneAction<string>) => {
      const w = window.open(action.parameters, '_blank');
      const success = w!=null;
      const result = success ? action.parameters : null;
      return of( { success, result });
  }) as GeneActionExecutor;
  
  /**
   * A precondition that checks that the URL parameter is not null
   */
  const notNullURLPrecondition : GenePrecondition<string> = {
      evaluate: (context: GeneContext, url?: string) => {
          const canExecute = url?.length > 0;
          const message = canExecute ? '' : 'The URL parameter must be provided.';
  
          return of({
              canExecute,
              message
          })
      }
  };
  
  // Register custom actions samples
  actionService.registerAction({
      manifest: SAMPLE_ACTION_OPEN_WEB_PAGE,
      executor: openCustomWebPageExecutor,
      preconditions: [notNullURLPrecondition],
      parametersConfigurator: ActionTextInputConfiguratorComponent,
  } as GeneActionRegistrationDescriptor<string>);

// Executing the action with runtime data to be used by the parameter resolver
actionService.executeAction({manifest:SAMPLE_ACTION_HELLO_WORLD}, `Jane Doe, born on ${new Date().toLocaleDateString()}`);