|
| 1 | +# 🖼️ pExport |
| 2 | + |
| 3 | +## Purpose of the plugin |
| 4 | + |
| 5 | +This plugin defines the basic interface for exporting the displayed text of a chapter. |
| 6 | + |
| 7 | +The derived plugin is usually encapsulated logic between: |
| 8 | + |
| 9 | +- **HelpViewer** (🖥️ [puiButtonExport][puiButtonExport]) and |
| 10 | +- a converter from **HTML** to the desired format, which is usually handled by an external script. |
| 11 | + |
| 12 | +If necessary, the plugin 📦 [Resource][resource] will load the converter. |
| 13 | + |
| 14 | +## Implementation |
| 15 | + |
| 16 | +1. A new plugin will always have 🖼️ [pExport][pExport] as its base class. |
| 17 | +2. The implementation will look something like this: |
| 18 | + |
| 19 | +```javascript |
| 20 | +class pExportNEW extends pExport { |
| 21 | + constructor(aliasName, data) { |
| 22 | + super(aliasName, data); |
| 23 | + |
| 24 | + this.RES_HTMLTONEW = new Resource('HTMLTONEW', undefined, STO_DATA, 'HTMLToNEW/HTMLToNEW.js;HTMLToNEW/LICENSE;HTMLToNEW/README.md'); |
| 25 | + } |
| 26 | + |
| 27 | + async onETPrepareExport(evt) { |
| 28 | + let promise = Promise.resolve(true); |
| 29 | + |
| 30 | + if (typeof HTMLTONEW !== 'function') |
| 31 | + promise = this.RES_HTMLTONEW?.init(promise); |
| 32 | + |
| 33 | + promise = promise.then(async() => { |
| 34 | + const ctx = { listStack: [], i_img: 0, i_svg: 0, embeds: evt.embeds }; |
| 35 | + const converted = HTMLTONEW(evt.parent, ctx); |
| 36 | + evt.output.file('output.txt', converted); |
| 37 | + |
| 38 | + if (evt.doneHandler) |
| 39 | + evt.doneHandler(); |
| 40 | + |
| 41 | + }); |
| 42 | + } |
| 43 | +} |
| 44 | + |
| 45 | +Plugins.catalogize(pExportNEW); |
| 46 | +``` |
| 47 | +
|
| 48 | +3. The new plugin must be added to the 📄 [list of plugins][pluginslst]: |
| 49 | +
|
| 50 | +``` |
| 51 | +pExportNEW:NEW |
| 52 | +``` |
| 53 | +
|
| 54 | +in an order that is lower than **pExport** in the list. |
| 55 | +
|
| 56 | +The ID after the colon (here NEW) will be offered in the drop-down list of the 📥 Export button. |
| 57 | +
|
| 58 | +## Functionality description |
| 59 | +
|
| 60 | +- The user clicks on the 📥 Export button |
| 61 | +- The button handler creates a ZIP archive and collects images and other nested elements found in the text into it and sends the data as a link to the chapter text or handler **doneHandler**, which ensures that the ZIP file is displayed to the user |
| 62 | +- The button handler sends the event ⚡ [PrepareExport][PrepareExport] |
| 63 | +- The derived plugin (**pExportNEW**) defines the handler 👂 **onETPrepareExport**, which takes over the prepared intermediate result |
| 64 | +- The export handler (which may be asynchronous) works primarily with: |
| 65 | + - **evt.embeds** - embedded elements, images, SVG |
| 66 | + - **evt.parent** - parent HTML object (display area for chapter text) |
| 67 | +- The export handler calls the converter function, which passes the necessary context object with empty or default values, a reference to the HTML object containing the complete input, or additional input depending on the implementation |
| 68 | +- The export handler takes the conversion result and calls **evt.output.file('name.txt', result);** to write to the ZIP output |
| 69 | +- Finally, the export handler calls **evt.doneHandler();**. This releases the ZIP file to the user's browser for standard download |
| 70 | +
|
| 71 | +## Implementation examples |
| 72 | +
|
| 73 | +- 🖼️ [pExportHTM][pExportHTM] and other descendants of the class 🖼️ [pExport][pExport] whose names begin with **pExport**. |
| 74 | +- Converters: [HTMLToTeX][HTMLToTeX], [HTMLToMD][HTMLToMD] |
| 75 | +
|
| 76 | +[puiButtonExport]: :_plg:puiButtonExport.md "puiButtonExport" |
| 77 | +[pExportHTM]: :_plg:pExportHTM.md "pExportHTM" |
| 78 | +[PrepareExport]: :_evt:PrepareExport.md "PrepareExport" |
| 79 | +[pExport]: :_plg:pExport.md "pExport" |
| 80 | +[resource]: resource.md "Resource" |
| 81 | +[pluginslst]: plugins.lst.md "List of plugins (plugins.lst)" |
| 82 | +[HTMLToTeX]: https://github.com/HelpViewer/HTMLToTeX "HTML -> TeX" |
| 83 | +[HTMLToMD]: https://github.com/HelpViewer/HTMLToMD "HTML -> md" |
0 commit comments