Action

Form actions are user components that allow you to perform any action on the task form in response to user actions, data changes or other form events. Examples of actions can, for example.

• perform mathematical calculations, e.g. convert net amounts, sum values, calculate rates
• add comments
• display messages
• communicate with the server in order to download data
• freely change the values of task variables (via FormAPI)

The created actions are available in the process editor and can be easily used in the business process enabling the execution of business logic. Their behavior can be further configured using parameters.

Defining actions

Actions are created based on their definition created by the user. Such a definition must contain the following elements:

1. An annotation @Actions (if the action is not defined in the plug-in, it must come from the com.suncode package)
2. An annotation @ActionsScript An annotation transferring the path to the script (from classpath) containing the JavaScript implementation, or the path along with the fragments in which the script will be placed (for example, if the action is placed in the process history). In the first case, we specify only the path, while in the second case the path lands in the value parameter, and the fragments in the fragments object. The available values for fragments can be found in the class ActionUIFragment.
3. Public method annotated @Define  with a single parameter ActionDefinitionBuilder (many different actions can be defined in a single @Actions class)

An action can also provide a script that builds the appearance of parameters when it is defined in the PWE. To do this, add another annotation for the class @ComponentsFormScript with the path to the script transferred (from classpath).

An example definition is shown below:

@Actions
@ActionsScript( "actions/example.js" )
@ComponentsFormScript( "actions/example-form.js" )
public class ExampleActions
{
	@Define
    public void action( ActionDefinitionBuilder action )
    {
		action
            .id( "hide-variables" )
            .name( "action.hide-variables.name" )
            .description( "action.hide-variables.desc" )
            .icon( SilkIconPack.EYE )
            .category( Categories.TEST )
            .destination( ActionDestination.button() )
            .parameter()
                .id( "variables" )
                .name( "action.hide-variables.variables.name" )
                .description( "action.hide-variables.variables.desc" )
                .type( Types.VARIABLE_ARRAY )
                .create();
	}
}

Sample definition for an action placed both on the form and in the history:

@Actions
@ActionsScript( value = "actions/example.js", fragments = { ActionUIFragment.FORM, ActionUIFragment.HISTORY } )
public class ExampleActions

Destination elements (destination)

Destination elements are indicated at the action definition stage in the destination()method. They specify to which form elements the action can be added:

Element	Description	Examples of actions	Selection in PWE
ActionDestination.form()	Form The action added to the form is initiated with the formInit method.	Actions in which the main element cannot be indicated, e.g. hiding multiple variables at the same time
ActionDestination.variable()	Variable The action added to the form variable is initialized with the variableInit method in the parameter receiving an object of this variable (PW.form.variable.Variable).	Actions in which it is possible to clearly indicate the variable to which the action applies (to the greatest extent), e.g. hiding a variable live validation of a variable (e.g. showing a message without acceptance)
ActionDestination.variableSet()	Dynamic table The action added to the form variable is initialized with the variableSetInit method in the parameter receiving a dynamic table object (PW.form.field.VariableSet).	Actions that apply to a dynamic table and need its identifier, for example. add a title to the table based on calculations import data into the table (action adds a button to the table)
ActionDestination.button()	Button The action added to the form button is initialized with the buttonInit method in the parameter receiving the button object (PW.form.button.Button).	Actions whose source is a button, e.g. adding a comment before acceptance displaying messages after clicking the button
ActionDestination.dtButton()	Table button The action added to the form's table button is initialized with the dtButtonInit method in the parameter receiving the button object (PW.form.button.DtButton).		The action is added at the add/edit level of the form table button:
ActionDestination.label()	Label The action added to the label on the form is initialized with the labelInit method in the parameter receiving the label object (PW.form.field.Label).

Action initialization

The creator of the process in action can specify its initialization type. Available types:

• No initialization (NONE)

• Single initialization (SINGLE)

• Continuous initialization (CONTINUOUS)

The selected parameter is readable by the action in the getInitializationType function. Setting this parameter DOES NOT affect the operation of the action unless the action creator has implemented it.

Assigning a target element to a parameter (bindTo)

The selected target element of the action can be transferred to the action parameter by specifying the target parameter ID in the bindTo parameter. E.g.

