Rodzaje funkcji w gniazdach rozszerzeń Wapro Anywhere

W Wapro Anywhere udostępniono możliwość korrzystania z nastepujących funkcji dla gniazd rozszerzeń:

• Procedura SQL,
• Moduł wykonywalny,
• Komunikat - otwarcie okna komunikatu,
• Pytanie - otwarcie okna zapytania,
• Koniec - funkcja kończąca działanie gniazda rozszerzeń,
• Tabela dodatkowa - wyświetlenie tabeli dodatkowej,
• Formularz tabeli - wyświetlenie formularza tabeli dodatkowej,
• IF (warunek) THEN ELSE - instrukcja warunkowego wykonania.

Wszystkie kategorie funkcji mają różne parametry zależnie od ich typu. Niemniej jednak istnieją pewne elementy wspólne dla każdej z funkcji:

• nazwa funkcji- to obowiązkowe pole, w którym należy wprowadzić unikalną nazwę dla definiowanej funkcji;
• opis - ten obszar pozwala na zawarcie dodatkowego komentarza dotyczącego działań, jakie realizuje dana funkcja.

Podpowiedź

Warto odpowiednio nazywać gniazda, ich etapy oraz notować co wykonują poszczególne etapy gniazda. Ułatwia to zdecydowanie zrozumienie logiki zapisanej w gniazdach po jakimś czasie lub kiedy logikę musi przeanalizować inna osoba.

Zarówno nazwa, jak i opis widoczne są w Edytorze gniazd rozszerzeń bez konieczności otwierania formularza. Wygląd formularza ulega zmianie w zależności od wybranego typu funkcji dostępnego z listy.

W dalszych rozdziałach zostaną szczegółowo omówione parametry, które można przekazać w poszczególnych typach funkcji.

Procedura SQL

Funkcja Procedury SQL stanowi fundamentalny element w gniazdach rozszerzeń. Aby móc skutecznie wywołać procedurę SQL za pomocą gniazda, istnieją dwa wymagania do spełnienia:

1. Procedura musi istnieć w bazie danych i posiadać parametry, które należy przekazać w dokładnie takiej kolejności i typach, jak zdefiniowano w polu Lista parametrów.
2. Nazwa procedury musi być zapisana w ustalonym formacie tj. musi zaczynać się od ciągu znaków "MAGSRC_".

Podpowiedź

W przypadku gniazd definiowanych w Wapro Anywhere liczba parametrów do procedury została ograniczona do minimum. Dane z aplikacji w formie zmiennych przekazywane są nie jak dotychczas w przypadku wersji desktop w formie niezależnych parametrów a w formie obiektu JSON. Obiekt zawiera zapisane wszystkie pola, które dostępne są na formularzu, który uruchamia gniazdo. Podejście takie pozwala dowolnie dostarczać ilość zmiennych do gniazd bez konieczności zmiany prototypu procedury SQL. Dodatkowo dodawanie nowych pól na formularzach w kolejnych wersjach aplikacji automatycznie daje programiście dostęp do tych pól.

Pamiętaj

Nie wszystkie pola przekazane w obiekcie do procedury mogą być nadpisane w procedurze i zmienione po zakończeniu działania gniazda zwrotnie w formularzu aplikacji.

Parametry w gniazdach Wapro Anywhere do procedur SQL mają określoną strukturę i nazwy i dostepne są w definicji przykładowej procedury. Procedura powinna mieć 4 parametry - operowanie zmiennymi odbywa się na zasadzie obiektu JSON zarówno w danych wejściowych ja i wyjściowych:

