ShowMessage

Zastosowanie

Funkcja ShowMessage wyświetla użytkownikowi komunikat w oknie na formularzu sprawy albo na liście spraw „Do wykonania”, gdy reguła ręczna jest uruchamiana z kafelka sprawy. Używasz jej, żeby poinformować o błędzie walidacji, ostrzec przed niekompletnymi danymi, potwierdzić wykonanie operacji albo przekazać informację.

Komunikat o błędzie (typ 1) blokuje zapis sprawy i przejście na kolejny etap. Pozostałe instrukcje reguły wykonują się dalej.

Efekt działania

Typy komunikatów

Typ	Rodzaj	Kolor	Kiedy używać
1	Błąd	czerwony	błędy, nieudana walidacja
2	Informacja	niebieski	informacje dla użytkownika
3	Sukces	zielony	potwierdzenie wykonania operacji
4	Ostrzeżenie	żółty	ostrzeżenia, np. o brakujących danych

Kiedy użytkownik zobaczy komunikat

To, czy komunikat się pokaże, zależy od rodzaju reguły i od akcji użytkownika.

Rodzaj reguły	Błąd (typ 1)	Informacja, sukces, ostrzeżenie (typ 2, 3, 4)
Reguła ręczna (przycisk na formularzu albo na kafelku sprawy na liście „Do wykonania”)	zawsze po kliknięciu przycisku	zawsze po kliknięciu przycisku
Reguła automatyczna	po kliknięciu „Zapisz”, „Usuń”, „Zamknij”, „Prześlij dalej” albo przycisku reguły	jak błąd, a dodatkowo przy otwarciu sprawy
Reguła tabeli	po kliknięciu „Zapisz”, „Usuń”, „Zamknij”, „Prześlij dalej” albo przycisku reguły	tak samo jak błąd
Reguła okresowa	nie wyświetla się	nie wyświetla się

Komunikaty nie wyświetlają się podczas wpisywania wartości w polach formularza.

Pomoc w edytorze reguł oznacza użycie funkcji w regułach automatycznych jako niezalecane, a w regułach okresowych jako niedozwolone, bo nie daje efektu. Komunikaty dla użytkownika wyświetlaj przede wszystkim w regułach ręcznych.

Komunikat o błędzie blokuje zapis sprawy

Gdy reguła wyświetli komunikat typu 1:

• nie wykonują się działania związane ze zmianą etapu,
• sprawa nie zostaje zapisana,
• użytkownik zostaje na formularzu sprawy i nie wraca na listę spraw.

Kolejność komunikatów

Jeżeli reguła wyświetla kilka komunikatów, okno grupuje je według typu, w tej kolejności:

1. błąd (typ 1),
2. ostrzeżenie (typ 4),
3. informacja (typ 2),
4. sukces (typ 3).

W obrębie grupy komunikaty występują w kolejności wywołania w regule. Na zrzucie poniżej reguła wywołała najpierw „Komunikat typu info 2”, potem „Komunikat typu info 1”, i w tej samej kolejności pokazuje je okno.

Okno komunikatu

• Rozmiar okna można zmienić. Przeciągnij prawy dolny róg okna, żeby je powiększyć albo zmniejszyć. Okna nie da się zmniejszyć poniżej 300 × 160 pikseli, dzięki czemu treść komunikatu i przyciski pozostają widoczne.
• Długie komunikaty mieszczą się w oknie. Tekst zawija się także wtedy, gdy zawiera długi ciąg znaków bez spacji, np. adres albo identyfikator. Okno nie wychodzi poza szerokość ekranu.
• Reguła z wymaganym komentarzem. Komunikat korzysta z tego samego, spójnego okna dialogowego co w pozostałych regułach.

Składnia

ShowMessage(type, message);

Argumenty

Argument	Typ	Wymagany	Opis
type	liczba	Tak	Typ komunikatu: 1 błąd, 2 informacja, 3 sukces, 4 ostrzeżenie (zobacz Typy komunikatów).
message	tekst	Tak	Treść komunikatu.

Zwracana wartość

