Skip to content

Commit 10ac625

Browse files
VitSimonVitSimon
committed
EN,CZ : pExtension documented, indexed, interconneced to firstPlugin list and pExport
1 parent ce813a8 commit 10ac625

File tree

10 files changed

+259
-1
lines changed

10 files changed

+259
-1
lines changed

‎cs/files.lst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,4 @@ milestones.md|Milníky
4646
puiButtonSelect.md|puiButtonSelect
4747
custPackage.md|Vlastní balíček
4848
pExport.md|pExport
49+
pExtension.md|pExtension

‎cs/firstPlugin.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Plugins.catalogize(pMinPlugin);
6464
| 🔌 [IPlugin][IPlugin] | Základní plugin pro všechny pluginy v systému. Poskytuje základní funkce pro obecný plugin. Je určen pro pluginy služeb nebo posluchačů událostí, které samy nebudou zajišťovat žádný prvek uživatelského rozhraní. |
6565
| 🔌 [pConvertSysEventToEvent][pConvertSysEventToEvent] | Plugin převádí definovanou javascript událost na událost aplikace, která může být zachycena jiným pluginem. |
6666
| 🔌 [pServicePlugin][pServicePlugin] | Plugin pro rozšiřující služby. Základem jsou obsluhy napojené na události pluginu 🔌 [pPluginManagement][pPluginManagement]. |
67+
| 🧩 [pExtension][pExtension] | Pluginy s prefixem **pExtension**\* rozšiřují stávající funkcionalitu systému nebo externích knihoven. Nemají pevně danou strukturu. |
6768

6869
### Uživatelské rozhraní
6970

@@ -101,3 +102,4 @@ Plugins.catalogize(pMinPlugin);
101102
[pServicePlugin]: pServicePlugin.md "pServicePlugin"
102103
[pPluginManagement]: :_plg:pPluginManagement.md "pPluginManagement"
103104
[puiButtonExport]: :_plg:puiButtonExport.md "puiButtonExport"
105+
[pExtension]: pExtension.md "pExtension"

‎cs/pExport.md‎

Lines changed: 42 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
Tento plugin definuje základní rozhraní pro export zobrazeného textu kapitoly.
66

7-
Odvozený plugin je obvykle zapouzdřením mezi:
7+
Odvozený plugin je obvykle zapouzdřením mezi:
88

