CZ : eventFilter, pluginLoad, puiButton, clarifications in other chapters

VitSimon · VitSimon · commit ea12876ae60c · 2025-09-13T18:12:44.000+02:00
diff --git a/cs/eventFilter.md b/cs/eventFilter.md
@@ -0,0 +1,77 @@
+# ▼ Filtrování událostí v pluginech
+
+V pluginech existuje přepínač na (de)aktivaci filtru na příjem událostí podle **aliasName (id)** instance pluginu:
+
+```javascript
+this.eventIdStrict = true;
+```
+
+Volání provádějte v konstruktoru nebo na začátku funkce init() nebo nejpozději před voláním base.init().
+
+Filtrování událostí je dvoustupňové - podle eventIdStrict a jména obslužné funkce. V následujících podkapitolách je popsáno podrobněji.
+
+## Úvodní souhrn
+
+- Funkce **onET_(jméno události)** přijímá všechny události s eventName = (jméno události)
+- Funkce **onET(jméno události)** přijímá všechny události s eventName = (jméno události) a id = plugin.aliasName
+- **Plugin s plugin.aliasName = ''** přijímá všechny události do funkce **onET(jméno události)** nebo **onET_(jméno události)**
+
+## Diagram rozhodovacího procesu
+
+```mermaid
+flowchart LR
+  Event[⚡ Událost - eventName, id] --> Check1
+  Plugin[🧩 Plugin - aliasName] --> Check4
+  Plugin --> Check5
+  Check1{Existuje 👂 onET_:eventName:} -->|TRUE| EndY
+  Check1 -->|FALSE| Check2
+  Check2{eventIdStrict} -->|🔺 TRUE| Check3
+  Check2 -->|🟢 FALSE| Check5
+  Check3{Existuje 👂 onET:eventName:} -->|FALSE| EndN
+  Check3 -->|TRUE| Check4
+  Check4{Událost.id = Plugin.aliasName} -->|TRUE| EndY
+  Check4 -->|FALSE| Check5
+  Check5{Událost.id nebo Plugin.aliasName = ''} -->|TRUE| EndY
+  Check5 -->|FALSE| EndN
+  EndY[✔️ Předej do pluginu]
+  EndN[⛔ Nepředávej]
+```
+
+## 0. Význam hodnot aliasName (''/...)
+
+| Hodnota aliasName | Popis |
+|---|---|
+| '' | (Inicializace **třída:** v seznamu pluginů). Pokud je nastavena tato hodnota, plugin je schopný přijímat většinu zpráv systému (jsou běžně posílány s nevyplněným id). |
+| xxx | V případě jakkoli jinak vyplněné hodnoty o dalším zpracování rozhoduje vlastnost **eventIdStrict**. |
+
+## 1. Význam hodnot eventIdStrict (🟢/🔺)
+
+Obvyklá hodnota bývá **false**, aby plugin přijímal všechny události nezávisle na jejich id.
+
+| Hodnota eventIdStrict | Popis |
+|---|---|
+| false | 🟢 Není filtrováno id příchozích událostí. Příchozí události se filtrují pouze obsluhami na pluginu, které se jmenují **onET_(jméno události)** nebo **onET(jméno události)** |
+| true | 🔺 Požadována striktní shoda id v událostech. Tedy pokud **aliasName** (**id** pluginu) a **id** v události se shodují, pak je událost předána pluginu. Aby plugin událost zpracoval, musí mít navíc definovanou metodu obsluhy **onET_(jméno události)** nebo **onET(jméno události)** |
+
+Pokud je zde **false** a plugin má **aliasName (id)** prázdné (inicializace **třída:**), pak událost **je předána** ke zpracování do dalšího kroku. V případě **false** také není rozhodující jméno obsluhy **ET vs. ET_**.
+
+## 2. Jméno obslužné funkce (ET/ET_)
+
+| Jméno události | Výsledek |
+|---|---|
+| **neexistuje žádná onET funkce v pluginu** | Událost není pluginu předána ke zpracování. |
+| onET_(jméno události) | (onET podtržítko) Událost je pluginu předána ke zpracování **bez ohledu na shodu id události a pluginu**. ⚠️ **Jméno funkce s podtržítkem je nadřazeno nastavení eventIdStrict.** |
+| onET(jméno události) | (onET) Událost je pluginu předána ke zpracování **pouze když id události a pluginu se shodují**. Nezadané id pluginu je také považováno za shodu. |
+
+## Jak rozhodnout nastavení?
+
+Plugin by neměl poslouchat všechny události, ale budou se zasílat jen některé přímo jemu, proto dostane konkrétní id a eventIdStrict = true.
+
+EventIdStrict na **true** nastavte minimálně v těchto případech:
+
+- Plugin bude (nebo může) běžet ve více než jedné instanci (například 📇 slovník klíčových slov a 🔎 fulltext hledání)
+- Plugin bude součástí procesu (🖼️ [pTRPhasePlugin][pTRPhasePlugin] - vypisování obsahu kapitoly)
+- Plugin bude součástí většího funkčního celku (🔹 [pIndexFile:fulltextList][pIndexFile] - dynamické vytvoření fulltext indexu nápovědy)
+
+[pTRPhasePlugin]: pTRPhasePlugin.md "pTRPhasePlugin"
+[pIndexFile]: :inst:pIndexFile:fulltextList.md "pIndexFile:fulltextList"
diff --git a/cs/files.lst b/cs/files.lst
@@ -18,3 +18,6 @@ implPlug.md|Implementace pluginů
 lists.md|Seznamy zavádění
 pTopicRenderer.md|pTopicRenderer
 pluginConfig.md|Konfigurace pluginů
