Návrhář skriptů

1. Základní informace

• Skript je programový kód, který se spouští na straně serveru.

• Skript se může spouštět:
  • v serverových událostech editačních formulářů,
    • OnBeforeOpen – provádí se před otevřením editačního formuláře po kliknutí na tlačítko „Uložit a nový“,
    • OnAfterOpen – provádí se po otevření editačního formuláře,
    • OnBeforeSave – provádí se před uložením záznamu do databáze,
    • OnAfterSave – provádí se po uložení záznamu do databáze,
    • OnBeforeDelete – provádí se před smazáním záznamu z databáze,
    • OnAfterDelete – provádí se po smazání záznamu z databáze,
  • po stisknutí tlačítka v editačním formuláři,
  • po stisknutí tlačítka na nahlížecí stránce,
  • při pokusu o vytvoření nového záznamu z ovládacích prvků „TimeTable“ a „Planner“.

• Odkaz na skript je vždy součástí dialogu nastavení ovládacího prvku.
  • Nejčastěji jde o ovládací prvek „ActionButtons“ (serverové události editačního formuláře) nebo „Button“ (tlačítka v editačních formulářích a na nahlížecích stránkách).
  • Odkaz je označen jako „Upravit skript (počet řádek skriptu)“ a otevírá grafický návrhář skriptů.

• Skript se skládá z číslovaných řádků, které jsou vyhodnocovány sekvenčně shora dolů.

• Každý řádek skriptu obsahuje jednu instrukci určující provedení konkrétního příkazu.

• NET Genium vyhodnocuje skript řádek po řádce. Obecné programové bloky nepodporuje; příkaz „Cyklus“ však používá blok ohraničený příkazem „Další…“.

1.1. Základní skriptové příkazy

• Deklarace proměnné
  • Definuje datový typ skriptové proměnné.
  • Pokud již proměnná existuje nebo obsahuje hodnotu, dojde ke změně jejího datového typu a nastavení hodnoty na databázovou hodnotu „null“.

• Načtení hodnoty z databázového dotazu
  • Načte hodnotu z databázového dotazu a uloží ji do proměnné nebo do databázového ovládacího prvku.
  • Pokud již proměnná existuje, její datový typ i hodnota jsou přepsány.

