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.

W tworzonych akcjach po stronie przeglądarki wspierany jest standard ECMAScript 6.

Definiowanie akcji

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

Adnotację (jeżeli akcja nie jest definiowana we wtyczce, musi ona pochodzić z pakietu com.suncode)
Adnotację 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 .
Publiczną metodę oznaczoną adnotacją z jednym parametrem (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 z przekazaną ścieżką do skryptu (z classpath).

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
            .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
ActionDestination.variable()	Zmienna Akcja dodana do zmiennej formularza inicjowana jest metodą `variableInit` w parametrze otrzymując obiekt tej zmiennej ().	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)
ActionDestination.variableSet()	Tabelka dynamiczna Akcja dodana do zmiennej formularza inicjowana jest metodą `variableSetInit` w parametrze otrzymując obiekt tabelki dynamicznej ().	Akcje które dotyczą tabelki dynamicznej i potrzebują jej identyfikator np. nadanie tytułu tabelce na podstawie obliczeń import danych do tabelki (akcja dodaje przycisk do tabelki)
ActionDestination.button()	Przycisk Akcja dodana do przycisku formularza inicjowana jest metodą `buttonInit` w parametrze otrzymując obiekt przycisku ().	Akcje których źródłem jest przycisk np. dodawanie komentarza przed akceptacją wyświetlanie komunikatów po kliknięciu przycisku
ActionDestination.dtButton()	Przycisk na tabeli Akcja dodana do przycisku na tabeli formularza inicjowana jest metodą dtB`uttonInit` w parametrze otrzymując obiekt przycisku ().		Akcja dodawana jest na poziomie dodawania/edytowania przycisku tabeli formularza:
ActionDestination.label()	Etykieta Akcja dodana do etykiety na formularza inicjowana jest metodą `labelInit` w parametrze otrzymując obiekt etykiety ().

Inicjalizacja akcji

Funkcjonalność jeszcze niedostępna.

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ą:

Element docelowy	Przypisana wartość
Zmienna	Zmienna
Tabelka dynamiczna	Identyfikator tabelki dynamicznej
Przycisk	Identyfikator przycisku (nazwa akcji)

Implementacja akcji

Zdefiniowana na serwerze akcja formularza musi zostać zarejestrowana i zaimplementowana po stronie przeglądarki. Rejestrację umożliwia klasa za pomocą metody . Pierwszym parametrem metody jest id akcji (id musi odpowiadać tej akcji, która została zdefiniowana na serwerze), drugim parametrem jest obiekt implementacji akcji:

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.

Akcje domyślne są wywoływane tylko jeżeli warunek wykonania akcji jest spełniony.

Parametry wywołania akcji domyślnej są takie same jak parametry zdarzeń, które są źródłem wywołania akcji domyślnej.

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

Element docelowy Nazwa funkcji Domyślne zdarzenie Opis

ActionDestination.button()

button

click (

)

Funkcja wywoływana jest po kliknięciu na przycisk, do którego dodana jest akcja.

Można przerwać akceptację formularza poprzez zwrócenie false:

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

ActionDestination.variable()

variable

change (

)

Funkcja wywoływana jest po zmianie wartości zmiennej, do której dodana jest akcja.

ActionDestination.variableSet()

variableSet

change (

)

Funkcja wywoływana jest jeżeli zmieni się wartość jakiejkolwiek zmiennej należącej do tabeli dynamicznej, do której dodana jest akcja.

ActionDestination.form()

form

enable (

)

Funkcja wywoływana jest, jeżeli zostanie spełniony warunek dla akcji.

ActionDestination.dtButton()

dtButton

click (

)

Funkcja wywoływana jest po kliknięciu na przycisk w tabeli, do którego dodana jest akcja.

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

Funkcjonalność jeszcze niedostępna.

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

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.

The ECMAScript 6 standard is supported in the browser-side actions created.

Defining actions

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

An annotation (if the action is not defined in the plug-in, it must come from the com.suncode package)
An annotation 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 .
Public method annotated with a single parameter (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 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 ().	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 ().	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 ().	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 dtB`uttonInit` method in the parameter receiving the button object ().		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 ().

Action initialization

Functionality not yet available.

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:

Target element	Assigned value
Variable	Variable
Dynamic table	Dynamic table identifier
Button	Button ID (action name)

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 using the method . 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 actions are called only if the action execution condition is fulfilled.

The parameters of the default action call are the same as the parameters of the events that are the source of the default action call.

Default events depending on the action target element:

Target element Function name Default event Description

ActionDestination.button()

button

click (

)

The function is called when you click on the button to which the action is added.

You can abort acceptance of the form by returning false:

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

ActionDestination.variable()

variable

change (

)

The function is called when the value of the variable to which the action is added changes.

ActionDestination.variableSet()

variableSet

change (

)

The function is called if the value of any variable belonging to the dynamic table to which the action is added changes.

ActionDestination.form()

form

enable (

)

The function is called if the condition for the action is fulfilled.

ActionDestination.dtButton()

dtButton

click (

)

The function is called when you click on the button in the table to which the action is added.

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

Functionality not yet available.

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