99
- **HelpViewer** (🖥️ [puiButtonExport][puiButtonExport]) a
1010
- převodníkem z **HTML** na požadovaný formát, který je obvykle řešen externím skriptem.
@@ -68,16 +68,57 @@ ID za dvojtečkou (zde NEW) se nabídne ve výběrovém seznamu tlačítka 📥
6868
- Obsluha exportu převezme výsledek převodu a provolá **evt.output.file('name.txt', result);**, pro zápis do ZIP výstupu
6969
- Obsluha exportu nakonec provolá **evt.doneHandler();**. Tímto vydá ZIP soubor uživateli do prohlížeče pro standardní stažení
7070
71+
## Předexportní konverze
72+
73+
V případě některých pluginů (konvence pro pojmenování v systému **pExtension**\* - například: 🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions]) lze předpokládat, že provádějí transformaci do HTML kódu, kterou obecné **HTMLTo**\* (**HTMLToMD**, **HTMLToTeX**) převodníky nerozpoznají.
74+
75+
### Postup
76+
77+
1. V odvozené třídě **pExport**\* v **onETPrepareExport** bude definována proměnná **corrections** (pole), která bude evidovat budoucí změny v DOM struktuře textu kapitoly.
78+
2. Spustíte událost ⚡ [PreExportCorrection][PreExportCorrection] s tím, že **x.temporaryObjects** budou propojeny na **corrections**
79+
3. Proběhnou provolání **onET_PreExportCorrection** na pluginech a konverze výstupů z **pExtension**\* pluginů podle typu exportního formátu, který se připravuje - extension plugin znovu transformuje svou konverzi do zjednodušeného výstupu pro **HTMLTo**\* převodník.
80+
4. V **corrections** budou obsaženy prvky, které konverzí vznikly
81+
5. Provolá se samotná konverze z HTML na požadovaný formát
82+
6. **corrections** projdete v cyklu a smažete všechny obsažené prvky - dočasné úpravy se vyčistí z viditelného vstupu.
83+
84+
### Ukázková implementace
85+
86+
```javascript
87+
//...
88+
async onETPrepareExport(evt) {
89+
//...
90+
promise = promise.then(async() => {
91+
//...
92+
const corrections = [];
93+
sendEvent(EventNames.PreExportCorrection, (x) => {
94+
x.exportType = this.aliasName;
95+
x.parent = evt.parent;
96+
x.temporaryObjects = corrections;
97+
});
98+
99+
const converted = HTMLTONEW(evt.parent, ctx);
100+
corrections.forEach(x => x.remove());
101+
//...
102+
}
103+
}
104+
```
105+
106+
Událost ⚡ [PreExportCorrection][PreExportCorrection] má obsluhu na straně 🧩 [pExtension][pExtension]\*, která zajistí bod 3 [Postupu][H30].
107+
71108
## Příklady implementací
72109
73110
- 🖼️ [pExportHTM][pExportHTM] a další potomci třídy 🖼️ [pExport][pExport], kteří svým jménem začínají na **pExport**.
74111
- Převodníky: [HTMLToTeX][HTMLToTeX], [HTMLToMD][HTMLToMD]
75112
76113
[puiButtonExport]: :_plg:puiButtonExport.md "puiButtonExport"
77114
[pExportHTM]: :_plg:pExportHTM.md "pExportHTM"
115+
[pExtension]: pExtension.md#h-3-0 "pExtension"
116+
[pExtensionMarkedAdmonitions]: :_plg:pExtensionMarkedAdmonitions.md "pExtensionMarkedAdmonitions"
78117
[PrepareExport]: :_evt:PrepareExport.md "PrepareExport"
118+
[PreExportCorrection]: :_evt:PreExportCorrection.md "PreExportCorrection"
79119
[pExport]: :_plg:pExport.md "pExport"
80120
[resource]: resource.md "Zdroj"
81121
[pluginslst]: plugins.lst.md "Seznam pluginů (plugins.lst)"
82122
[HTMLToTeX]: https://github.com/HelpViewer/HTMLToTeX "HTML -> TeX"
83123
[HTMLToMD]: https://github.com/HelpViewer/HTMLToMD "HTML -> md"
124+
[H30]: #h-3-0 "Postup"