• Uložení proměnné zpět do databáze
  • Uloží hodnoty proměnné zpět do databáze na místo, odkud byly načteny.
  • Proměnná nesmí změnit počet svých hodnot (např. seskupením pomocí „GROUP(#A#)“).

• Načtení více hodnot z databázového dotazu
  • Načte více sloupců z databázového dotazu a uloží je do proměnných nebo ovládacích prvků.

• Cyklus
  • Provede opakování bloku skriptu ohraničeného příkazem „Další…“ pro každý prvek řídící proměnné.
  • Pokud proměnná neobsahuje žádné prvky, cyklus se neprovede.
  • Během cyklu se proměnné chovají jako jednoprvkové.
  • Hodnoty „null“ jsou v cyklu automaticky přeskočeny.
  • Jako řídící proměnná se doporučuje primární klíč „id“.

• Přiřazení hodnot
  • Přiřazuje jednu hodnotu nebo matematický výraz do proměnné nebo ovládacího prvku.
  • U polí hodnot se operace provádí nad všemi prvky.

• Porovnání hodnot
  • Porovnává hodnoty proměnných nebo hodnoty zadané uživatelem.
  • Podmínky testující (ne)vyplněnost hodnoty musí u textových hodnot počítat s oběma podobami prázdné hodnoty – s prázdným řetězcem i s databázovou hodnotou „null“ (složená podmínka: hodnota rovná se „“ nebo hodnota není definováno). Detailní popis testu na (ne)vyplněnou hodnotu je uveden v samostatné příručce Práce s proměnnými ve skriptu.

• Další příkazy
  • Skok na řádek
  • Vyvolání přerušení
  • Odeslání e-mailu
  • Smazání záznamů z databáze podle dotazu
  • Přesměrování uživatele do editačního formuláře (dostupné pouze v OnBeforeOpen, OnAfterSave, OnAfterDelete)
  • Vytvoření nových záznamů v databázi
  • Uložení jedné nebo více hodnot do databáze
  • Komentář (včetně volání externích funkcí)

1.2. Charakter skriptovacího jazyka

• Skript NET Genium je deklarativní, řádkově vyhodnocovaný jazyk.
• Podporuje deklarativní cyklus a řízené podmíněné větvení pomocí podmíněných variant příkazů a příkazu „Skok na řádek“.
• Skok smí vést pouze na následující řádek nebo na konec skriptu; zpětné skoky nejsou povoleny. Logiku, kterou nelze vyjádřit dostupnými příkazy, je nutné realizovat pomocí externích funkcí v jazyce C#.

1.3. Spouštění skriptu mimo webové rozhraní

• Skript přiřazený tlačítku na nahlížecí stránce lze spustit i externě pomocí programu „RunScript.exe“.
• Program je umístěn v adresáři „NETGenium\bin“ na serveru.
• Program „RunScript.exe“ není dostupný v cloudové variantě NET Genium Online — k adresářům cloudového serveru nemá zákazník přístup.

1.4. Chyby a přerušení skriptu

• Během provádění skriptu může dojít k chybě nebo k přerušení.
• Ve všech případech dojde k ukončení skriptu, návratu do původního kontextu a zobrazení chybového hlášení uživateli.
• U skriptů „OnBeforeSave“ a „OnBeforeDelete“ přerušení znamená zamezení uložení nebo smazání záznamu.
• V cloudové variantě NET Genium Online je délka běhu skriptu omezena na 10 vteřin. Po překročení limitu se skript ukončí chybou „Časový limit vypršel! Maximální délka trvání skriptu je 10 vteřin.“

1.5. Vymezení skriptovacího jazyka

• Skriptovací jazyk NET Genium je uzavřený a omezený jazyk určený výhradně k řízení aplikační logiky na straně serveru. Skript může používat pouze výše uvedené typy proměnných, příkazy, operátory, serverové funkce a externí funkce. Jakékoliv jiné konstrukce, funkce, operátory, datové typy, návratové hodnoty, programové bloky nebo jazykové prvky nejsou ve skriptu podporovány a nelze je použít. Pokud požadovanou funkcionalitu není možné realizovat kombinací dostupných skriptových příkazů, proměnných a serverových funkcí, musí být implementována formou externí funkce napsané v jazyce C#.

2. Dialog návrháře skriptů

2.1. Rozbalovací seznam „Zadejte příkaz…“

• Rozbalovací seznam s výběrem typu příkazu, který bude vložen do skriptu na označené místo.
  • 1. Deklarovat proměnnou
  • 2. Přiřadit hodnotu z dotazu
  • 3. Uložit proměnnou zpět do databáze
  • 4. Přiřadit více hodnot z dotazu
  • 5. Cyklus
  • 6. Přiřadit hodnotu
  • 7. Jestliže (výraz) přiřadit hodnotu
  • 8. Jestliže (složený výraz) přiřadit hodnotu
  • 9. Přejít na řádek
  • 10. Jestliže (výraz) přejít na řádek
  • 11. Jestliže (složený výraz) přejít na řádek
  • 12. Vyvolat výjimku (přerušení)
  • 13. Jestliže (výraz) vyvolat výjimku
  • 14. Jestliže (složený výraz) vyvolat výjimku
  • 15. Odeslat e-mail
  • 16. Jestliže (výraz) odeslat e-mail
  • 17. Jestliže (složený výraz) odeslat e-mail
  • 18. Smazat záznam
  • 19. Jestliže (výraz) smazat záznam
  • 20. Jestliže (složený výraz) smazat záznam
  • 21. Nový záznam
  • 22. Jestliže (výraz) nový záznam
  • 23. Jestliže (složený výraz) nový záznam
  • 24. Uložit hodnotu do databáze
  • 25. Jestliže (výraz) uložit hodnotu …
  • 26. Jestliže (složený výraz) uložit hodnotu …
  • 27. Uložit více hodnot do databáze
  • 28. Jestliže (výraz) uložit více …
  • 29. Jestliže (složený výraz) uložit více …
  • 30. Komentář

2.2. Rozbalovací seznam „Proměnné“

• Rozbalovací seznam s výběrem rozsahu proměnných, které budou k dispozici ve skriptu pro ukládání hodnot. Tyto proměnné je možné používat na jednotlivých řádcích skriptu.
• Detailní popis proměnných je uveden v samostatné příručce Proměnné.

2.3. Rozbalovací seznam „Funkce“

• Rozbalovací seznam s výběrem serverových funkcí, které je možné volat na jednotlivých řádcích skriptu.
• Detailní popis serverových funkcí je uveden v samostatné příručce Serverové funkce.

2.4. Rozbalovací seznam „Hodnoty“

• Rozbalovací seznam s výběrem identifikátorů databázových ovládacích prvků, které je možné používat na jednotlivých řádcích skriptu.

2.5. Odkaz „Slovník...“

• Slovník zobrazuje seznam komentářů a přerušení použitých napříč všemi skripty v celé aplikaci, které se vztahují k následujícím typům příkazů:
  • Parametr „message“ serverové funkce „SCHEDULEBACK“ v komentáři skriptu
  • Parametr „message“ serverové funkce „TEFUIG“ v komentáři skriptu
  • Parametr „message“ serverové funkce „TESUIG“ v komentáři skriptu
  • Parametr „message“ serverové funkce „WRITEMESSAGE“ v komentáři skriptu
  • Přerušení skriptu
• Vyhledávání ve slovníku slouží k navržení správného tvaru uživatelských hlášek a k udržení konzistence názvosloví v celé aplikaci.

2.6. Odkaz „Sledování změn...“

• Sledování změn zobrazuje detailní report se všemi provedenými změnami skriptu jednotlivými uživateli.

2.7. Odkaz „Statistika…“

• Statistika zobrazuje agregovanou informaci o využívání ovládacího prvku spojeného s tímto skriptem napříč celou aplikací.
• Pomocí odkazu „Statistika“ se zobrazí detailní report všech míst, kde je ovládací prvek použitý nebo referencovaný, včetně možnosti otevření nastavení takového místa či ovládacího prvku.

2.8. Odkaz „Logování…“

• Pomocí odkazu „Logování“ se zobrazí detailní report se záznamy o spuštění skriptu. Report obsahuje informace o:
  • datu a času spuštění skriptu,
  • uživateli, který skript spustil,
  • době zpracování skriptu,
  • datu a času zahájení zpracování a
  • datu a času dokončení zpracování.

• Pro správné fungování logování je nutné mít v nastavení NET Genia na záložce „Ostatní“ aktivováno logování buď „Do databáze“, nebo „Do databáze a na disk“. Detailní popis je uveden v samostatné příručce Nastavení NET Genia.
• Minimální zobrazovaný čas zpracování skriptu je ve výchozím nastavení stanoven na 0 milisekund, zobrazují se tedy všechny záznamy spuštění skriptů včetně těch, jejichž zpracování trvalo 0 milisekund. Tento minimální čas je možné zvýšit nebo snížit změnou parametru „mintime“ v URL reportu.
• Počet záznamů je ve výchozím nastavení omezen na 100 záznamů. Tento počet je možné ručně zvýšit nebo snížit změnou parametru „maxrows“ v URL reportu.

2.9. Tlačítko „Spustit skript“

• Tlačítko „Spustit skript“ slouží ke spuštění skriptu v testovacím režimu.
• Spuštění skriptu simuluje průběh zpracování skriptu, neukládá však žádné hodnoty do databáze, ani nemaže žádné záznamy z databáze.
• Externí funkce volané ze skriptu v testovacím režimu se nevykonávají – do externí funkce je předána hodnota „true“ v parametru „test“:

using System;

namespace NETGenium
{
  public class ExternalFunctions
  {
    public static string ngef(string id, string[] args, bool test, DbCommand cmd, DbConnection conn)
    {
      if (test) return "";

      switch (id)
      {
        // case "MyFirstFunction": return MyFirstFunction();
        default: return conn == null ? "" : conn.ExternalFunctionNotFound(id, cmd);
      }
    }
  }
}

2.10. Tlačítko „Uložit“

• Uložení změn ve skriptu.

2.11. Tlačítko „Uložit a pokračovat v editaci“

• Uložení změn ve skriptu a ponechání skriptu otevřeného pro další úpravy.