Widget action | Casewhere Docs

While viewing data in Casewhere widgets, end-users may need to interact with the data, such as editing a draft, submitting an application, or approving a budget. These functionalities will be implemented as widget actions in Casewhere.

The screenshot below illustrates how widget actions appear to end users on worker sites.

In Casewhere Admin, the widget actions will appear to developers as shown below. As illustrated, there are two types of widget actions, Trigger a Workflow and Open a Page.

Settings for widget actions are organized into three main areas:

General: Includes key attributes, triggered workflows, appearance, and other general settings.
Advanced: Covers advanced behaviors and rules, often requiring scripting.
Security: Defines security policies to determine who can view and execute the actions.

Trigger-workflow action

The action triggers a workflow and opens it in a dialog. The screenshot below illustrates how a workflow is triggered and loaded on the worker site.

The action settings look as follow.

Name	Mandatory	Description
Name	Yes	The unique name referring the action.
Label	Yes	The button label is displayed to end users and accepts a text resource key.
Workflow Definition	Yes	The workflow triggered when the action is executed. If the workflow type is 'Case Creation', a process is also required.
Css Class	No	To decorate the button, for example, the "Delete" button can be highlighted using `btn-danger`.
Icon	No	To decorate the button, for example, the icon for a "Delete" button could be `fa fa-trash`.
Auto Refresh Page	No	When selected, Casewhere will automatically refresh the page data, including all widgets within it. This is useful when the action causes changes that need to be reflected across all areas of the page.
Auto Show on Widget	No	By default, the action button is visible. However, if the setting is not selected, the button will be hidden, though the action can still be triggered via scripting.
Auto Refresh Data	No	When selected, the action will be triggered when users double-click on a widget data item.

Open-page action

The action will open a new page inside a dialog. The screenshot below illustrates how a page is loaded on the worker site.

TBD

The action settings look as follow.

Name	Mandatory	Description
Name	Yes	The unique name referring the action.
Label	Yes	The button label is displayed to end users and accepts a text resource key.
Page	Yes	The page to be opened.
Query String Parameters	No	A list of key-value pair parameters sent to the page for data loading. The key is used to access the parameters in widget data queries. The value supports a JavaScript expression, such as `dataObject.Id`.
Require Parameter	No	When selected, Casewhere requires parameters to trigger the action. This means end-users must select a data item on the widget to activate the action.
Window Size	No	Large, medium, or small.
Css Class	No	To decorate the button, for example, the "Delete" button can be highlighted using `btn-danger`.
Icon	No	To decorate the button, for example, the icon for a "Delete" button could be `fa fa-trash`.
Auto Refresh Page	No	When selected, Casewhere will automatically refresh the page data, including all widgets within it. This is useful when the action causes changes that need to be reflected across all areas of the page.
Auto Show on Widget	No	By default, the action button is visible. However, if the setting is not selected, the button will be hidden, though the action can still be triggered via scripting.

Advanced settings

The advanced settings look as follow.

Name	Description
Deactivate Rule `deprecated`	This setting controls whether the action is enabled. Note that this action is deprecated; you should use the Security function instead.
Hide Rule `deprecated`	This setting determines whether the action is visible. Note that this action is deprecated; you should use the Security function instead.
Client Visible Rule	A JavaScript expression used to determine if the action is visible or not.
Client Enable Rule	A JavaScript expression used to determine if the action is enabled or not.
Label Rule	A JavaScript expression used to dynamically set the button label.
On Executed	A callback triggered when the triggered workflow finishes, and the workflow or page dialog is closed.
Parameter Rule	To send additional data to the triggered workflows.

Example 1: The button will be visible when users select a data object.

Use the following expression for the Client Visible Rule.

model.selectedDOs && model.selectedDOs.length > 0

Example 2: The "Delete" button will be enabled when users select a "Draft" application.

Use the following expression for the Client Enable Rule.

model.selectedDOs && model.selectedDOs[0] && model.selectedDOs[0].Status == "Draft"

Example 3: Open a viewing-data page after the creation workflow is completed.

Use the following expression for the On Executed.

dataObjects && dataObjects.length && $scope.widgetApi.runWidgetAction("View", dataObjects)

Example 4: Set parameters for widget action, for example, add an item to a parent object.

TBD

Security

You can manage who can view and trigger widget actions by assigning the appropriate security rules, similar to how rules are applied to protect pages and widgets.

Typically, a widget action should inherit security rules from its parent elements, such as the widget and the page. This is achieved by selecting "Can Inherit From The Parent Security Policy", which is also enabled by default.

Security rules for widget actions have two scopes. The following examples will demonstrate how each scope can be used:

Example 1: Access rules to determine if the widget action should be visible or not.

#predicate
return @user.Contains("Roles", "Administrator");

Example 2: Widget action rules to determine if the widget action can be executed or not.

#predicate

var dataApi = @apiFactory.Get<IDataApi>();
var applicationId = @parameters["DOIds"][0];
var application = dataApi.Load(applicationId); 

return application["Status"] == "Submitted";