CZ : cfgopt, concept, event, handler, jsevent, objDef, resource, uibutton, uiobject, uitab, uitree

Author: VitSimon

cs/cfgopt.md

@@ -0,0 +1,42 @@
+# ⚙️ Konfigurační volba
+
+Konfigurační volba zastupuje ⚙️ [konfiguraci pluginů][cfgPlug] na straně kódu pluginu.
+
+## Definice
+
+```javascript
+class pConfigValuePlugin extends IPlugin {
+  static KEY_CFG_FILENAME = 'FILENAME';
+
+  init() {
+    const T = this.constructor;
+    const TI = this;
+    TI.DEFAULT_KEY_CFG_FILENAME = 'marked.min.js;LICENSE-marked.md';
+    TI.cfgFileName = TI.config[T.KEY_CFG_FILENAME] || TI.DEFAULT_KEY_CFG_FILENAME;
+    super.init();
+  }
+}
+Plugins.catalogize(pConfigValuePlugin);
+```
+
+### Ukázka konfiguračního souboru
+
+Tato definice se napáruje na tuto definici v konfiguračním souboru:
+
+```text
+FILENAME|README.md
+```
+
+[Ukázka na straně prohlížeče objektů][pTRParseMd]
+
+Pokud se v konfiguračním souboru nenajde klíč z konstanty **KEY_CFG_FILENAME**, použije se hodnota **DEFAULT_KEY_CFG_FILENAME**.
+
+### Význam proměnných
+
+- KEY_CFG_FILENAME - jméno konfiguračního klíče na straně konfigurace
+- DEFAULT_KEY_CFG_FILENAME - defaultní hodnota pro konfigurační klíč
+- ⚠️ DEFAULT_**KEY_CFG_FILENAME** a **KEY_CFG_FILENAME** se musí svým názvem objektu shodovat, aby prohlížeč objektů konfigurační volbu správně vyhodnotil a propojil název i výchozí (záložní) hodnotu.
+
+
+[cfgPlug]: pluginConfig.md "Konfigurace pluginů"
+[pTRParseMd]: :_inst:pTRParseMd:-md.md#h-2-1 "pTRParseMd:-md"

cs/concept.md

@@ -0,0 +1,30 @@
+# 🗺️ Základní přehled
+
+Aplikace je postavená na **pluginech (zásuvných modulech) a přenosu událostí (zpráv) mezi nimi**.
+
+V pluginech lze definovat:
+
+- události (zprávy),
+- jejich obsluhy,
+- odesílání událostí,
+- UI prvky,
+- obsluhy javascript událostí,
+- členství v komunikační cestě (skupina příjemců)
+
+Díky tomu jsou přístupy pro UI i programovou logiku jednotné napříč celou aplikací.  
+Systém pluginů i distribuce zpráv je vyvinut od základů, bez použití cizích frameworků.  
+
+**Technické řešení:**
+
+- komprimovaný balíček aplikačních dat (s možností běhu s rozzipovaným obsahem),
+- běh na klientovi, bez nutnosti serveru či backendu,
+- minimum pro nasazení: prohlížeč s podporou **ES2021** + místní disk (Internet není nutný) (doporučeno vypnutí CORS, byť aplikace obsahuje podporu pro upload dat ručně uživatelem)
+
+**Hlavní součásti aplikace:**
+
+- zavaděč (**hvdata/appmain.js + jszip.min.js**),
+- aplikační data (**hvdata/data.zip**), kde je uložena převážná část aplikace (asi 86 % velikosti balíčku)
+  - nízkoúrovňový kód (v **js.lst**),
+  - pluginový kód (v **plugins.lst**).
+- knihovny třetích stran (oddělené, načítané jako samostatné moduly)
+- soubor implementačních dat - samostatný archiv v aplikaci logicky pojmenovaný jako **STO_HELP**

cs/debug.md

@@ -7,5 +7,7 @@
 
 - 🧩 [Prohlížeč objektů][oexplorer]
 - 📜 Logování do DevTools konzole prohlížeče