+pluginLoad.md|Zavádění pluginů
+puiButton.md|puiButton
+eventFilter.md|Filtrování událostí v pluginech
diff --git a/cs/oexplorer.md b/cs/oexplorer.md
@@ -36,7 +36,7 @@ Dále podporuje:
 
 - vývojářské ruční definice vazeb
 - statická analýza (skenování kódu, který je načtený, ale neběží)
-- dynamická analýza (automatizované skenování běhu a zaslaných událostí během provozu)
+- dynamická analýza (automatizované skenování běhu a zaslaných událostí během provozu - ⚡ [DebugEventEvent][DebugEventEvent])
 
 ## Omezení
 
@@ -47,3 +47,4 @@ Dále podporuje:
 [OEGroups]: :_/README.md "Seznam kategorií"
 [OETree]: :_/tree/TREE.md "Strom dědičností"
 [OELoadOrder]: :_/LORDER.md "Pořadí zavádění"
+[DebugEventEvent]: :_evt:DebugEventEvent.md "DebugEventEvent"
diff --git a/cs/pTopicRenderer.md b/cs/pTopicRenderer.md
@@ -37,7 +37,7 @@ Pokud aplikace běží v [debug režimu][debug], plugin průběh své činnosti
 Je doporučeno, aby každá fáze měla definovaný aspoň jeden plugin. Pokud v daném procesu fáze vhodná není, ale nechcete ji odebírat, definujte instanci pluginu 🖼️ [pTREmptyPlugin][pTREmptyPlugin].
 5. Po dokončení zpracování všech kroků (odpovídají za ně potomci 🖼️ [pTRPhasePlugin][pTRPhasePlugin]) odešle událost ⚡ [ChapterShown][ChapterShown], kterou obvykle přijímá plugin 🧩 [pAppmainNext][pAppmainNext], který je hlavním pluginem aplikace a má na tuto událost obsluhu.
 
-## Aplikace
+## Příklady implementací
 
 - Vypisování obsahu kapitoly uživateli
 - Příprava fulltext slovníku v případě, že není v nápovědě k dispozici předgenerovaný slovník ze CI/CD skriptu
diff --git a/cs/pluginConfig.md b/cs/pluginConfig.md
@@ -1,8 +1,8 @@
 # ⚙️ Konfigurace pluginů
 
