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.

...

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

    ze ścieżką 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 loggeraction( ActionDefinitionBuilder action )
    {
		// budowanie definicji akcji
	}
}

...

action

...

• identyfikator: 

@Define
public void logger( ActionDefinitionBuilder action ) {     action         .id( "loggerhide-variables" )
            .name( "actionsaction.loggerhide-variables.name" )
            .description( "actionsaction.loggerhide-variables.desc" )
        .category( Categories.DEBUG )         .destination( ActionDestination.form() )
        .icon( SilkIconPack.APPLICATION_OSX_TERMINALEYE )
        .parameter()             .id( "msg".category( Categories.TEST )
            .namedestination( "actions.logger.param.msg.name" )
            .description( "actions.logger.param.msg.desc" )
            .type( Types.STRING ActionDestination.button() )
            .createparameter()
        .parameter()             .id( "errorvariables" )
                .name( "actionsaction.loggerhide-variables.paramvariables.level.name" )
                .description( "actionsaction.loggerhide-variables.paramvariables.level.namedesc" )
                .type( Types.BOOLEANVARIABLE_ARRAY )
                .create();
	}

Akcja musi być zdefiniowana po stronie serwera. W tym celu należy utworzyć klasę i oznaczyć ją adnotacją 

...

}

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 ( 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)	variableset
ActionDestination.variableSet()	Tabelka dynamiczna Akcja dodana do zmiennej formularza inicjowana jest metodą variableSetInit w parametrze otrzymując obiekt tabelki dynamicznej ( Jsdoc property jsdoc.plusworkflow className 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 ( Jsdoc property jsdoc.plusworkflow className 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

Image Removed

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

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

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

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ą 

...

...

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();
    },
    
    .name( "action.hiding.variables.name" )disable: function(){
    	this.showVariables();
    },
  .description( "action.hiding.variables.desc" )
    hideVariables: function() {
     	this.iconsetVariablesVisibility( SilkIconPack.APPLICATION_FORM )false);
    },
    
    .category( Categories.TEST showVariables: function() {
    	this.setVariablesVisibility(true);
    },
 .destination( ActionDestination.form() ) 
    setVariablesVisibility: function(visible) {
    	PW.parametereach()this.id( "variables", ).name( "action.hiding.variables.parameter.name" )function(variable){
    		if(visible){
       			variable.description( "action.hiding.variables.parameter.desc" ).type( Type.VARIABLE )show();
    		}
    		else{
    			variable.array().create(hide();
    		}
		}, this);
    }
}

Implementacja akcji

...

...

);

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(  disable: function(){"action.hide-variables.name" )
    	this.showVariables();     },   .description( "action.hide-variables.desc" )
    hideVariables: function() {     	this .setVariablesVisibility(false);icon( SilkIconPack.EYE )
    },        .category( Categories.TEST showMessage: function)
			.multitarget()
{     	var message = Action.t('action.hiding.variables.success', this.variables);
    	messageService.showSuccess(message);    .destination( ActionDestination.button() )
            .parameter()
    },          showVariables: function( .id( "variables" )
{     	this.setVariablesVisibility(true);
    },           .name( "action.hide-variables.variables.name" )
            setVariablesVisibility: function(visible) { 		if(visible) {
			variableService.show(this.variables);
		}
		else {
			variableService.hide(this.variables);
		}.description( "action.hide-variables.variables.desc" )
                .type( Types.VARIABLE_ARRAY )
     }      }     .create();

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

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

...

	}

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 --> 
<form<workflow-actionscomponents key="actionscomponents" />

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