Funkcja zwraca treść komunikatu (tekst).

Po każdym wywołaniu z typem 1–4 reguła ma też zmienną z liczbą wszystkich komunikatów danego typu dodanych w tym wykonaniu reguły: RuleErrorsCount, RuleInfosCount, RuleSuccessesCount albo RuleWarningsCount.

Przykłady

Przykład 1: komunikat o błędzie

ShowMessage(1, "Uzupełnij numer faktury przed przekazaniem sprawy.");

Użytkownik zobaczy czerwony komunikat. Sprawa nie zostanie zapisana ani przekazana na kolejny etap.

Przykład 2: kilka komunikatów jednocześnie

ShowMessage(2, "Decyzję otrzymasz w ciągu 5 dni roboczych.");
ShowMessage(4, "Nie wszystkie załączniki zostały podpisane.");

Okno pokaże najpierw ostrzeżenie, a pod nim informację, niezależnie od kolejności wywołań.

Przykład 3: walidacja i wysłanie dokumentu do podpisu w Trust Center

Reguła sprawdza formularz, tworzy plik PDF i wysyła go do podpisu. Na każdym etapie informuje użytkownika o wyniku.

if (IsFormValid() == false)
{
   ShowMessage(1, "Brak danych na formularzu");
}
else
{
   if (ConvertFileToPDF("DOCX", "PDF") == false)
   {
      ShowMessage(1, "Nie udało się utworzyć pliku PDF");
   }
   else
   {
      if (GetUserData(CurrentUser(), "mobile") == "")
      {
         ShowMessage(1, "W ustawieniach użytkownika brakuje numeru telefonu komórkowego, który jest wymagany");
      }
      else
      {
         sec.RequireSMSCodeToOpenDocument = "true";
         sec.RequireEmailCodeToOpenDocument = "false";
         sec.AllowSimpleSignature = "false";
         sec.AllowSMSSignature = "true";
         sec.AllowHandwrittenSignature = "false";
         sec.AllowHandwrittenSignatureWithSMS = "false";
         sec.AllowQualifiedSignature = "false";
         sec.AllowToAddNewSigners = "true";
         sec.Language = "pl-PL";
         map.LastName = "LastName";
         result = TrustCenterSendToSign("PDF", "", "Protokół odbioru prac", CurrentUser(), "Osoby podpisujące", map, sec);
         if (result == "")
         {
            ShowMessage(3, "Dokument przesłany do AMODIT Trust Center.");
            ShowMessage(3, "Osoby podpisujące otrzymają e-mail z zaproszeniem do podpisania dokumentu.");
         }
         else
         {
            ShowMessage(1, "Błąd przy przesyłaniu dokumentu do Trust Center: " + result);
         }
      }
   }
}

Przy błędzie użytkownik zobaczy jego przyczynę, a sprawa zostanie na bieżącym etapie. Po udanym wysłaniu zobaczy dwa zielone potwierdzenia.

Dobre praktyki

• Pisz krótkie komunikaty, z których wynika, co użytkownik ma zrobić.
• Do komunikatów dla użytkownika używaj reguł ręcznych. W regułach automatycznych funkcja działa, ale jej użycie nie jest zalecane.
• Do zatrzymania przekazania sprawy używaj typu 1. Do informacji, które nie blokują pracy, używaj typów 2, 3 i 4.
• Nie wyświetlaj wielu komunikatów naraz, bo trudniej je przeczytać.

Typowe błędy

• Nieobsługiwany typ. Funkcja z typem innym niż 1, 2, 3 albo 4 nie wyświetli komunikatu i nie zgłosi błędu, a licznik komunikatów się nie zmieni. Sprawdź wartość argumentu type.
• Pusta treść. Przy pustym argumencie message okno pokaże pusty komunikat. Przekaż treść komunikatu.
• Komunikat w regule okresowej. Użytkownik go nie zobaczy. Do powiadomienia użytkownika z reguły okresowej użyj na przykład wiadomości e-mail.

Powiązane funkcje

• FieldIsCorrect
• FieldIsIncorrect
• SetFieldAlias
• SetFieldInfo