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

1. 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

   .
2. 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:

         .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();
	}
}

Przykładowa definicja dla akcji umieszczonej zarówno na formularzu, jak i w historii:

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

Elementy docelowe (destination)

Elementy docelowe wskazywane są na etapie tworzenia definicji akcji w metodzie destination(). Określają one, do jakich elementów formularza może być dodana akcja:

Element	Opis	Przykłady akcji	Wybór w PWE
ActionDestination.form()	Formularz Akcja dodana do formularza inicjowana jest metodą formInit.	Akcje w których nie można wskazać głównego elementu np. ukrywanie wielu zmiennych jednocześnie	Image Modified
ActionDestination.variable()	Zmienna Akcja dodana do zmiennej formularza inicjowana jest metodą variableInit w parametrze otrzymując obiekt tej zmiennej ( Jsdoc property jsdoc.plusworkflow className PW.form.variable.Variable ).	Akcje w których można jednoznacznie wskazać zmienną, której akcje dotyczy (w największym stopniu) np. ukrywanie zmiennej walidacja zmiennej na żywo (np. pokazanie komunikatu bez akceptacji)	Image Modified

ActionDestination.dtButton()

ActionDestination.label()

Inicjalizacja akcji

Twórca procesu w akcji określić może jej typ inicjalizacji. Dostępne typy:

• Brak inicjalizacji (NONE)
• Pojedyncza inicjalizacja (SINGLE)
• Ciągła inicjalizacja (CONTINUOUS)

Wybrany parametr jest możliwy do odczytu w akcji w funkcji getInitializationType. Ustawienie tego parametru NIE WPŁYWA na działanie akcji, jeżeli nie zaimplementował tego twórca akcji.

Przypisanie elementu docelowego do parametru (bindTo)

Wybrany element docelowy akcji może zostać przekazany do parametru akcji poprzez podanie w parametrze bindTo identyfikatora parametru docelowego. Np. 

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

Z tak skonfigurowaną akcją, jeżeli dodamy ją do dowolnej zmiennej, zmienna to zostanie automatycznie ustawiona jako wartość parametru. W zależności od elementu docelowego w parametr wpisane zostaną:

Zmienna

Tabelka dynamiczna

Przycisk

Implementacja akcji

Zdefiniowana na serwerze akcja formularza musi zostać zarejestrowana i zaimplementowana po stronie przeglądarki. Rejestrację umożliwia klasa 

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);
    }
});

Akcje domyślne

W celu ułatwienia tworzenia akcji które reagują na domyślne zdarzenia elementów docelowych możliwe jest zdefiniowanie tzw. akcji domyślnych.

Twórca akcji może zadeklarować funkcje, które wykonają się automatycznie, jeżeli wystąpi zdarzenie skojarzone z elementem docelowym akcji np. jeżeli akcja dodana jest do przycisku, to klikniecie w ten przycisk spowoduje wywołanie zdefiniowanej akcji domyślnej.

Zdarzenia domyślne w zależności od elementu docelowego akcji:

ActionDestination.button()

button

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

ActionDestination.variable()

variable

ActionDestination.variableSet()

variableSet

ActionDestination.form()

form

ActionDestination.dtButton()

Poniżej przykładowa implementacja akcji pokazującej skonfigurowaną wiadomość. W zależności od elementu docelowego wiadomość pokaże się przy naciśnięciu przycisku, zmianie wartości zmiennej lub zmianie danych w tabelce.

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'));
	}
});

Wiele źródeł (targetów) akcji

Możliwe jest określenie więcej niż jednego źródła (targetu) dla akcji np. w celu wywołania dokładnie tej samej akcji, jeżeli została zmieniona wartość jednej z wielu określonych zmiennych. Aby dodać wsparcie do wielu targetów dla akcji, w builderze należy wywołać multitarget():

	@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();
	}

Jeżeli akcja została dodana (przeciągnięta) do:

• przycisków
• zmiennych nagłówkowych
• tabeli

możliwe jest dodanie kolejnych obiektów tego samego typu jako źródeł wywoływania akcji. Jeżeli źródłem jest tabela, kolejno dodawane obiekty muszą być zmiennymi tabelarycznymi. Akcja pozostaje jednym i tym samym obiektem JavaScriptowym, lecz więcej niż jeden obiekt może wywołać zdarzenia defaultActions:

• dla przycisków - każdy z dodanych przycisków wywołuje po kliknięciu zdarzenie button przekazując do funkcji zdarzenia samego siebie
• dla zmiennych nagłówkowych - każda z dodanych zmiennych po zmianie wartości wywołuje zdarzenie variable przekazując do funkcji zdarzenia samą siebie
• dla tabeli - jeżeli nie określono dodatkowych zmiennych tabelarycznych, każda zmiana w tabeli dynamicznej wywołuje zdarzenie variableSet. Jeżeli określono dodatkowe zmienne - zmiana w tabeli dynamicznej wywołuje zdarzenie variableSet tylko wtedy, gdy zmiana zaszła w którejś ze zdefiniowanych zmiennych tabelarycznych (przy dodaniu lub usunięciu wiersza zdarzenie variableSet jest zawsze wywoływane).

Również inicjalizacja akcji dla określonych zmiennych zmienia nieznacznie swoje zachowanie:

• buttonInit - przekazuje tablicę przycisków (nawet, gdy określony został tylko jeden przycisk)
• variableInit - przekazuje tablicę zmiennych nagłówkowych (nawet, gdy została określona tylko jedna zmienna)

Symbol błyskawicy zostaje wyświetlony przy każdym z dodanych targetów, lecz edycja takiej akcji jest globalna.

Rejestracja akcji we wtyczce

Jeżeli akcja jest definiowana we wtyczce to należy dodatkowo zaznaczyć, że wtyczka ta udostępnia akcje. W tym celu należy w pliku suncode-plugin.xml dodać wpis:

<!-- Udostępnianie akcji --> 
<workflow-components key="components" />

1. Actions

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

   Javadoc
   displayValue

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

1. 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

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

1. ActionUIFragment

   .

2. 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

1. (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:

    .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

ActionDestination.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.FormActions.create('

	}, 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){
			

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:

<!--