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:

pesel-validator-1.0.0.jar

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 isEmpty(), 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( "validator.pesel.invalid" ), 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.invalid=Należy podać prawidłowy PESEL

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
validator.pesel.invalid=Fill with valid PESEL

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 jest, 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 walidacji. 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 isEmpty( String value )
    {
        return value == null || value.trim().isEmpty();
    }
} 

Konfiguracja wtyczki

Walidator został już zdefiniowany. Należy jeszcze "powiedzieć" systemowi, że wtyczka udostępnia walidator i funkcję 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="Validate Pesel Tutorial">
	<!-- Udostępnianie tłumaczeń -->
	<i18n key="i18n"/>
	
	<!-- Udostępnianie walidatorów --> 
	<form-validators key="validators" />
 
	<!-- Udostępnianie funkcji-->
	<functions key="functions" />

</plugin>

Wykorzystanie walidatora w zadaniu

Stworzony walidator będzie mógł być wykorzystany w edytorze procesów po uruchomieniu wtyczki. Aby sprawdzić jego działanie należy stworzyć prosty proces, a następnie dodać nasz walidator do przycisku akceptacji. Aby to zrobić należy wejść w formularz zadania, następnie wejść w edycję przycisku akceptacji i rozwinąć zakładkę Walidatory. Następnie przy pomocy przycisku należy dodać walidator.

Po dodaniu walidatora pojawi się okno z jego definicją. Należy uzupełnić parametr walidatora oraz warunek wywołania.

W tym momencie dodaliśmy walidator do przycisku akceptującego zadanie, który będzie weryfikował czy zmienna Pesel jest PESELem. Walidacja będzie wywoływana tylko jeżeli zmienna Imię i Nazwisko nie będzie pusta.

Poniżej został przedstawiony wynik walidacji błędnego PESELu.