‎cs/pExtension.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# 🧩 pExtension
2+
3+
Pluginy s prefixem **pExtension**\* rozšiřují stávající funkcionalitu systému nebo externích knihoven.
4+
5+
## Jmenná konvence
6+
7+
Například:
8+
🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions]
9+
10+
| Část | Význam | Příklad |
11+
| --- | --- | --- |
12+
| **pExtension** | rozšíření | **pExtension** |
13+
| **Marked** | pro co? | **marked.js** - externí knihovna vykreslující markdown |
14+
| **Admonitions**| co zajišťuje? | **zvýrazněné bloky** |
15+
16+
(stejná knihovna = jedna společná předpona a část společné logiky v předkovi **pExtensionMarked**)
17+
18+
## Implementace
19+
20+
1. Nový plugin vždy bude mít 🧩 [pExtension][pExtension] jako svou bázovou třídu.
21+
2. Implementace je velmi různorodá podle prvku, který bude rozšiřovat. Postupujte podle kapitoly 🧩 [první plugin][firstPlugin]
22+
3. Nový plugin musí být zaveden do 📄 [seznamu pluginů][pluginslst] například takto:
23+
24+
```
25+
pExtensionMarked
26+
pExtensionMarkedAdmonitions:
27+
```
28+
29+
v pořadí, které je v seznamu níže než **pExtension**.
30+
31+
## Možné odpovědnosti
32+
33+
Tyto pluginy mohou mít odpovědnosti, které jsou rozebrány v dalších podkapitolách.
34+
35+
### Předexportní konverze
36+
37+
V případě některých pluginů lze předpokládat, že provádějí transformaci do HTML kódu, kterou obecné **HTMLTo**\* (**HTMLToMD**, **HTMLToTeX**) převodníky nerozpoznají.
38+
39+
Na straně pluginů proto musí být definována obsluha **onET_PreExportCorrection** události ⚡ [PreExportCorrection][PreExportCorrection] s tím, že její **x.temporaryObjects** budou propojeny na **corrections** v místě požadavku na export. **Za způsob výstupu do exportu odpovídá tento plugin.** Typ exportu dostává z dat volání. Měl by také zajistit záložní obsluhu pro nový nebo neznáný formát (**\***).
40+
41+
Ukázka obsluhy:
42+
43+
```javascript
44+
onET_PreExportCorrection(e) {
45+
if (!e || !e.parent) return;
46+
47+
const cssClass = this.cfgROOTCSSCLASS;
48+
const willBeUpdated = [...$A(`.${cssClass}`, e.parent)];
49+
const exportFormatting = new Map([
50+
['MD', (id) => `> [!${id}]`],
51+
['TEX', (id) => `<strong>[!${id}]</strong> `],
52+
['*', (id) => ''],
53+
]);
54+
55+
willBeUpdated.forEach(x => {
56+
const typeClass = x.className.split(' ').filter(Boolean).find(c => c.startsWith(cssClass) && c !== cssClass) || '';
57+
if (typeClass) {
58+
const correctionText = (exportFormatting.get(e.exportType) || exportFormatting.get('*'))?.(typeClass.toUpperCase().substring(cssClass.length + 1));
59+
if (correctionText) {
60+
const correction = document.createElement('span');
61+
correction.className = e.CSSClassName;
62+
correction.innerHTML = correctionText;
63+
64+
x.prepend(correction);
65+
e.temporaryObjects.push(correction);
66+
e.manipulatedObjects.push(x);
67+
}
68+
}
69+
});
70+
}
71+
```
72+
73+
(🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions])
74+
75+
## Příklady implementací
76+
77+
- 🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions], 🧩 [pExtensionMarked][pExtensionMarked] a další potomci třídy 🧩 [pExtension][pExtension], kteří svým jménem začínají na **pExtension**.
78+
79+
[pExtension]: :_plg:pExtension.md "pExtension"
80+
[pExtensionMarkedAdmonitions]: :_plg:pExtensionMarkedAdmonitions.md "pExtensionMarkedAdmonitions"
81+
[pExtensionMarked]: :_plg:pExtensionMarked.md "pExtensionMarked"
82+
[firstPlugin]: firstPlugin.md "První plugin"
83+
[pluginslst]: plugins.lst.md "Seznam pluginů (plugins.lst)"
84+
[PreExportCorrection]: :_evt:PreExportCorrection.md "PreExportCorrection"

‎cs/tree.lst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Implementace pluginů|Implementace pluginů||implPlug.md
2323
🖼️ pTRPhasePlugin|pTRPhasePlugin||pTRPhasePlugin.md
2424
🖼️ pTopicRenderer|pTopicRenderer||pTopicRenderer.md
2525
🖼️ pExport|pExport||pExport.md
26+
🧩 pExtension|pExtension||pExtension.md
2627
🔌 pServicePlugin|pServicePlugin||pServicePlugin.md
2728
Definice objektů|Definice objektů||objDef.md
2829
⚙️ Konfigurační volba|Konfigurační volba||cfgopt.md

‎en/files.lst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,3 +46,4 @@ milestones.md|Milestones
4646
puiButtonSelect.md|puiButtonSelect
4747
custPackage.md|Custom package
4848
pExport.md|pExport
49+
pExtension.md|pExtension

‎en/firstPlugin.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,7 @@ Plugins.catalogize(pMinPlugin);
6464
| 🔌 [IPlugin][IPlugin] | Basic plugin for all plugins in the system. Provides basic functions for a general plugin. It is intended for service plugins or event listeners that do not provide any user interface elements themselves. |
6565
| 🔌 [pConvertSysEventToEvent][pConvertSysEventToEvent] | The plugin converts a defined JavaScript event into an application event that can be captured by another plugin. |
6666
| 🔌 [pServicePlugin][pServicePlugin] | Plugin for extended services. It is based on handlers connected to plugin events 🔌 [pPluginManagement][pPluginManagement]. |
67+
| 🧩 [pExtension][pExtension] | Plugins with the prefix **pExtension**\* extend the existing functionality of the system or external libraries. They do not have a fixed structure. |
6768

6869
### User interface
6970

