Tworzenie wtyczki udostępniającej warunkowy walidator formularza.

Projekt stworzonej wtyczki jest dostępny w publicznym repozytorium http://192.168.1.61/developers/tutorials. Skompilowana wersja do pobrania tutaj:

Wstęp

Kurs ten opisuje proces tworzenia wtyczki dla systemu PlusWorkflow w wersji co najmniej 3.1. Wtyczka ta będzie udostępniała walidator formularza, który:

• sprawdzi czy podana w parametrze zmienna spełnia warunki PESELu, gdy warunek wykonania walidatora jest spełniony
• wyświetli wiadomość w przypadku, gdy zmienna nie jest PESELem.

Dodatkowo, stworzona zostanie funkcja empty() którą można wykorzystać jako warunek wywołania walidatora.

Przygotowanie walidatora

Pierwszym krokiem jest stworzenie definicji walidatora oraz jego metody walidującej. W ten sposób informujemy edytor procesów, że taki walidator jest dostępny i może zostać wykorzystany przy budowie formularza zadania. W tym celu należy stworzyć klasę z odpowiednim zestawem adnotacji oraz metodę walidującą:

@Validator
public class PeselValidator
{
    private final String PESEL_REGEX = "^\\d{11}$";
    
    @Define
    public void definition( ValidatorDefinitionBuilder builder )
    {
        builder
            .id( "pesel-validator" )
            .name( "validator.pesel" )
            .description( "validator.pesel.desc" )
            .category( Categories.TEST )
            .parameter()
                .id( "pesel_param" )
                .name( "validator.pesel.parameter.name" )
                .description( "validator.pesel.parameter.desc" )
                .type( Types.VARIABLE)
                .create();
    }
 
    //Metoda walidująca
    public void validate( @Param( value = "pesel_param" ) Variable pesel, Parameters parameters, ValidationErrors errors,
                          Translator translator )
    {
        boolean isPesel = Pattern.matches( PESEL_REGEX, (String) pesel.getValue() );
        if ( isPesel == false )
        {
            errors.add( translator.getMessage( "Należypodać prawidłowy PESEL" ), pesel.getId() );
        }
    }
}

Definicja

Powyżej zdefiniowaliśmy walidator pesel-validator z jednym parametrem tekstowym, czyli w tym miejscu będziemy chcieli otrzymać wartość zmiennej do walidacji. Jako nazwy i opisy walidatora i jego parametru podaliśmy klucze, gdyż będziemy chcieli, aby te właściwości były tłumaczone w zależności od języka użytkownika. Tłumaczenia dodajmy w plikach /resources/locale/messages.properties (domyślne - wersja polska) oraz /resources/locale/messages_en.properties (wersja angielska).

validator.pesel=Walidacja peselu
validator.pesel.desc=Walidator weryfikuje czy podany parametr jest peselem
validator.pesel.parameter.name=Pesel
validator.pesel.parameter.desc=Wartość do walidacji

validator.pesel=Validate pesel
validator.pesel.desc=Validator to validate if parameter is pesel
validator.pesel.parameter.name=Pesel
validator.pesel.parameter.desc=Value to validate

W definicji akcji podaliśmy również kategorię Categories.TEST. Niezbędne jest stworzenie takiej kategorii lub wykorzystanie kategorii, która już istnieje. Implementacja kategorii wygląda następująco:

public enum Categories
    implements Category
{
    TEST( "Test" );

    private String name;

    private Categories( String name )
    {
        this.name = name;
    }
 
    @Override
    public String getName()
    {
        return name;
    }
}

Metoda walidująca

Oprócz definicji walidatora zaimplementowaliśmy również metodę walidującą.

W metodzie walidującej zdefiniowaliśmy parametry wejściowe.

• @Param( value = "pesel_param" ) String pesel - wartość dla zdefiniowanego parametru walidatora
• Parameters parameters - obiekt zawierający wszystkie zdefiniowane parametry walidatora
• ValidationErrors errors - Obiekt, do którego można zapisać błędy walidatora
• Translator translator - obiekt translatora wtyczki

Podczas wywoływania metody do wszystkich parametrów zostaną wstrzyknięte obiekty. Wszystkie obiekty, jakie mogą być wykorzystane jako parametry wejściowe metody walidującej są opisane tutaj.

Metoda walidująca weryfikuje czy parametr pesel_param jest PESELem. Jeżeli nie, to dodaje tłumaczoną informacje o tym do obiektu ValidationErrors oraz oznacza, że chodzi o zmienną podaną w parametrze.

Przygotowanie funkcji warunkowej 

Zdefiniujemy zatem jeszcze funkcję, którą wykorzystamy jako warunek wykonania akcji. Ustawienie warunku odbywa się za pomocą narzędzia PlusWorkflowEditor.

Funkcje definiowane są w klasach oznaczonych adnotacją @Functions. Nasza definicja wygląda następująco:

@Functions
public class BasicFunctions
{
    @Function
    public Boolean lte( Float a, Float b )
    {
        return a.floatValue() <= b.floatValue();
    }
} 

Każda zarejestrowana funkcja powinna dostarczać implementację tej funkcji w języku JavaScript na potrzeby przeglądarki. Dla funkcji wykorzystywanych w akcjach formularza jest to wymagane. Implementacja jest następująca:

PW.Functions.register("lte", "boolean", ["float", "float"], function(value1, value2){
	return value1 <= value2;
});

Wykorzystanie tej funkcji jako warunek wykonania akcji oznaczać będzie, że akcji zostanie uruchomiona, gdy value1 będzie mniejsze lub równe od value2. W przeciwnym razie akcja zostanie zatrzymana.

Konfiguracja wtyczki

Akcja została już zdefiniowana. Należy jeszcze "powiedzieć" systemowi, że wtyczka udostępnia akcje i funkcje oraz korzysta z tłumaczeń. Plik suncode-plugin.xml powinien wyglądać następująco:

<?xml version="1.0" encoding="UTF-8"?>
<plugin key="${project.groupId}-${project.artifactId}" name="Hide Action Tutorial">
	<!-- Udostępnianie tłumaczeń -->
	<i18n key="i18n"/>
	
	<!-- Udostępnianie akcji --> 
	<form-actions key="actions" />
 
	<!-- Udostępnianie funkcji-->
	<functions key="functions" />

	<!-- Lokalizacja do skryptów z funkcjami-->
	<web-scripts key="formScripts" fragment="form" >
		<resource>/resources/functions/functions.js</resource>
	</web-scripts>
</plugin>

Wykorzystanie akcji w zadaniu

Stworzona akcja będzie mogła być wykorzystana w edytorze procesów po uruchomieniu wtyczki. Aby sprawdzić jej zadanie należy stworzyć prosty proces, a następnie dodać naszą akcję. Aby to zrobić należy wejść w formularz zadania następnie po lewej stronie rozwinąć Akcje i przeciągnąć naszą akcję na formularz.

Po upuszczeniu akcji na formularzu pojawi się okno z definicją akcji. Należy uzupełnić parametr akcji oraz warunek wywołania.

W tym momencie dodaliśmy akcję do zadania, która będzie ukrywać zmienne Zmiennoprzecinkowa i Data i Czas, jeżeli wartość zmiennej Całkowita będzie mniejsza bądź równa 0. W przeciwnym wypadku zmienne zostaną pokazane.

Poniżej wartość zmiennej Calkowita wynosi -2, więc zmienne zostały ukryte.

Natomiast gdy zmienna Całkowita ma wartość dodatnią to zmienne zostaną z powrotem wyświetlone.