Add server actions to page actions menu

Key concepts of server actions in censhare Web.

Context

In censhare Web, server actions are available on asset pages in the page actions menu, in asset lists in the asset actions menu and in widgets in the widget actions menu. Server actions can be added to the page actions menu. The article provides basic technical information and a simple example. 

Prerequisites

Before you configure a server action in censhare Web, you must enable the server action in the censhare Admin Client.

Introduction

censhare Web server actions are based on server actions that are configured in the censhare Admin Client. You must enable and configure the server commands in the respective server actions in the censhare Admin Client. When you enable a server action in the censhare Admin Client, censhare creates a custom XML file that stores your configuration parameters.

The XML configuration file contains general configuration parameters, action metadata, and the defined command steps (Java scriptlet references). In the censhare Admin Client, the custom configuration file for a server action is stored in the respective directory in the „Modules“ folder.

When you execute a server action, the command sends the XML configuration file back and forth between the censhare server and the censhare Client.

Key concepts

Server command

Server actions execute a server command that contains one or more command steps. If a server action requires user input or interaction, the server returns the respective dialog data and options in an XSLT.

When you enable a server action, the corresponding server command is available immediately. You can enable a server action for the censhare Client, for the censhare Admin Client or for both clients.

censhare Web implementation

As of censhare 5.5, the configuration of server actions for censhare Web was improved. censhare stores the configuration in assets. Therefore, you do not need access to the server filesystem. To configure a simple server action without user interaction, only one Server action asset is required. This asset references the command name of the censhare Admin Client.

Server actions in censhare Web are based in a JSON serialization of the server command XML. censhare uses a generic CommandHandler for this purpose. To make a server action available in censhare Web, you must configure the respective assets:

• Module / Action / Server action - This asset is mandatory and references the server action configuration in the censhare Admin Client.

• Module / Dialog - Depending on the steps that users must follow when they execute an action, one or more dialog assets are necessary to configure the user interaction.

• Module / Script - Depending on the complexity of an action, a script asset is necessary to process the data.

The Server action asset, Dialog asset and Script asset form an asset structure as shown in the image below:

Asset structure for a complex server action configuration in censhare Web: The Server action asset (1) references a Dialog asset (2). The reference (4) is stored in the "Action dialog" feature. The Dialog asset (2) and the Script asset (3) are related through a "JavaScript Controller" relation (5).

Configure the Server action asset

To enable and configure a server action in censhare Web, open the respective Server action asset and edit the "Properties" widget in the "Overview" tab:

Configure the dialog assets

To configure censhare Web server actions that require user input or interaction, a dialog is required. censhare stores the dialog templates in "Module / Dialog" assets. The Dialog asset contains an HTML master file where you configure the UI elements and necessary parameters. Dialog assets are referenced in the "Action dialog" feature (ID: censhare:action.dialog.) of the Server action asset. Use the "Action dialogs" widget in the Server action asset to create a reference.

In the Dialog asset, the corresponding command step must be referenced in the "Server action dialog key" feature (ID: censhare:action.server.dialog-key). The value corresponds to the command step key of the command XML snippet. If a dialog consists of multiple command steps, you must configure a dialog asset for each step and add the dialog to the Server action asset.

Configure the Script asset

To pass the data of the server command into the dialog templates, you must add a simple JavaScript controller. To do this, you create a "Module / Script" asset and relate it to the corresponding Dialog asset. The JavaScript is stored in the master file of the Script asset. The default controller for server actions provides scope access to the commandData. The commandData is the JSON representation of the server-side command XML:

$scope.cmd = commandData.cmd;

This allows to write data from the client (for example: data entered in the HTML dialog) into the command and send these data to the server for processing. If a more complex logic is required for the implementation of a server action, you can use the controller asset to prepare the data for the dialog template via JavaScript.

To add a JavaScript controller to your server action, you have to create a "Module / Script" asset and create an asset relation from the corresponding Dialog asset to this Scrip asset. Use the "JavaScript controllers" widget in the Dialog asset to add a Script asset.

For the JavaScript controller, all censhare Web frontend API options are available. For example:

function controller($scope, commandData) { if (commandData && commandData.cmd) { $scope.cmd = commandData.cmd; } // logic }

NOTE: In the command XML, attribute names contain a "-" (minus) as separator. For example, "transformation-key". In JavaScript, use an array to access these XML structures. Inside the array, the attribute name is defined as string. For example, "cmd.config['transformation-key']".

Action groups

Optionally, you can group server actions into a sub-menu of a menu item. Menu items that contain multiple server actions in censhare Web are called "Action groups". Use this option to improve the structure and usability of the censhare Web action menus.

To configure an Action group, you must create a "Module / Action group" asset. In this asset, you can define a default name and localized names, a resource key and an optional icon.

To show a server action in an action group, create a reference to the desired Action group asset in the server action asset. To do this, use the Actions widget in the "Overview" tab of the Server actions asset.

Example

The following example shows how to setup a simple server action in censhare Web. Simple server actions do not require any user interaction or input. Therefore, you only have to create a Server action asset. No Dialog or Script assets are required.

The server action in the example is called "Rename asset" and executes an XSLT that renames the asset from which the action is executed.

Note: The XSLT of this server action is not part of this example configuration.

To configure the server action in censhare Web, do the following:

1. Enable the server action in the censhare Admin Client in the "Modules/Configuration/Transformations" directory and update your server configuration.

2. Open the custom configuration of the newly created server action and copy the command name to the clipboard.

3. In censhare Web, create a new "Module / Action / Server action" asset, enter a name (for example: "Rename asset") and a resource key (for example: "censhare:action.server.transformation.rename-asset") and click OK.

4. In the newly created asset, edit the "Properties" widget in the "Overview" tab.

5. Enter localized names if you wish so. For example, "Rename asser via XSLT" for English and "Asset per XSLT umbenennen" for German.

6. Define an icon, if you wish so. For example, "cs-icon-cogwheels".

7. Select "Enabled".

8. Enter a priority value if you wish so. For example, "1000".

9. In the "Command name" field, paste the command name that you copied from the censhare Admin Client.

10. Click OK to close the dialog and SAVE to save your changes.

11. Refresh the browser page.

12. Open an asset page and open the page actions menu. The new server action "Rename asset via XSLT" appears now in the menu.

The code snippet below shows the XML representation of the Server action asset:

<?xml version="1.0" encoding="UTF-8"?>
<asset name="Server action: csXsltExecutionAction Example" type="module.action.server." application="default" domain="root." domain2="root.">
  <asset_feature feature="censhare:action.name" value_string="Rename asset"/>
  <asset_feature feature="censhare:action.icon" value_string="cs-icon-cogwheels"/>
  <asset_feature feature="censhare:action.server.command-name" value_string="transformation.aa-xslt-execution-action-20180820-1821-0"/>
  <asset_feature feature="censhare:enabled" value_long="1"/>
  <asset_feature feature="censhare:name" language="en" value_string="Rename asset via XSLT"/>
  <asset_feature feature="censhare:name" language="de" value_string="Asset per XSLT umbenennen"/>
  <asset_feature feature="censhare:resource-enabled" value_long="1"/>
  <asset_feature feature="censhare:resource-key" value_string="censhare:action.server.transformation.rename-asset"/>
</asset>

Result

The server action is available in the actions menu in censhare Web (global actions menu, page actions menu, asset actions menu or widget actions menu). When a user executes an action, the respective dialog is shown. Simple actions are executed without user interaction.