@@ -101,3 +102,4 @@ Plugins.catalogize(pMinPlugin);
101102
[pServicePlugin]: pServicePlugin.md "pServicePlugin"
102103
[pPluginManagement]: :_plg:pPluginManagement.md "pPluginManagement"
103104
[puiButtonExport]: :_plg:puiButtonExport.md "puiButtonExport"
105+
[pExtension]: pExtension.md "pExtension"

‎en/pExport.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,16 +68,57 @@ The ID after the colon (here NEW) will be offered in the drop-down list of the
6868
- The export handler takes the conversion result and calls **evt.output.file('name.txt', result);** to write to the ZIP output
6969
- Finally, the export handler calls **evt.doneHandler();**. This releases the ZIP file to the user's browser for standard download
7070
71+
## Pre-export conversion
72+
73+
In the case of some plugins (naming convention in the **pExtension**\* system - for example: 🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions]), it can be assumed that they perform a transformation into HTML code that general **HTMLTo**\* (**HTMLToMD**, **HTMLToTeX**) converters do not recognize.
74+
75+
### Procedure
76+
77+
1. In the derived class **pExport**\* in **onETPrepareExport**, the variable **corrections** (array) will be defined, which will record future changes in the DOM structure of the chapter text.
78+
2. Trigger the event ⚡ [PreExportCorrection][PreExportCorrection] with **x.temporaryObjects** linked to **corrections**
79+
3. Calls to **onET_PreExportCorrection** will be made on plugins and the outputs from **pExtension**\* plugins will be converted according to the type of export format being prepared - the extension plugin will transform its conversion back into a simplified output for the **HTMLTo**\* converter.
80+
4. **corrections** will contain elements created by the conversion
81+
5. The conversion from HTML to the desired format will be called
82+
6. Go through **corrections** in a loop and delete all contained elements - temporary edits will be cleared from the visible input.
83+
84+
### Sample implementation
85+
86+
```javascript
87+
//...
88+
async onETPrepareExport(evt) {
89+
//...
90+
promise = promise.then(async() => {
91+
//...
92+
const corrections = [];
93+
sendEvent(EventNames.PreExportCorrection, (x) => {
94+
x.exportType = this.aliasName;
95+
x.parent = evt.parent;
96+
x.temporaryObjects = corrections;
97+
});
98+
99+
const converted = HTMLTONEW(evt.parent, ctx);
100+
corrections.forEach(x => x.remove());
101+
//...
102+
}
103+
}
104+
```
105+
106+
The event ⚡ [PreExportCorrection][PreExportCorrection] has a handler on the side of 🧩 [pExtension][pExtension]\*, which ensures point 3 [Procedure][H30].
107+
71108
## Implementation examples
72109
73110
- 🖼️ [pExportHTM][pExportHTM] and other descendants of the class 🖼️ [pExport][pExport] whose names begin with **pExport**.
74111
- Converters: [HTMLToTeX][HTMLToTeX], [HTMLToMD][HTMLToMD]
75112
76113
[puiButtonExport]: :_plg:puiButtonExport.md "puiButtonExport"
77114
[pExportHTM]: :_plg:pExportHTM.md "pExportHTM"
115+
[pExtension]: pExtension.md#h-3-0 "pExtension"
116+
[pExtensionMarkedAdmonitions]: :_plg:pExtensionMarkedAdmonitions.md "pExtensionMarkedAdmonitions"
78117
[PrepareExport]: :_evt:PrepareExport.md "PrepareExport"
118+
[PreExportCorrection]: :_evt:PreExportCorrection.md "PreExportCorrection"
79119
[pExport]: :_plg:pExport.md "pExport"
80120
[resource]: resource.md "Resource"
81121
[pluginslst]: plugins.lst.md "List of plugins (plugins.lst)"
82122
[HTMLToTeX]: https://github.com/HelpViewer/HTMLToTeX "HTML -> TeX"
83123
[HTMLToMD]: https://github.com/HelpViewer/HTMLToMD "HTML -> md"
124+
[H30]: #h-3-0 "Postup"