-Aplikace automaticky při načítání pluginů zajišťuje propis konfigurace do jednotlivých instancí pluginů při jejich zavádění.
+Aplikace automaticky zajišťuje propis konfigurace do jednotlivých instancí pluginů při jejich zavádění.
 
-Při zavádění instance pluginu je automaticky ve stejném datovém souboru z jakého pochází plugin (aplikace nebo souboru nápovědy) hledáno umístění:  
+Ve stejném datovém souboru z jakého je načten plugin (aplikace nebo souboru nápovědy) je hledáno umístění:  
 
 - **zip/plugins-config/[jméno třídy]_[jméno instance].cfg** (v datech aplikace)
 - **plugins-config/[jméno třídy]_[jméno instance].cfg** (ve základních datech nápovědy **Help-.zip** nebo **kořen adresáře bez jazyka**)
@@ -13,7 +13,7 @@ Pokud existuje, načte se a předá se instanci pluginu. Pokud neexistuje, hodno
 
 - ⚠️ Tento formát je velmi přísný, prosím, dodržujte pravidla přesně.
 - Jeden řádek = jedna položka
-- Zalomení řádku uprostřed definice není povoleno
+- Zalomení řádku uprostřed definice není povoleno a to ani u hodnot
 - V případě shody názvů klíče se propisuje vždy poslední definovaná hodnota
 - V případě vícehodnotových výčtů je výčet hodnot uveden na jednom řádku a oddělovačem je obvykle **;**. Zpracování a rozdělení hodnot si zajišťuje každý plugin sám (může mít tedy vlastní oddělovač, avšak oddělovači **|** je doporučeno se vyhnout)
 
