Akcja

Akcje formularza to komponenty, 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 ze ścieżką do skryptu (z classpath) zawierającego implementację
3. Publiczną metodę oznaczoną adnotacją @Define z jednym parametrem ActionDefinitionBuilder(w jednej klasie @Actions może być zdefiniowanych wiele różnych akcji)

Przykładowa definicja przedstawiona jest poniżej:

@Actions
@ActionsScript( "actions/example.js" )
public class ExampleActions
{
	@Define
    public void logger( ActionDefinitionBuilder action )
    {
		// budowanie definicji akcji
	}
}

Teraz wykorzystując obiekt ActionDefinitionBuilder definiujemy akcję:

• identyfikator: 

@Define
public void logger( ActionDefinitionBuilder action )
{
    action
        .id( "logger" )
        .name( "actions.logger.name" )
        .description( "actions.logger.desc" )
        .category( Categories.DEBUG )
        .destination( ActionDestination.form() )
        .icon( SilkIconPack.APPLICATION_OSX_TERMINAL )
        .parameter()
            .id( "msg" )
            .name( "actions.logger.param.msg.name" )
            .description( "actions.logger.param.msg.desc" )
            .type( Types.STRING )
            .create()
        .parameter()
            .id( "error" )
            .name( "actions.logger.param.level.name" )
            .description( "actions.logger.param.level.name" )
            .type( Types.BOOLEAN )
            .create();
}

Akcja musi być zdefiniowana po stronie serwera. W tym celu należy utworzyć klasę i oznaczyć ją adnotacją @Action. Adnotacja ta sprawia, że system będzie szukał definicji akcji w tej klasie. Dodatkowo należy dodać adnotację @ActionScript i jako jej wartość podać relatywną ścieżkę do skryptu z implementacją akcji. W tak przygotowanej klasie należy teraz dodać definicję akcji. W tym celu trzeba dodać metodę i oznaczyć ją adnotacją @DefineAction. Metoda musi przyjmować jeden parametr typu ActionDefinitionBuilder. W implementacji metody należy za pomocą przekazanego builder'a zdefiniować wszystkie własności akcji.

Elementy docelowe

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

Element	Opis	Przykłady akcji	Wybór w PWE
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
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)
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)
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

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

ActionDestination.variable()

variable

ActionDestination.variableSet()

variableSet

Poniżej przykładowa implementacja akcji pokazującej skonfigurowaną wiadomość. W zależności 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'));
	}
});

PW.FormActions.create('message', {
	
	buttonInit: function(button){
		this.button.on('click', this.showMsg);
	},
 
	variableInit: function(button){
		this.button.on('click', this.showMsg);
	},
 
	variableSetInit: function(button){
		this.button.on('click', this.showMsg);
	},
	showMsg: function(){
		if(this.isEnabled){
			ServiceFactory.getMessageService().showSuccess(this.get('msg'));
		}		
	}
});

Własności

• id - unikalny w obrębie całego systemu identyfikator akcji,
• name - nazwa akcji (obsługuje tłumaczenia),
• description - opis akcji (obsługuje tłumaczenia),
• icon - ikona akcji,
• category - kategoria, do której należy akcja (może być wiele),
• destination - element formularza, dla którego dostępna jest akcja (może być wiele)
• parameters - parametry akcji.

Kategorie

Kategorie ułatwiają podział oraz wyszukiwanie akcji. Opisywane są one za pomocą interfejsu ActionCategory. Dostępna jest podstawowa implementacja tego interfejsu ActionCategories, która udostępnia podstawowe kategorie. Tworząc akcję można skorzystać z tych kategorii. W przypadku braku jakiejś kategorii można ją dodać do tej implementacji bądź stworzyć własną.

Elementy formularza (destination)

Akcja może być zdefiniowana dla konkretnych elementów formularza. Definicji dokonujemy za pomocą klasy . Dostępne są następujące elementy:

