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

Przykładowa definicja przedstawiona jest poniżej:

@Actions
@ActionsScript( "actions/example.js" )
@ActionsFormScript( "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 (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)
ActionDestination.variableSet()	Tabelka dynamiczna Akcja dodana do zmiennej formularza inicjowana jest metodą variableSetInit w parametrze otrzymując obiekt tabelki dynamicznej (PW.form.field.VariableSet).	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 (PW.form.button.Button).	Akcje których źródłem jest przycisk np. dodawanie komentarza przed akceptacją wyświetlanie komunikatów po kliknięciu przycisku

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.form.action.Actions za pomocą metody create. 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.

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

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();
		}
	},	
	
	showMsg: function(){
		ServiceFactory.getMessageService().showSuccess(this.get('msg'));
	}
});

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