diff --git a/cs/pluginLoad.md b/cs/pluginLoad.md
@@ -0,0 +1,46 @@
+# 📑 Zavádění pluginů
+
+Zavést instanci pluginu je v aplikaci možné dvěma způsoby:
+
+1. Definicí v [seznamu pluginů][plugins]. Při spouštění aplikace nebo načítání nápovědy zavedení provede aplikace sama.
+2. Voláním funkce kdekoli v kódu aplikace
+
+## Dynamické zavedení pluginu
+
+```javascript
+const pluginName = 'puiButtonObjectExplorer';
+const pluginId = '-load';
+await loadPlugin(pluginName, loadPluginListBasePath(pluginName));
+await activatePlugin(pluginName, pluginId);
+```
+
+| Definice | Popis |
+|---|---|
+| pluginName | Jméno třídy pluginu |
+| loadPlugin | Zajistí načtení třídy pluginu, pokud zatím načtena nebyla. |
+| loadPluginListBasePath(pluginName) | Funkce, která zajistí sestavení správné cesty k souboru pluginu uvnitř balíku dat. Předpokládá, že se soubor pluginu bude nacházet v **plugins/(pluginName).js** |
+| activatePlugin | Zajistí vytvoření nové instance pluginu **pluginName** s id **pluginId** |
+
+## Odebrání pluginu za běhu
+
+Plugin odeberete následujícím způsobem:
+
+```javascript
+const pluginName = 'puiButtonObjectExplorer';
+const pluginId = '-load';
+await deactivatePlugin(pluginName, pluginId);
+```
+
+⚠️ Tato operace dovolí ze systému odebrat jakýkoli plugin.  
+Pokud odeberete klíčový plugin systému, je možné, že aplikace v rámci dané relace:
+
+- přestane částečně či zcela fungovat (nebude reagovat na důležitou událost ze systému nebo javascriptu)
+- se bude častěji restartovat
+- bude nadměrně překreslovat celé své uživatelské rozhraní
+
+## Akce správy pluginů
+
+Tyto akce správy pluginů provádí buďto základní funkce aplikace nebo plugin 🔌 [pPluginManagement][pPluginManagement], pokud je zaveden (je v základní systémové konfiguraci ve standardním distribučním balíčku). Plugin pPluginManagement poskytuje zapouzdření základních funkcí pro práci s pluginy a zasílání událostí dovnitř systému, pokud dojde ke změně v aktivních pluginech (načtení, inicializace, odebrání, chyba operace načtení/inicializace/odebrání).
+
+[plugins]: plugins.lst.md "Seznam pluginů"
+[pPluginManagement]: :_inst:pPluginManagement:.md "pPluginManagement"
diff --git a/cs/puiButton.md b/cs/puiButton.md
@@ -0,0 +1,54 @@
+# 🖥️ puiButton
+
+## Účel pluginu
+
+Tento plugin je vhodný pro zajištění jednoduchého 🔘 tlačítka s akcí pro uživatelské rozhraní.
+
+## Konfigurace
+
+1. Připravte konfiguraci s hodnotami:
+
+| Název | Popis |
+|---|---|
+| ID | Id nového tlačítka. Musí být jedinečné napříč systémem, aby tlačítko nebylo propojeno s jinou akcí a nebo plugin jinou akci nepřepsal. |
+| CAPTION | Titulek nebo ikonka pro tlačítko. Pokud **ID** tlačítka je definované jako klíč v lokalizaci, data se přepíší hodnotou překladového klíče. |
+| TARGET | Cílový slot pro tlačítko. Obvyklé hodnoty: sidebar (boční panel), header (horní panel nad textem kapitoly). Hodnota může být jakákoli, avšak cílový plugin (páruje se podle ID pluginu) musí být schopen zpracovat událost ⚡ [ButtonSend][ButtonSend] jinak se tlačítko nikde nezobrazí. |
+
+## Implementace
+
+2. Nový plugin vždy bude mít [puiButton][puiButton] jako svou bázovou třídu.
+
+```javascript
+class puiButtonFullScreen extends puiButton {
+  constructor(aliasName, data) {
+    super(aliasName, data);
+
+    this.DEFAULT_KEY_CFG_ID = 'downP-ToggleFS';
+    this.DEFAULT_KEY_CFG_CAPTION = '🔲';
+    this.DEFAULT_KEY_CFG_TARGET = UI_PLUGIN_SIDEBAR;
+  }
+  
+  _buttonAction(evt) {
+    document.fullscreenElement 
+      ? document.exitFullscreen() 
+      : document.documentElement.requestFullscreen();
+  }
+}
+
+Plugins.catalogize(puiButtonFullScreen);
+```
+
+- Řádky **this.DEFAULT_KEY_CFG_** mohou být odebrány, pokud chcete spoléhat pouze na konfiguraci ze souboru. S ohledem na automatickou dokumentaci objektů v pluginu však doporučuji je ponechat.
+
+## Popis funkčnosti
+
+- Funkce **_buttonAction**(evt) představuje handler pro obsluhu kliknutí na tlačítko.
+- **evt** představuje ⚡ [ClickedEvent][ClickedEvent]
+
+## Příklady implementací
+
+- Potomci třídy 🖥️ [puiButton][puiButton]
+
+[ButtonSend]: :_evt:ButtonSend.md "ButtonSend"
+[ClickedEvent]: :_evt:ClickedEvent.md "ClickedEvent"
+[puiButton]: :_plg:puiButton.md "puiButton"
diff --git a/cs/tree.lst b/cs/tree.lst
@@ -8,8 +8,11 @@ Seznamy|Seznamy||lists.md
 🐞 Debug režim|Debug režim||debug.md
 🧩 Prohlížeč objektů|Prohlížeč objektů||oexplorer.md
 🧩 První plugin|První plugin||firstPlugin.md
+ 📑 Zavádění pluginů|Zavádění pluginů||pluginLoad.md
  ⚙️ Konfigurace pluginů|Konfigurace pluginů||pluginConfig.md
+ ▼ Filtrování událostí|Filtrování událostí v pluginech||eventFilter.md
  Implementace pluginů|Implementace pluginů||implPlug.md
+  🖥️ puiButton|puiButton||puiButton.md
   🔌 pConvertSysEventToEvent|pConvertSysEventToEvent||pConvertSysEventToEvent.md
   🖼️ pTRPhasePlugin|pTRPhasePlugin||pTRPhasePlugin.md
   🖼️ pTopicRenderer|pTopicRenderer||pTopicRenderer.md