+- ⚡ zaslané události jsou také zdvojeny do události [DebugEventEvent][DebugEventEvent], která je zpracována prohlížečem objektů s cílem zachytit přenosy událostí mezi celky aplikace při běhu
 
+[DebugEventEvent]: :_evt:DebugEventEvent.md "DebugEventEvent"
 [oexplorer]: oexplorer.md "Prohlížeč objektů"

cs/event.md

@@ -0,0 +1,87 @@
+# ⚡ Událost
+
+Událost definuje událost/zprávu aplikace.  
+Událost je možné definovat s obsluhou nebo pouze definovat (bez obsluhy).
+
+## Definice
+
+1. Definujte objekt dat události nebo určete, který z již definovaných potomků ⚡ [IEvent][IEvent] se vám pro událost hodí:
+
+```javascript
+class ClickHandlerRegister extends IEvent {
+  constructor() {
+    super();
+    this.handlerId = undefined;
+    this.handler = undefined;
+  }
+}
+```
+
+2. Definujte třídu pluginu pro událost:
+
+```javascript
+class pEventPlugin extends IPlugin {
+  static EVT_CLICK_HANDLER_REGISTER = 'ClickHandlerRegister';
+
+  init() {
+    const T = this.constructor;
+    const TI = this;
+
+    // (B)
+
+    super.init();
+  }
+}
+Plugins.catalogize(pEventPlugin);
+```
+
+3. Rozhodněte, zda můžete mít obsluhu přímo v pluginu nebo ji potřebujete mít právě mimo plugin. Podle svého případu si vyberte potřebný postup podle dalších kapitol.
+
+4. Zdroj kódu kapitoly pak vždy vložte do místa komentáře **(B)**.
+
+### ⚡ Událost s obsluhou
+
+```javascript
+    const h_EVT_CLICK_HANDLER_REGISTER = (reply) => {
+      // ...
+      reply.result = 'replyValue';
+    }
+    TI.eventDefinitions.push([T.EVT_CLICK_HANDLER_REGISTER, ClickHandlerRegister, h_EVT_CLICK_HANDLER_REGISTER]);
+```
+
+### 📄⚡ Událost pouze definovaná
+
+```javascript
+    TI.eventDefinitions.push([T.EVT_CLICK_HANDLER_REGISTER, ClickHandlerRegister, null]); // outside event handlers
+```
+
+### Význam prvků
+
+- class ClickHandlerRegister - datový objekt události (je možné použít stejnou třídu u více událostí nebo dědit z kteréhokoli potomka IEvent)
+- ClickHandlerRegister.constructor - obsahuje výchozí hodnoty objektu zprávy. Je žádoucí, aby se hodnoty, pokud je to možné předvyplnily ideálně výchozí hodnotou podle plánovaného typu. Tato data jsou používána v [prohlížeči objektů][oexplorer] jako součást automatické dokumentace systému.
+- const h_EVT_CLICK_HANDLER_REGISTER - obsluha události
+- reply.result - standardní vlastnost události (⚡ [IEvent][IEvent]), která je automaticky aplikační logikou přebírána jako odpověď obsluhy na událost. Může to být jakýkoli objekt.
+- TI.eventDefinitions.push([T.EVT_CLICK_HANDLER_REGISTER, ClickHandlerRegister, null]) - vytvoří předpis definice události (jméno události, objekt dat události a obslužná metoda nebo null pokud má být událost pouze definována). O zpracování definic se stará předek 🔌 [IPlugin][IPlugin].
+- super.init(); - provádí standardní inicializace vazeb. Musí být posledním příkazem, aby se řádně inicializovalo vše definované.
+
+## Zasílání události
+
+V obslužném kódu pak můžete události vyvolávat takto:
+
+```javascript
+      const eventName = EventNames.MyNewEvent; //nebo: 'MyNewEvent'
+
+      sendEvent(eventName, (r) => {
+        r.id = aliasName;
+        r.result = loadedCount;
+        //vyplnění dalších potřebných dat
+      });
+```
+
+V souboru **appmainBaseLogic.js** naleznete příklady funkcí, které podobná volání zapouzdřují.  
+⚠️ Je doporučeno si pro svůj plugin založit podobnou sadu funkcí v odděleném souboru (který vložíte do [seznamu skriptů][jsList]). Volání metody **sendEvent** se neindexuje pro [prohlížeč objektů][oexplorer], ale tyto funkce budou indexovány.
+
+[IEvent]: :_evt:IEvent.md "IEvent"
+[oexplorer]: oexplorer.md "Prohlížeč objektů"
+[IPlugin]: :_plg:IPlugin.md "IPlugin"
+[jsList]: js.lst.md "Seznam skriptů"

