Model danych na interfejsie

Wiązanie pól formularza z modelem danych

Kiedy model danych jest już zdefiniowany i podpięty, możemy w formularzu wniosku powiązać konkretne pola (komponenty UI) z polami modelu. W edytorze formularza każdy komponent, który przechowuje jakąś wartość (np. pole tekstowe, pole wyboru, data itp.), posiada właściwość "Klucz modelu danych".

Jeżeli formularz jest podpięty do aplikacji, klucz można wygodnie wybrać z listy. Gdy na liście nie ma klucza, którego potrzebujemy, można wpisać go ręcznie.

Ilustracja 1. Wybór klucza modelu danych z listy (z możliwością wpisania ręcznego)

Po wskazaniu klucza dane z komponentu zostają związane z odpowiednim miejscem w modelu. Od tego momentu komponent staje się dwukierunkowo związany (two-way binding) z modelem danych – podczas inicjalizacji formularza wartość z modelu (jeśli istnieje) zostanie wczytana do pola, a gdy użytkownik wypełni lub zmieni tę wartość, zostanie ona zapisana z powrotem do modelu danych przy zapisie wniosku. Oznacza to, że po zapisaniu formularza, wszystkie powiązane pola aktualizują odpowiadające im wartości w modelu danych, dzięki czemu model zawsze odzwierciedla bieżący stan danych wniosku.

Ilustracja 1. Przykład dwukierunkowego związania za pomocą klucza modelu danych

Info: Można też stosować jednokierunkowe powiązanie pola z modelem w sytuacji, gdy chcemy jedynie wyświetlić wartość z modelu na formularzu, ale nie aktualizować jej na podstawie wejścia użytkownika. Taki jednorazowy odczyt realizuje się np. poprzez wstawienie odwołania do zmiennej modelu w tekstach (etykietach) albo użycie właściwości komponentu valueSourceId, która pobierze wartość z modelu tylko do odczytu. Standardowo jednak, dla pól edytowalnych korzystamy z powiązania dwustronnego, aby wprowadzone dane zostały zapisane.

Ilustracja 2. Przykład jednokierunkowego związania za pomocą valueSourceId

Należy pamiętać, że nie każdy komponent formularza można powiązać z modelem. Model danych ma sens tylko dla pól, które przechowują wartości. W związku z tym nie powiążemy z modelem np. takich elementów jak:

• linki (odnośniki),
• pola typu CAPTCHA,
• pojedyncze przyciski radio (poza grupami radiobuttonów),
• okna popup,
• kody QR (jeśli występują jako obraz/element dekoracyjny).

Wszystkie pozostałe pola (tekstowe, liczbowe, wybory z listy, checkboxy, daty, sekcje itp.) mogą i powinny być powiązane z modeliem danych, jeśli ich wartość ma być zachowana lub użyta poza samym formularzem. Powiązanie to zapewnia spójność – każda dana wprowadzona przez użytkownika ma swoje miejsce w modelu, skąd może być dalej przetwarzana (np. przekazana do procesu).

Wartości z modelu danych mogą być wykorzystywane w artefakcie Treść (TextContent) np.

<p>
    Przykładowa treść ${model:client.name}
</p>

Obsługa pól tablicowych (list)

Model danych umożliwia definiowanie pól będących kolekcjami (tablicami) obiektów lub wartości prostych. Jeśli w modelu dane pole ma mieć wiele powtórzeń (np. lista adresów, listę produktów, itp.), należy ustawić jego multiplicityMax > 1 (np. null dla braku górnego limitu) oraz przygotować odpowiednie źródło danych zwracające kolekcję. W formularzu takie pole może być reprezentowane np. przez Sekcję powtarzalną (Repeatable Section) z odpowiednimi polami wewnątrz. Ważne jest, by poprawnie odwoływać się do elementów tablicy w kluczach modelu:

• kolekcja[].pole – odwołanie do wszystkich wystąpień pola w kolekcji (zwraca całą listę wartości lub np. konkatenację, zależnie od kontekstu),
• kolekcja[0].pole – odwołanie do pola w pierwszym elemencie kolekcji (indeks 0 oznacza pierwszy element, 1 - drugi, itd.),
• Uwaga: Nie można pomijać indeksu! Składnia kolekcja.pole (bez [] lub indeksu) jest niepoprawna i spowoduje błąd uniemożliwiający uruchomienie formularza. Zawsze należy użyć notacji tablicowej przy odwołaniu do pól elementów kolekcji.
• Dla sekcji powtarzalnych w formularzu, w których użytkownik może dynamicznie dodawać/usuwać elementy, Eximee używa zmiennej _rowIdx przypisanej do danej sekcji, aby przekazywać indeks bieżącego wiersza. W kluczu modelu pojawia się wtedy identyfikator w postaci NazwaSekcji_rowIdx. Na przykład, jeżeli sekcja powtarzalna jest powiązana z kolekcją produkty[] i ma pole nazwa, to klucz pola w sekcji może wyglądać: produkty[NazwaSekcji_rowIdx].nazwa. Mechanizm ten zapewnia powiązanie każdego dynamicznie dodanego pola z unikalnym indeksem w modelu.

Ilustracja 3. Podpięcie pola tablicowego do sekcji powtarzalnej

Ilustracja 4. Podpięcie Comboboxa znajdującego się w sekcji powtarzalnej do modelu danych

Wykorzystanie modelu w zakładce Jakość danych

Można używać kluczy z modelu danych w zakładce Jakość danych do definiowania warunków widoczności, wymagalności lub aktywności.

Należy jednak pamiętać, że jeśli dane pole nasłuchuje zmian w innym polu, każde takie odwołanie będzie powodować ponowne zapytanie do modelu danych, co może negatywnie wpłynąć na wydajność. W takich przypadkach zaleca się pobranie wartości z modelu danych do zmiennej i korzystanie z tej zmiennej w warunkach, co pozwala uniknąć niepotrzebnych odwołań do modelu.

Ilustracja 5. Warunek widoczności z wykorzystaniem modelu danych

dataModelTransformer

Dzięki dataModelTransformer, znajdującym się w xml (zakładka "Źródło") można wpłynąć na dane, które po zapisie wniosku spadną do modelu danych.

Aby wykorzystać tę funkcjonalność, należy w xml (w ecMetadata wewnątrz iftTemplateMetadata) dodać skrypt, który będzie mógł zmodyfikować zapisywany model.

Przykład mapowania zmiennych sesyjnych do modelu danych:

<dataModelTransformer>
  <content>
      function transform(input) {
          input.put('bazaOfert.KredytNr', api.form.v1.value("agreementId"));
          input.put('bazaOfert.CIF', api.form.v1.value("cif"));
          if(api.form.v1.value("GesCheckbox5") == "false"){
              input.put('daneKlientaCis.NumerTelefonu', api.form.v1.value("phoneNumber"));
              input.put('daneKlientaCis.AdresEmail', api.form.v1.value("email"));
          }  
          return input;
      }
  </content>
</dataModelTransformer>

Przykład mapowania wartości z niewidocznych pól do modelu danych:

<dataModelTransformer>
  <content>
      function transform(input) {
              for (let node of api.form.v1.invisibleFormNodes()) {
                  if(node.model()) {
                      input.put(node.model(), '');
                  }
              }
              return input;
          }
  </content>
</dataModelTransformer>