Formularze publiczne

Podsumowanie:

Formularze publiczne to formularze, za pomocą których niezalogowany użytkownik może tworzyć instancje dokumentów w nAxiom oraz dodawać do nich załączniki. Strona formularza jest renderowana na podstawie kodu HTML, CSS i Javascript podawanego w definicji formularza. Ponadto można zdefiniować strony wyświetlane w przypadku powodzenia i niepowodzenia zapisu.

Formularz publiczny jest dostępny pod adresem URL <adres_witryny_naxiom>/front/public/<adres_względny>. Wywołanie formularza jest chronione funkcją rate limiting, a do weryfikacji, czy dane są wysyłane przez człowieka można użyć mechanizmu Google reCAPTCHA v3 .

☛ AdminSPA > INTERFEJS UŻYTKOWNIKA > Formularze publiczne

Oprócz metadanych standardowych dla obiektów w nAxiom dla formularza publicznego należy zdefiniować następujące właściwości:

• Karta Ogólne:
  • Język formularza: określa język komunikatów o błędach walidacji wykonywanej po stronie serwera oraz wersję językową etykiet pól wyświetlanych w tych komunikatach.

  • Dokument biznesowy: w tabeli powiązanej z podaną definicją będą zapisywane dane z formularza publicznego, a w kategorii załączników — przesłane pliki.

    Dane z kontrolek formularza zostaną zapisane w polach modelu danych pod warunkiem, że w znacznikach kontrolek formularza zostanie użyty atrybut name o wartości takiej, jak nazwa odpowiedniego pola danych, np:

    <input type="text" class="form-control" name="FirstName" placeholder="Wprowadź imię" required>
    

  • Adres względny...: ciąg tekstowy używany w adresie URL formularza publicznego; nie może się powtarzać dla danego tenanta.
• Karta Ekran formularza: obejmuje trzy sekcje:
  • HTML: okno edytora Monaco, w którym można wpisać/wkleić kod HTML formularza.
  • CSS: okno edytora Monaco, w którym można wpisać/wkleić arkusz stylów dla formularza.
  • Javascript: okno edytora Monaco, w którym można wpisać/wkleić kod Javascript dla formularza.
• Karty Ekran odpowiedzi serwera - powodzenie/niepowodzenie: pozwalają zdefiniować komunikat o powodzeniu/niepowodzeniu zapisu danych z formularza publicznego; obie karty obejmują sekcje HTML i CSS, które zawierają wstępnie zdefiniowane strony komunikatów.

W definicji formularza obsługiwane są style Bootstrap oraz biblioteki jQuery.js, Moment.js i DateRangePicker.js (https://www.daterangepicker.com/#examples).

• Panel Pomoc: zawiera dodatkowe informacje o nazwach pól modelu danych oraz kategorii załączników. Dodatkowo u dołu znajdują się dwa przykładowe formularze w tym jeden z walidacją pól formularza realizowaną przez Javascript oraz z komponentem dodawania załączników (obsługuje metodę drag&drop i okno wyboru plików).

Google reCAPTCHA v3

Dla formularzy publicznych można włączyć mechanizm Google reCAPTCHA v3, który zweryfikuje, czy dane są wysyłane przez człowieka. Odpowiednie ustawienia znajdują się w TenantsAdmin SPA (Global settings > Google reCAPTCHA v3). Mechanizm reCAPTCHA konfiguruje się dla witryny nAxiom, to jest dla wszystkich tenantów. Wymagane jest zarejestrowanie domeny witryny w usłudze Google reCAPTCHA i wybranie wersji v3. Rejestracja obejmuje domenę i wszystkie domeny podrzędne. Możliwe jest jednorazowe zarejestrowanie wielu domen dla różnych witryn nAxiom.

Wynikiem rejestracji jest przydzielenie klucza publicznego witryny (SiteKey) oraz klucza tajnego (SecretKey). Oba parametry należy podać w TenantsAdmin SPA, gdzie również można włączyć lub wyłączyć ochronę. Dodatkowo należy skonfigurować parametr Acceptable scoring, to jest minimalną wartość oceny zwracaną przez mechanizm reCAPTCHA, dla której weryfikacja będzie uznawana za pomyślną (zwracane wartości należą do zakresu od 0 do 1). W przypadku oceny niższej od podanej wartości, dane z formularza nie zostaną zapisane i nastąpi przekierowanie na stronę komunikatu o błędzie. Dodatkowo zostanie zalogowana informacja o niepowodzeniu weryfikacji.

Włączenie mechanizmu reCAPTCHA spowoduje dodanie do kodu HTML formularza publicznego nagłówka:

<script src="<https://www.google.com/recaptcha/api.js?render=klucz_publiczny_witryny>"></script>

Kiedy użytkownik kliknie przycisk wysłania danych formularza, skrypt wyśle żądanie do API reCAPTCHA w celu uzyskania tokenu. Następnie token zostanie przekazany wraz z danymi formularza do punktu końcowego API nAxiom. Ten punkt przed zapisaniem danych wyśle żądanie weryfikacji, podając w nim przekazany token i klucz tajny. Odpowiedź w formacie JSON wygląda następująco:

{
"success": true|false,      // określa, czy przesłany token reCAPTCHA dla danej witryny był prawidłowy
"score": number             // wynik oceny żądania (0.0 - 1.0)
"action": string            // nazwa akcji dla tego żądania (na potrzeby weryfikacji)
"challenge_ts": timestamp,  // datownik wczytania wyzwania (format ISO yyyy-MM-dd'T'HH:mm:ssZZ)
"hostname": string,         // nazwa hosta witryny, dla której wykonano weryfikację reCAPTCHA
"error-codes": [...]        // opcjonalne kody błędów
}

Ponadto skrypt generuje logo mechanizmu reCAPTCHA w prawym dolnym rogu formularza.

UWAGI

• Bezpłatny limit dla usługi Google reCAPTCHA wynosi 10 tysięcy żądań na miesiąc dla domen obsługiwanych przez parę SiteKey/SecretKey. Po przekroczeniu limitu usługa może stale zwracać wynik weryfikacji równy 0,9.
• Korzystanie z Google reCAPTCHA wymaga otwarcia połączeń do domen:
  • http://www.google.com
  • www.gstatic.com
  • fonts.gstatic.com