• @sesion varchar(max) - w tej zmiennej znajdują się wszystkie informacje o sesji w aplikacji (dostępne tu są informacje o aktualnie wybranej firmie, magazynie, użytkowniku czy języku)
• @data varchar(max) - w tej zmiennej zawarte są pola formularza lub listy, która dostępna była akurat w danym gnieździe
• @result varchar(max) - w tej zmiennej dostępny jest obiekt analogiczny do @data ale już po zmianie danych (jeśli procedura nadpisała w obiekcie @data dane w jakimś polu to zmienna @result będzie interpretowana na aplikacji frontend celem ustawienia nowej wartości w polu formularza po wykonaniu gniazda)
• @errorData varchar(max) - w tej zmiennej znajdują się ewentualne informacje o błędach, które aplikacja powinna odebrać w przypadku wystąpienia błędu w trakcie wykonania procedury

Podpowiedź

Schemat procedury w aplikacji zawarty w aplikacji Wapro Anywhere pokazuje w jaki sposób odczytywać z poszczególnych obiektów dane oraz jak je w nich modyfikować aby za pomocą gniazda zmienić zawartość w kodzie SQL a następnie aby aplikacja zinterpretowała nowe wartości i odświeżyła je w formularzu aplikacji.

Skompletowaną listę potrzebnych parametrów należy zatwierdzić przyciskiem F10, co generuje w polu Lista parametrów formularza edycji funkcji zgodną ze składnią SQL listę zmiennych i ich typów oddzielonych przecinkami.

Po zdefiniowaniu listy parametrów przez gniazdo procedury SQL możliwe jest podejrzenie sugerowanego schematu tworzenia takich procedur, które zostały opracowane przy założeniu, że procedury będą zmieniały dane w bazie - stąd ujęcie kodu procedury w transakcję.

Informacja

Kod procedury SQL wgrywany do bazy danych jest poza aplikacją Wapro Anywhere za pośrednictwem np. Management Studio lub aplikacji Wapro Sql Klient dostępnej z poziomu aplikacji Wapro Mag desktop.

Za pomocą klawisza F3 uruchamiany jest edytor, zawierający schemat procedury. Schemat jest od razu dostosowany do definicji funkcji, tzn. zawiera nazwę i parametry procedury SQL, które zostały wcześniej zdefiniowane (pole Nazwa i Lista parametrów).

Należy pamiętać o specyficznym sposobie obsługi błędów sygnalizowanych w procedurze SQL (błędów wykonania SQL). Gniazda automatycznie po odebraniu sygnalizacji błędu wyświetlają komunikat o błędzie (zwracany z SQL funkcją raiserror) i przerywają dalsze wykonanie kodu zarówno umieszonego w gnieździe rozszerzeń, jak i standardowego kodu programu, którego wykonanie nastąpiłoby normalnie po zakończeniu kodu gniazda.

Moduł wykonywalny

Pamiętaj

Moduł wykonywalny może być uruchomiony z komputera użytkownika z wykorzystaniem modułu Wapro Interkonektor. W przypadku usługi Wapro Anywhere uruchamianie modułu, który wymaga podpięcia zwrotnie do bazy SQL Server na której pracuje użytkownik nie jest możliwe.

Moduły rozszerzeń muszą mieć postać wykonywalnych programów tzn. typu EXE.

W polu Ścieżka do modułu należy wskazać lokalizację pliku modułu rozszerzeń wraz z jego nazwą widoczną dla wszystkich stacji roboczych Wapro Anywhere. W szczególnym przypadku może to być katalog instalacyjny programu (nie jest to zalecana opcja).

W polu Lista parametrów można przekazać wartości zmiennych dostępnych w gnieździe. Wartości będą oddzielone przecinkami i ujęte w cudzysłów, zgodnie z zasadami przekazywania parametrów do programów w środowisku systemu operacyjnego. Pole to jest odpowiednikiem kolekcji parametrów, które w przypadku wersji desktop przekazywane były jako drugi parametr.

Podpowiedź