ActionDestination.variable( "text" );  // 'text' to identyfikator parametru akcji

With the action configured in this way, if we add it to any variable, the variable will automatically be set as the value of the parameter. Depending on the target element in the parameter will be entered:

Variable

Dynamic table

Button

Implementation of actions

The form action defined on the server must be registered and implemented on the browser side. Registration is enabled by the class PW.form.action.Actions using the method create. The first parameter of the method is the action id (the id must correspond to the action that has been defined on the server), the second parameter is the action implementation object:

PW.FormActions.create('hide-variables', {
    init: function(){
    	this.variables = this.get("variables");
    	this.variablesNames = [];
    },
    
    enable: function(){
    	this.hideVariables();
    },
    
    disable: function(){
    	this.showVariables();
    },
    
    hideVariables: function() {
    	this.setVariablesVisibility(false);
    },
    
    showVariables: function() {
    	this.setVariablesVisibility(true);
    },
    
    setVariablesVisibility: function(visible) {
    	PW.each(this.variables, function(variable){
    		if(visible){
    			variable.show();
    		}
    		else{
    			variable.hide();
    		}
		}, this);
    }
});

Default actions

In order to simplify the creation of actions that react to default events of target elements, it is possible to define so-called default actions.

The creator of the action can declare functions that will execute automatically if an event associated with the target element of the action occurs, e.g. if the action is added to a button, clicking on this button will trigger the defined default action.

Default events depending on the action target element:

ActionDestination.button()

button

defaultActions: {
	button: function(button){
		// do some job
		return false;
	}
}

ActionDestination.variable()

variable

ActionDestination.variableSet()

variableSet

ActionDestination.form()

form

ActionDestination.dtButton()

Below is an example implementation of an action showing a configured message. Depending on the target element, the message will show when you press a button, change the value of a variable or change the data in a table.

PW.FormActions.create('message', {
	
	// domyślne akcje
	defaultActions: {
		button: function(button){
			this.showMsg();
		},
		variable: function(variable, newValue, oldValue){
			this.showMsg();
		},
		variableSet: function(variableSet, added, updated, removed){
			this.showMsg();
		},
		dtButton: function(button){
			this.showMsg();
		},
	},	
	
	showMsg: function(){
		ServiceFactory.getMessageService().showSuccess(this.get('msg'));
	}
});

Multiple sources (targets) of action

It is possible to specify more than one source (target) for an action, for example, to call exactly the same action if the value of one of the many specified variables has been changed. To add support for multiple targets for an action, call multitarget() in the builder:

	@Define
    public void action( ActionDefinitionBuilder action )
    {
		action
            .id( "hide-variables" )
            .name( "action.hide-variables.name" )
            .description( "action.hide-variables.desc" )
            .icon( SilkIconPack.EYE )
            .category( Categories.TEST )
			.multitarget()
            .destination( ActionDestination.button() )
            .parameter()
                .id( "variables" )
                .name( "action.hide-variables.variables.name" )
                .description( "action.hide-variables.variables.desc" )
                .type( Types.VARIABLE_ARRAY )
                .create();
	}

If the action has been added (dragged) to:

• buttons
• header variables
• tables

it is possible to add more objects of the same type as sources for calling the action. If the source is a table, the successively added objects must be table variables. The action remains one and the same JavaScript object, but more than one object can trigger defaultActions events:

• for buttons - each of the added buttons triggers the button event when clicked, passing itself to the event function
• for header variables - each of the added variables, after changing the value, triggers the variable event passing itself to the event function
• for table - if no additional table variables are specified, any change in the dynamic table triggers the variableSet. If additional variables are specified - a change in the dynamic table triggers the variableSet event only if the change occurred in any of the defined tabular variables (when adding or deleting a row, the variableSet event is always triggered).

Also, initialization of actions for specified variables changes its behavior slightly:

• buttonInit - transfers an array of buttons (even when only one button is specified)
• variableInit - transfers an array of header variables (even when only one variable has been specified)

The lightning symbol is displayed with each added target, but editing such an action is global.

Registration of actions in the plugin

If the action is defined in the plugin then you should additionally indicate that the plugin provides the action. To do this, add an entry in the suncode-plugin.xml file:

<!-- Sharing actions --> 
<workflow-components key="components" />