‎en/pExtension.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# 🧩 pExtension
2+
3+
Plugins with the prefix **pExtension**\* extend the existing functionality of the system or external libraries.
4+
5+
## Naming convention
6+
7+
For example:
8+
🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions]
9+
10+
| Part | Meaning | Example |
11+
| --- | --- | --- |
12+
| **pExtension** | extension | **pExtension** |
13+
| **Marked** | what for? | **marked.js** - external library rendering markdown |
14+
| **Admonitions**| what does it provide? | **highlighted blocks** |
15+
16+
(same library = one common prefix and part of common logic in ancestor **pExtensionMarked**)
17+
18+
## Implementation
19+
20+
1. A new plugin will always have 🧩 [pExtension][pExtension] as its base class.
21+
2. The implementation varies greatly depending on the element it will extend. Follow the steps in the chapter 🧩 [first plugin][firstPlugin]
22+
3. The new plugin must be added to 📄 [plugin list][pluginslst] as follows:
23+
24+
```
25+
pExtensionMarked
26+
pExtensionMarkedAdmonitions:
27+
```
28+
29+
in an order that is lower than **pExtension** in the list.
30+
31+
## Possible responsibilities
32+
33+
These plugins may have responsibilities that are discussed in the following subchapters.
34+
35+
### Pre-export conversion
36+
37+
In the case of some plugins, it can be assumed that they perform a transformation into HTML code that general **HTMLTo**\* (**HTMLToMD**, **HTMLToTeX**) converters do not recognize.
38+
39+
Therefore, the plugin side must define the handling of the **onET_PreExportCorrection** event ⚡ [PreExportCorrection][PreExportCorrection], with its **x.temporaryObjects** linked to **corrections** at the point of the export request. **This plugin is responsible for the export output method.** It receives the export type from the call data. It should also provide a backup handler for new or unknown formats (**\***).
40+
41+
Handler example:
42+
43+
```javascript
44+
onET_PreExportCorrection(e) {
45+
if (!e || !e.parent) return;
46+
47+
const cssClass = this.cfgROOTCSSCLASS;
48+
const willBeUpdated = [...$A(`.${cssClass}`, e.parent)];
49+
const exportFormatting = new Map([
50+
['MD', (id) => `> [!${id}]`],
51+
['TEX', (id) => `<strong>[!${id}]</strong> `],
52+
['*', (id) => ''],
53+
]);
54+
55+
willBeUpdated.forEach(x => {
56+
const typeClass = x.className.split(' ').filter(Boolean).find(c => c.startsWith(cssClass) && c !== cssClass) || '';
57+
if (typeClass) {
58+
const correctionText = (exportFormatting.get(e.exportType) || exportFormatting.get('*'))?.(typeClass.toUpperCase().substring(cssClass.length + 1));
59+
if (correctionText) {
60+
const correction = document.createElement('span');
61+
correction.className = e.CSSClassName;
62+
correction.innerHTML = correctionText;
63+
64+
x.prepend(correction);
65+
e.temporaryObjects.push(correction);
66+
e.manipulatedObjects.push(x);
67+
}
68+
}
69+
});
70+
}
71+
```
72+
73+
(🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions])
74+
75+
## Příklady implementací
76+
77+
- 🧩 [pExtensionMarkedAdmonitions][pExtensionMarkedAdmonitions], 🧩 [pExtensionMarked][pExtensionMarked], and other descendants of the class 🧩 [pExtension][pExtension] whose names begin with **pExtension**.
78+
79+
[pExtension]: :_plg:pExtension.md "pExtension"
80+
[pExtensionMarkedAdmonitions]: :_plg:pExtensionMarkedAdmonitions.md "pExtensionMarkedAdmonitions"
81+
[pExtensionMarked]: :_plg:pExtensionMarked.md "pExtensionMarked"
82+
[firstPlugin]: firstPlugin.md "První plugin"
83+
[pluginslst]: plugins.lst.md "Seznam pluginů (plugins.lst)"
84+
[PreExportCorrection]: :_evt:PreExportCorrection.md "PreExportCorrection"

‎en/tree.lst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@ Plugin implementation|Plugin implementation||implPlug.md
2323
🖼️ pTRPhasePlugin|pTRPhasePlugin||pTRPhasePlugin.md
2424
🖼️ pTopicRenderer|pTopicRenderer||pTopicRenderer.md
2525
🖼️ pExport|pExport||pExport.md
26+
🧩 pExtension|pExtension||pExtension.md
2627
🔌 pServicePlugin|pServicePlugin||pServicePlugin.md
2728
Object definitions|Object definitions||objDef.md
2829
⚙️ Configuration option|Configuration option||cfgopt.md

0 commit comments

Comments
 (0)