W wersji exe struktura parametrów do modułu exe była następująca "serwer,baza,użytkownik,hasło" "parametr1, parametr2, parametr3" czyli tablica tablic z parametrami. W wersji Wapro Anywhere użytkownik definiuje tylko listę parametrów jaka ma być przekazana - parametr połączenia jest dodawany automatycznie. Pamiętaj, że w przypadku Wapro Anywhere Online moduł wykonywalny nie ma połączenia do serwera bazy danych tak jak ma to miejsce w lokalnej instalacji Wapro Mag + moduł wykonywalny lokalnie na komputerze użytownika.

Moduł powinien również odbierać wartość parametrów połączenia do bazy danych (tzw. Connection String), przekazywaną jako Parametr 1. Parametry połączenia podawane są w kolejności: nazwa serwera, nazwa bazy danych, użytkownik serwera, hasło użytkownika serwera oddzielone przecinkami i ujęte w cudzysłowy.

Komunikat

Komunikat wyświetla na ekranie okno dialogowe z przyciskiem OK. W polu Treść komunikatu można wstawić dowolny ciąg tekstowy lub wartość zmiennych wybranych przyciskiem Dodaj w sekcji Lista parametrów. Umieszczenie w gnieździe funkcji typu Komunikat i uruchomienie wykonania powoduje wstrzymanie dalszego przetwarzania kodu do czasu zamknięcia okna komunikatu.

Pytanie

Funkcja typu Pytanie wyświetla na ekranie okno dialogowe z przyciskami TAK i NIE. Podobnie jak w przypadku funkcji Komunikat możemy w treści pytania umieścić wartości dostępnych zmiennych w gnieździe, w którym uruchomione zostanie pytanie. Naciśnięcie przez użytkownika przycisku TAK w odpowiedzi na pytanie ustawia zmienną @OdpNaPytanie dostępną w gniazdach na wartość "1", zaś wybór przycisku NIE powoduje przypisanie wartości "0".

Sprawdzenie wartości zmiennej i podjęcie dalszych działań umożliwia funkcja typu IF (warunek) THEN ELSE (instrukcja warunkowego wykonania).

Funkcja typu Pytanie jest funkcją interakcji z użytkownikiem toteż jej wykonanie w gnieździe wstrzymuje wykonanie dalszej części kodu do czasu zamknięcia okna pytania.

Koniec

Funkcja Koniec przerywa bezwarunkowo wykonanie kodu gniazda rozszerzeń (nie kończy działania aplikacji). W zależności od parametru statusu końca program po wyjściu z gniazda może realizować standardową funkcjonalność (status = 1 OK) lub nie wykonywać standardowych funkcji i powrócić do miejsca, które aktywowało wykonanie gniazda (status = 0 Przerwij).

Tabela dodatkowa

Funkcja typu Tabela dodatkowa umożliwia wywołanie w kodzie gniazda okna listy wierszy tabeli dodatkowej zdefiniowanej wcześniej w programie. W polu Nazwa SQL tabeli dodatkowej należy wybrać z listy nazwę serwerową tabeli. Następnie trzeba podać wartość identyfikatora pola zależnego od kontekstu tabeli, w którym została zdefiniowana (czyli klucza obcego tabeli). Przykładowo jeśli tabela została zdefiniowana w kontekście firmy, należy podać wartość identyfikatora @Session.CompanyId. Jeśli natomiast została zdefiniowana w kontekście dokumentu magazynowego, wtedy należy podać wartość dokumentu @Object.ObjectId, dla którego będą pokazywane zapisy w oknie listy wierszy tabeli. Na postawie kontekstu, w jakim została zdefiniowana tabela, program sam sugeruje nazwę identyfikatora, który jest wymagany. Wartość identyfikatora można przekazać jako wartość stałą (liczbę) lub wartość zmiennej dostępnej w gnieździe. W drugim przypadku nie ma znaczenia typ zmiennej tzn. czy zmienna jest tekstowa, czy liczbowa - ważne, aby zawierała wartość numeryczną, którą można skonwertować na wartość potrzebnego identyfikatora.