cs/files.lst

@@ -25,3 +25,15 @@ eventFilterD.md|Detaily o filtrování událostí v pluginech
 appendix.md|Přílohy
 puiButtonTab.md|puiButtonTab
 puiButtonTabTree.md|puiButtonTabTree
+objDef.md|Definice objektů v pluginech
+debug.md|Režim ladění
+cfgopt.md|Konfigurační volba
+event.md|Událost
+concept.md|Základní přehled
+handler.md|Obsluha události
+jsevent.md|Zpracování javascript události
+uiobject.md|UI prvky
+uibutton.md|Tlačítko
+uitab.md|Karta
+uitree.md|Strom
+resource.md|Zdroj/Balíček

cs/firstPlugin.md

@@ -37,6 +37,9 @@ class pMinPlugin extends IPlugin {
   }
 
   init() {
+    //const T = this.constructor;
+    //const TI = this;
+    
     super.init();
   }
 
@@ -49,7 +52,10 @@ Plugins.catalogize(pMinPlugin);
 
 ```
 
-Volání **Plugins.catalogize(pMinPlugin);** je povinné, protože provede zavedení pluginu do katalogu načtených pluginů. Následně na základě znalosti jména pluginu je možné si vyžádat jeho instance. Na základě dat v **plugins.lst** toto udělá aplikace sama.
+- Volání **Plugins.catalogize(pMinPlugin);** je povinné, protože provede zavedení pluginu do katalogu načtených pluginů. Následně na základě znalosti jména pluginu je možné si vyžádat jeho instance. Na základě dat v **plugins.lst** toto udělá aplikace sama.
+- Volání **super.** by mělo být první u konstruktoru a u init a deinit poslední. Zajišťují aplikaci obecné spoelčné logiky.
+- const T a TI jsou zkratky pro přístup k this a ke třídě. Je to napříč systémem doporučená koncepce psaní.
+- V případě, že máte ve funkci pouze volání super. , můžete funkci odebrat zcela. Zde v ukázce je vše uvedeno pro rychlý obecný přehled.
 
 ## Základní pluginy
 

cs/handler.md

@@ -0,0 +1,33 @@
+# 👂 Obsluha události
+
+Obsluha definuje reakci systému na konkrétní událost.
+
+Pokud jste ⚡ [událost definovali s obsluhou][eventWH], tento postup pro vás již nemá v rámci jednoho pluginu smysl.
+
+## Definice
+
+1. Uvnitř jiného pluginu definujte funkci:
+
+```javascript
+  onET_ClickHandlerRegister(evt) {
+  }
+```
+
+- evt bude obsahovat instanci třídy **ClickHandlerRegister** s daty události.
+
+## Význam jména funkce
+
+- onET_ClickHandlerRegister (podtržítko) - příjímá události **ClickHandlerRegister** pro jakékoli id pluginu a to i když bude definováno 🔺 [filtrování][filter].
+- onETClickHandlerRegister - příjímá události **ClickHandlerRegister** s [id][IEvent-ID], které se shoduje s **plugin.aliasName**.
+
+### Další informace
+
+- Struktura události ⚡ [IEvent][IEvent]
+- 🔺 [Filtrování][filter] událostí na straně pluginu
+- Podrobnější popis k 🔺 [filtrování událostí][filter2]
+
+[IEvent]: :_evt:IEvent.md "IEvent"
+[IEvent-ID]: :_evt:IEvent.md#h-4-4 "IEvent id"
+[eventWH]: event.md#h-3-0 "Událost s obsluhou"
+[filter]: eventFilter.md "Filtrování"
+[filter2]: eventFilterD.md "Podrobnosti k filtrování"

cs/jsevent.md

@@ -0,0 +1,61 @@
+# ⭐ Zpracování javascript události
+
+Zpracování javascript události slouží k napojení pluginu na systémovou javascript událost.
+
+## Definice
+
+### pConvertSysEventToEvent a konfigurace
+
+Pokud je to možné, upřednostněte instanci pluginu 🔌 [pConvertSysEventToEvent][pConvertSysEventToEvent], kterou upravíte konfigurací. Výsledkem tohoto postupu je přeložená událost systému, kterou si může zachytit kterýkoli plugin prostřednictvím 👂 [obsluhy události][handler].
+
+### Definice uvnitř vlastního pluginu
+
+```javascript
+class pSysEventHandling extends IPlugin {
+  constructor(aliasName, data) {
+    super(aliasName, data);
+  }
+
+  init() {
+    const T = this.constructor;
+    const TI = this;
+
+    TI.SEVT_POPSTATE = new SystemEventHandler('', undefined, window, 'popstate', this._handlePopstate);
+    TI.SEVT_POPSTATE.init();
+
+    super.init();
+  }
+
+  _handlePopstate(e) {
+  }
+}
+Plugins.catalogize(pSysEventHandling);
+```
+
+### Význam prvků
+
+- TI.SEVT_POPSTATE - obsahuje instanci 🔌 [SystemEventHandler][SystemEventHandler], pluginu, který zajišťuje párování na javascript systémovou událost. Zde je ukázka párování na objekt **window**, událost **popstate**. 
+- _handlePopstate - obsluha při zachycení události **popstate**
+- e - objekt javascript systémové události
+
+#### Parametry konstruktoru SystemEventHandler
+
+| Parametr | Popis |
+|---|---|
+| aliasName | id pluginu (může zůstat '') |
+| data | objekt s konfiguračními daty (může zůstat undefined) |
+| target | cílový systémový objekt na který se má plugin napojit |
+| eventName | jméno javascript systémové události |
+| handler | handler pro událost na straně aplikace |
+
+Dokumentace konfigurace pluginu 🔌 [pConvertSysEventToEvent][pConvertSysEventToEvent] je platná i zde.
+
+### Další informace
+
+Pro více informací k javascript systémovým událostem si projděte dokumentaci javascript standardu **ES2021** (**ECMA script**).  
+Úvod na [geeksforgeeks][geeksforgeeks1] Vám může pomoci získat základní přehled.
+
+[pConvertSysEventToEvent]: pConvertSysEventToEvent.md "pConvertSysEventToEvent"
+[handler]: handler.md "Obsluha události"
+[SystemEventHandler]: :_plg:SystemEventHandler.md "SystemEventHandler"
+[geeksforgeeks1]: https://www.geeksforgeeks.org/javascript/javascript-events/ "JavaScript Events"

cs/objDef.md

@@ -0,0 +1,8 @@
+# 🧾 Definice objektů
+
+Pro složitější práci pluginů je někdy nutné definovat podpůrné objekty. Některé pluginy sice zapouzdřují běžné prvky aplikace (např. UI komponenty nebo obsluha javascriptových událostí), ale nemusí to pokrývat všechny scénáře. 
+
+Tato kapitola proto popisuje [dostupné typy objektů][OEGroups] a způsob jejich definice tak, aby je bylo možné automaticky indexovat v [prohlížeči objektů][oexplorer].
+
+[oexplorer]: oexplorer.md "Prohlížeč objektů"
+[OEGroups]: :_/README.md#h-2-1 "Seznam objektů"

cs/oexplorer.md

@@ -42,6 +42,7 @@ Dále podporuje:
 
 1. Plugin je dostupný pouze v **DEBUG** režimu z důvodu ochrany produkčních prostředí.
 2. ⚠️ Pro úplný seznam objektů je nutné, aby byla daná funkcionalita v rámci relace alespoň jednou provedena.
+3. Indexovány jsou pouze pojmenované funkce a objekty, které plugin vystavuje přes **this**.
 
 [PlgsList]: plugins.lst.md "Seznam pluginů"
 [OEGroups]: :_/README.md "Seznam kategorií"