Akcja

Akcje formularza to komponenty użytkownika, umożliwiające wykonywanie dowolnych akcji na formularzu zadania w reakcji na działania użytkownika, zmiany danych czy też inne zdarzenia formularza. Przykładowe akcje mogą np.

• przeprowadzać obliczenia matematyczne np. przeliczać kwoty netto, sumować wartości, obliczać kursy
• dodawać komentarze
• wyświetlać komunikaty
• komunikować się z serwerem w celu pobrania danych
• dowolnie zmieniać wartości zmiennych zadania (poprzez FormAPI)

Stworzone akcje dostępne są w edytorze procesów i mogą być łatwo wykorzystane w procesie biznesowym umożliwiając tym samym realizacje logiki biznesowej. Ich zachowanie może być dodatkowo konfigurowane za pomocą parametrów. 

Definiowanie akcji

Akcje tworzone są w oparciu o ich definicję stworzoną przez użytkownika. Definicja taka musi zawierać następujące elementy:

1. Adnotację 

   Javadoc
   displayValue @Actions property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.annotation.Actions

    (jeżeli akcja nie jest definiowana we wtyczce, musi ona pochodzić z pakietu com.suncode)
2. Adnotację 

   Javadoc
   displayValue @ActionsScript property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.annotation.ActionsScript

   przekazującą ścieżkę do skryptu (z classpath) zawierającego implementację w języku JavaScript lub ścieżkę wraz z fragmentami, w których skrypt zostanie umieszczony (np. w przypadku umieszczenia akcji w historii procesów). W pierwszym przypadku podajemy tylko ścieżkę, w drugim ścieżka ląduje w parametrze value, zaś fragmenty w obiekcie fragments. Dostępne wartości dla fragmentów można znaleźć w klasie

   Javadoc
   displayValue ActionUIFragment property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.ActionUIFragment

   .
3. Publiczną metodę oznaczoną adnotacją 

   Javadoc
   displayValue @Define property javadoc.plusworkflow className com.suncode.pwfl.component.annotation.Define

    z jednym parametrem

   Javadoc
   property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.ActionDefinitionBuilder

   (w jednej klasie @Actions może być zdefiniowanych wiele różnych akcji)

Akcja może również dostarczać skrypt, który buduje wygląd parametrów podczas jej definiowania w PWE. W tym celu należy dodać kolejną adnotację dla klasy 

Przykładowa definicja przedstawiona jest poniżej:

@Actions
@ActionsScript( "actions/example.js" )
@ComponentsFormScript( "actions/example-form.js" )
public class ExampleActions
{
	@Define
    public void action( ActionDefinitionBuilder action )
    {
		

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

   Javadoc
   displayValue @Actions property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.annotation.Actions

   (if the action is not defined in the plug-in, it must come from the com.suncode package)
2. An annotation

   Javadoc
   displayValue @ActionsScript property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.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

   Javadoc
   displayValue ActionUIFragment property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.ActionUIFragment

   .
3. Public method annotated 

   Javadoc
   displayValue @Define property javadoc.plusworkflow className com.suncode.pwfl.component.annotation.Define

     with a single parameter

   Javadoc
   property javadoc.plusworkflow className com.suncode.pwfl.workflow.form.action.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 

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	Image Added
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 ( Jsdoc property jsdoc.plusworkflow className 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)	Image Added
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 ( Jsdoc property jsdoc.plusworkflow className 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)	Image Added
ActionDestination.button()	Button The action added to the form button is initialized with the buttonInit method in the parameter receiving the button object ( Jsdoc property jsdoc.plusworkflow className PW.form.button.Button ).	Actions whose source is a button, e.g. adding a comment before acceptance displaying messages after clicking the button	Image Added
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 ( Jsdoc property jsdoc.plusworkflow className PW.form.button.DtButton ).		The action is added at the add/edit level of the form table button: Image Added
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 ( Jsdoc property jsdoc.plusworkflow className PW.form.field.Label ).		Image Added

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.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" />