Wykonanie w gnieździe funkcji typu Tabela dodatkowa spowoduje wywołanie okna listy wierszy zdefiniowanej tabeli, zaś program będzie oczekiwał z dalszym wykonaniem kodu gniazda do czasu zamknięcia tego okna.

Formularz tabeli

Funkcja typu Formularz tabeli umożliwia wywołanie w kodzie gniazda okna formularza edycji wiersza tabeli dodatkowej. Pierwsze dwa parametry tzn. Tabela dodatkowa i Id obiektu (klucza obcego tabeli) definiuje się identycznie jak przy funkcji typu Tabela dodatkowa. Trzecim parametrem jest Id wiersza, w którym podajemy wartość kolumny Identyfikator generowanej automatycznie podczas definiowania tabeli dodatkowej.

Formularz może być wywołany w trybie dodawania lub poprawiania. Wstawienie wartości "0" (lub zmiennej zwracającej wartość zero) spowoduje, że formularz będzie uruchomiony w trybie dodawania wiersza do tabeli dodatkowej. Wstawienie wartości większej niż "0" spowoduje uruchomienie formularza w trybie poprawiania wiersza o identyfikatorze wiersza równym podanej wartości.

Zatwierdzenie formularza skutkuje ustawieniem wartości zmiennej @Status, dostępnej w gnieździe na "1", zaś anulowanie - ustawieniem wartości "0". Można więc za pomocą warunku @Status > 0 w instrukcji warunkowego wykonania kodu sprawdzić, czy użytkownik zatwierdził, czy anulował formularz i uzależnić od tego sposób dalszego wykonania kodu gniazda.

IF (warunek) THEN ELSE

Instrukcja warunkowego wykonania kodu gniazda IF (warunek) THEN ELSE umożliwia sterowanie wykonaniem funkcji zdefiniowanych w gnieździe w zależności od spełniania lub nie warunku podanego jako jej parametr. Warunek musi zwracać logiczną wartość "PRAWDA" lub "FAŁSZ". Warunek, którego sprawdzenie zwraca wartość "PRAWDA", powoduje przeniesienie sterowania do miejsca oznaczonego w edytorze gniazd rozszerzeń THEN i wykonanie sekwencji funkcji zaś zwrócenie wartości "FAŁSZ" (niespełnienie warunku) powoduje, że wykonane zostaną funkcje po ELSE, zaś te, które zostały umieszczone po THEN zostaną pominięte.

Instrukcja warunkowego wykonania jest funkcją złożoną tzn. jej umieszczenie w gnieździe powoduje powstanie dwóch gałęzi drzewa. Do gałęzi zawierającej w nazwie THEN dołączamy funkcje, których wykonanie będzie poprawne w przypadku spełnienia warunku zaś do gałęzi zawierającej w nazwie ELSE dołączyć należy funkcje, które powinny wykonać się, gdy warunek nie jest spełniony.

Nie ma znaczenie poziom, na którym funkcje po ELSE są dołączone tzn. wykonanie funkcji pokazanych na poniższym obrazie:

Warunek buduje się w oparciu o zmienne. Wartości zmiennych można porównywać ze stałymi lub innymi zmiennymi za pomocą standardowych operatorów, np. ">", "<", "=" itp.

Poszczególne elementy w warunku można łączyć operatorami logicznymi OR, AND. Stałe tekstowe należy ująć w cudzysłów.

Kartoteka

Kartoteka to specjalny typ gniazda, który umożliwia wywołanie standardowej kartoteki jednego z wybranych modułów:

• Artykuły
• Kontrahenci
• Pracownicy
• Magazyny
• Kategorie artykułów

Gniazdo to umożliwia w dedykowanej logice u klienta uruchomić standardową kartotekę systemową tak aby np. w gnieździe gdzie użytkownik na formularzu musi wybrać kontrahenta można było to zrobić za pomocą podstawowej kartoteki dostępnej w programie.