• FORM (ActionDestination.form()) - cały formularz zadania,
• VARIABLE (ActionDestination.variable(parameter)) - zmienna formularza,
• VARIABLESET (ActionDestination.variableset(parameter)) - tabelka dynamiczna,
• BUTTON (ActionDestination.button(parameter)) - przycisk formularza.

Dla wszystkich elementów formularza poza FORM podczas definicji należy podać id parametru akcji (jeżeli akcja posiada parametry). Umożliwia to automatyczne podpięcie danego elementu do tego parametru podczas wyboru akcji w PlusWorkflowEditor.

Parametry akcji

Akcje mogą posiadać parametry.

Definicja parametru:

• id - id parametru,
• type - typ parametru,
• name - nazwa parametru (obsługuje tłumaczenia),
• description - opis parametru (obsługuje tłumaczenia),
• array - określa, czy parametr jest tablicą.

Jeżeli przekazana zostanie do parametru wartość innego typu niż w definicji, to zostanie ona skonwertowana do tego typu.

Definiowanie akcji

Akcja musi być zdefiniowana po stronie serwera. W tym celu należy utworzyć klasę i oznaczyć ją adnotacją @Action. Adnotacja ta sprawia, że system będzie szukał definicji akcji w tej klasie. Dodatkowo należy dodać adnotację @ActionScript i jako jej wartość podać relatywną ścieżkę do skryptu z implementacją akcji. W tak przygotowanej klasie należy teraz dodać definicję akcji. W tym celu trzeba dodać metodę i oznaczyć ją adnotacją @DefineAction. Metoda musi przyjmować jeden parametr typu ActionDefinitionBuilder. W implementacji metody należy za pomocą przekazanego builder'a zdefiniować wszystkie własności akcji.

@Action
@ActionScript( "resources/actions/test/hiding-variables-action.js" )
public class HidingVariablesAction
{
    @DefineAction
    public void action( ActionDefinitionBuilder action )
    {
        action
            .id( "hiding-variables-action" )
            .name( "action.hiding.variables.name" )
            .description( "action.hiding.variables.desc" )
            .icon( SilkIconPack.APPLICATION_FORM )
            .category( Categories.TEST )
            .destination( ActionDestination.form() )
            .parameter().id( "variables" ).name( "action.hiding.variables.parameter.name" )
            		.description( "action.hiding.variables.parameter.desc" ).type( Type.VARIABLE )
            		.array().create();
    }
}

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 konfiguracyjny akcji.

var variableService = ServiceFactory.getVariableService(),
	messageService = ServiceFactory.getMessageService(),
	Action = {
		t: PW.I18N.createT('com.suncode-actions-plugin')
	};

PW.FormActions.create('hiding-variables-action', {
    init: function(){
    	var me = this,
    		variables = me.get("variables");
		
    	me.variables = [];
		jQuery.each(variables, function(index, variable){
			me.variables.push(variable.getId());
		});
    },
    
    enable: function(){
    	this.hideVariables();
    	this.showMessage();
    },
    
    disable: function(){
    	this.showVariables();
    },
    
    hideVariables: function() {
    	this.setVariablesVisibility(false);
    },
    
    showMessage: function() {
    	var message = Action.t('action.hiding.variables.success', this.variables);
    	messageService.showSuccess(message);
    },
    
    showVariables: function() {
    	this.setVariablesVisibility(true);
    },
    
    setVariablesVisibility: function(visible) {
		if(visible) {
			variableService.show(this.variables);
		}
		else {
			variableService.hide(this.variables);
		}
    }
    
});

W przykładzie akcji wykorzystany jest mechanizm tłumaczeń:

Action = {
	t: PW.I18N.createT('com.suncode-actions-plugin')
};

Rejestracja 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 --> 
<form-actions key="actions" />

Jest to wymagane, aby nie trzeba było przeszukiwać wszystkich uruchomionych wtyczek, tylko te, które faktycznie posiadają akcje.