EN : First version of EN translation from Czech

Author: VitSimon

en/README.md

@@ -1,5 +1,16 @@
-# Developer Guide
+# Documentation for developers
 
-The main goal is to describe: 
-- HelpViewer GitHub overview and versioning description,
-- How to extend HelpViewer itself
+The purpose of this documentation is to describe:
+
+- The concept of the HelpViewer application and a list of technologies used
+- The structure of the HelpViewer application and its startup sequence
+- An overview of definition lists
+- A description of HelpViewer tools for analyzing system status
+- Procedures and specifics for configuring existing standard plugins and functionalities
+- Procedures and specifics for developing custom plugins and functionalities
+- Description of the possibilities for extending the project itself
+- Analysis and examples of specific possible implementations of plugins and their subordinate objects
+- Description of the operation of the event/message distribution system in the application, including message filtering
+- Description of the procedure for preparing a new language
+- Overview of the structure of the HelpViewer GitHub organization and description of versioning
+- Operational documents and links to groups and other resources

en/appendix.md

@@ -0,0 +1,3 @@
+# 📘 Appendices
+
+This chapter contains a complete list of documentation appendices.

en/cfgopt.md

@@ -0,0 +1,51 @@
+# ⚙️ Configuration option
+
+The configuration option represents ⚙️ [plugin configuration][cfgPlug] on the plugin code side.
+
+## Definition
+
+```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);
+```
+
+### Configuration file example
+
+This definition is paired with this definition in the configuration file:
+
+```text
+FILENAME|README.md
+```
+
+[Example on the object browser page][pTRParseMd]
+
+If the key from the **KEY_CFG_FILENAME** constant is not found in the configuration file, the value **DEFAULT_KEY_CFG_FILENAME** is used.
+
+### Meaning of variables
+
+- KEY_CFG_FILENAME - name of the configuration key on the configuration side
+- DEFAULT_KEY_CFG_FILENAME - default value for the configuration key
+- ⚠️ DEFAULT_**KEY_CFG_FILENAME** and **KEY_CFG_FILENAME** must match in name so that the object browser can correctly evaluate the configuration option and link the name and default (backup) value.
+
+## Records 📄⚙️
+
+If records with the 📄⚙️ icon appear in the [object explorer][oexplorer], it means that the specific keys contained in the configuration are not listed in the plugin as described here in the [definition](#h-2-0).
+
+The reasons for this may include:
+
+- An approach inspired by the [object explorer][oexplorer], where the goal is to have an open set of configuration keys. The list of groups can be arbitrarily long, and its items refer to other keys. These keys are not known in advance because the configuration can be changed dynamically, but the plugin can read them correctly thanks to its internal logic.
+- A typo in the key on the configuration file side leads to the creation of another visible item, while the default value is used for the key with the correct name because nothing is read.
+
+[cfgPlug]: pluginConfig.md "Plugin configuration"
+[pTRParseMd]: :_inst:pTRParseMd:-md.md#h-2-1 "pTRParseMd:-md"
+[oexplorer]: oexplorer.md "Object explorer"

en/concept.md

@@ -0,0 +1,34 @@
+# 🗺️ Basic overview
+
+The application is built on **plugins (plug-in modules) and the transfer of events (messages) between them**.
+
+The following can be defined in plugins:
+
+- events (messages),
+- their handlers,
+- sending events,
+- UI elements,
+- JavaScript event handlers,
+- membership in a communication path (group of recipients)
+
+This ensures that the approaches to the UI and program logic are consistent across the entire application.  
+The plugin system and message distribution have been developed from scratch, without the use of third-party frameworks.  
+
+**Technical solution:**
+
+- compressed application data package (with the option to run with unzipped content),
+- runs on the client, no server or backend required,
+- minimum requirements for deployment: browser with **ES2021** support + local disk (no Internet required) (CORS is recommended to be disabled, although the application includes support for manual data upload by the user)
+
+**Main components of the application:**
+
+- loader (**hvdata/appmain.js + jszip.min.js**),
+- application data (**hvdata/data.zip**; **STO_DATA**), where most of the application is stored (about 86% of the package size)
+  - low-level code (in **js.lst**),
+  - plugin code (in **plugins.lst**).
+- third-party libraries (separate, loaded as separate modules)
+- implementation data file - a separate archive in the application logically named **STO_HELP**
+
+**⚖️ License**: [MIT][MIT]
+
+[MIT]: https://github.com/HelpViewer/HelpViewer/blob/master/LICENSE "MIT license"

en/css.lst.md

@@ -0,0 +1,18 @@
+# 📄 List of styles (css.lst)
+
+- ⚠️ This format is very strict, please follow the rules exactly.
+- The file defines the list and order of CSS styles that the application will apply.
+- One line = one item
+- Line breaks in the middle of a definition are not allowed
+
+## File structure
+
+```text
+[1]
+```
+
+## Position descriptions
+
+| Position | Description |
+|---|---|
+| `[1]` | Relative path to the file with the extension relative to the root of the data store. |

en/debug.md

@@ -0,0 +1,13 @@
+# 🐞 Debug mode
+
+- Debug mode is automatically disabled in production.
+- Enable it by changing **DEBUG_MODE** to **true** in **hvdata/appmain.js**.
+
+## Features available in debug mode
+
+- 🧩 [Object explorer][oexplorer]
+- 📜 Logging to the browser's DevTools console
+- ⚡ Sent events are also duplicated into the [DebugEventEvent][DebugEventEvent] event, which is processed by the object explorer in order to capture event transfers between application entities during runtime
+
+[DebugEventEvent]: :_evt:DebugEventEvent.md "DebugEventEvent"
+[oexplorer]: oexplorer.md "Object Explorer"

en/event.md

@@ -0,0 +1,94 @@
+# ⚡ Event
+
+An event defines an application event/message.  
+An event can be defined with a handler or just defined (without a handler).
+
+## Definition
+
+1. Define the event data object or specify which of the already defined descendants ⚡ [IEvent][IEvent] is suitable for your event:
+
+```javascript
+class ClickHandlerRegister extends IEvent {
+  constructor() {
+    super();
+    this.handlerId = undefined;
+    this.handler = undefined;
+  }
+}
+```
+
+2. Define the plugin class for the event:
+
+```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. Decide whether you can have the handler directly in the plugin or whether you need to have it outside the plugin. Depending on your case, choose the necessary procedure according to the following chapters.
+
+4. Always insert the source code of the chapter into the comment **(B)**.
+
+### ⚡ Event with handler
+
+```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]);
+```
+
+### 📄⚡ Event only defined
+
+```javascript
+    TI.eventDefinitions.push([T.EVT_CLICK_HANDLER_REGISTER, ClickHandlerRegister, null]); // outside event handlers
+```
+
+### Meaning of elements
+
+- class ClickHandlerRegister - event data object (it is possible to use the same class for multiple events or inherit from any IEvent descendant)
+- ClickHandlerRegister.constructor - contains the default values of the message object. It is desirable that the values be pre-filled with the default value according to the planned type, if possible. This data is used in the [object explorer][oexplorer] as part of the system's automatic documentation.
+- const h_EVT_CLICK_HANDLER_REGISTER - event handler
+- reply.result - standard event property (⚡ [IEvent][IEvent]), which is automatically taken over by the application logic as the handler's response to the event. It can be any object.
+- TI.eventDefinitions.push([T.EVT_CLICK_HANDLER_REGISTER, ClickHandlerRegister, null]) - creates an event definition prescription (event name, event data object, and handler method, or null if the event is only to be defined). The processing of definitions is handled by the ancestor 🔌 [IPlugin][IPlugin].
+- super.init(); - performs standard initialization of bindings. It must be the last command in order for everything defined to be initialized properly.
+
+## Sending an event
+
+In the handler code, you can then trigger events as follows:
+
+```javascript
+      const eventName = EventNames.MyNewEvent; //nebo: 'MyNewEvent'
+
+      sendEvent(eventName, (r) => {
+        r.id = aliasName;
+        r.result = loadedCount;
+        //vyplnění dalších potřebných dat
+      });
+```
+
+In the **appmainBaseLogic.js** file, you will find examples of functions that encapsulate similar calls.  
+⚠️ It is recommended to create a similar set of functions for your plugin in a separate file (which you will add to the [list of scripts][jsList]). Calls to the **sendEvent** method are not indexed for the [object explorer][oexplorer], but these functions will be indexed.
+
+## Records 🛰️
+
+A record in the 🛰️ [object explorer][oexplorer] means that:
+
+- in the plugin instance overview: the plugin sends the event ...
+- in the list of event communication paths: the event is sent from ...
+
+[IEvent]: :_evt:IEvent.md "IEvent"
+[oexplorer]: oexplorer.md "Object explorer"
+[IPlugin]: :_plg:IPlugin.md "IPlugin"
+[jsList]: js.lst.md "List of scripts"

en/eventFilter.md

@@ -0,0 +1,38 @@
+# 🔺 Filtering events in plugins
+
+Each plugin can receive events from the system. Plugins have a switch to (de)activate the filter for receiving events according to the **aliasName (id)** of the plugin instance:
+
+```javascript
+this.eventIdStrict = true;
+```
+
+Make the call in the constructor or at the beginning of the init() function, or at the latest before calling base.init().
+
+Event filtering is two-stage - according to eventIdStrict and the name of the handler function. This is described in more detail in the following subchapters.
+
+## Summary
+
+- The **onET_(event name)** function accepts all events with eventName = (event name)
+- The **onET(event name)** function accepts all events with eventName = (event name) and id = plugin.aliasName
+- **A plugin with plugin.aliasName = ''** accepts all events into the **onET(event name)** or **onET_(event name)** function
+
+⚠️ It is recommended to have only one of the following handlers in the plugin:
+
+- onET(event name)
+- onET_(event name)
+
+## How to decide on the settings?
+
+The plugin should not listen to all events, but only some will be sent directly to it, so it will receive a specific id and eventIdStrict = true.
+
+Set EventIdStrict to **true** at least in these cases:
+
+- The plugin will (or may) run in more than one instance (for example, 📇 keyword dictionary and 🔎 full-text search)
+- The plugin will be part of a process (🖼️ [pTRPhasePlugin][pTRPhasePlugin] - listing the contents of a chapter)
+- The plugin will be part of a larger functional unit (🔹 [pIndexFile:fulltextList][pIndexFile] - dynamic creating a full-text index of help)
+
+📘 A [detailed appendix][appendix] is available for this chapter.
+
+[pTRPhasePlugin]: pTRPhasePlugin.md "pTRPhasePlugin"
+[pIndexFile]: :inst:pIndexFile:fulltextList.md "pIndexFile:fulltextList"
+[appendix]: eventFilterD.md "Rozbor filtrování událostí v pluginech"

en/eventFilterD.md

@@ -0,0 +1,47 @@
+# 🔺 Filtering events in plugins details
+
+## Decision process diagram
+
+```mermaid
+flowchart LR
+  Event[⚡ Event - eventName, id] --> CheckHandler
+  Plugin[🧩 Plugin - aliasName, eventIdStrict] --> CheckIdRelaxed
+  Plugin --> CheckIdStrict
+  Plugin --> CheckStrict
+  CheckHandler{👂 Is there a handler for eventName?} -->|NO| EndN
+  CheckHandler -->|YES| CheckStrict
+  CheckStrict{plugin.eventIdStrict} -->|🔺 YES| CheckIdStrict
+  CheckStrict -->|🟢 NO| CheckIdRelaxed
+  CheckIdStrict{id = plugin.aliasName?} -->|YES| EndY
+  CheckIdStrict -->|NO| EndN
+  CheckIdRelaxed{id = plugin.aliasName or plugin.aliasName = ''?} -->|YES| EndY
+  CheckIdRelaxed -->|NO| EndN
+  EndY[✔️ Pass to plugin]
+  EndN[⛔ Do not pass]
+```
+
+## 0. Meaning of aliasName values (''/...)
+
+| aliasName | Description |
+|---|---|
+| '' | (Initialization **class:** in the plugin list). If this value is set, the plugin is able to receive most system messages (they are usually sent with an empty id). |
+| xxx | If the value is filled in any other way, the **eventIdStrict** property determines further processing. |
+
+## 1. Meaning of eventIdStrict values (🟢/🔺)
+
+The usual value is **false**, so that the plugin accepts all events regardless of their ID.
+
+| eventIdStrict | Description |
+|---|---|
+| false | 🟢 The IDs of incoming events are not filtered. Incoming events are filtered only by plugin handlers named **onET_(event name)** or **onET(event name)** |
+| true | 🔺 Strict ID matching in events is required. That is, if **aliasName** (**id** of the plugin) and **id** in the event match, then the event is passed to the plugin. In order for the plugin to process the event, it must also have a defined handler method **onET_(event name)** or **onET(event name)** |
+
+If **false** is present and the plugin has an empty **aliasName (id)** (initialization **class:**), then the event **is passed** to the next step for processing. In the case of **false**, the name of the handler **ET vs. ET_** is also not decisive.
+
+## 2. Name of the handler function (ET/ET_)
+
+| Event name | Result |
+|---|---|
+| **There is no onET function in the plugin** | The event is not passed to the plugin for processing. |
+| onET_(event name) | (onET underscore) The event is passed to the plugin for processing **regardless of whether the event id and plugin id match**. ⚠️ **The name of the function with an underscore takes precedence over the eventIdStrict setting.** |
+| onET(event name) | (onET) The event is passed to the plugin for processing **only if the event ID and plugin ID match**. An unspecified plugin ID is also considered a match. |

en/files.lst

@@ -1,7 +1,40 @@
-README.md|Developer Guide
+README.md|Documentation for developers
 helpviewer.md|HelpViewer Project
 =latestApp|Download latest version
 https://github.com/HelpViewer/HelpViewer|GitHub repository
 https://github.com/HelpViewer/HelpViewer/pkgs/container/helpviewer|Container images
 https://discord.gg/J2SjcmqHSZ|User group
 newLangViewer.md|New language for Viewer
+runseq.md|Startup sequence
+css.lst.md|List of styles
+js.lst.md|List of scripts
+plugins.lst.md|List of plugins
+oexplorer.md|Object explorer
+firstPlugin.md|First plugin
+techstack.md|Used technologies
+pTRPhasePlugin.md|pTRPhasePlugin
+pConvertSysEventToEvent.md|pConvertSysEventToEvent
+implPlug.md|Plugin implementation
+lists.md|Loading Lists
+pTopicRenderer.md|pTopicRenderer
+pluginConfig.md|Plugin configuration
+pluginLoad.md|Loading plugins
+puiButton.md|puiButton
+eventFilter.md|Filtering events in plugins
+eventFilterD.md|Filtering events in plugins details
+appendix.md|Appendices
+puiButtonTab.md|puiButtonTab
+puiButtonTabTree.md|puiButtonTabTree
+objDef.md|Object definitions
+debug.md|Debug mode
+cfgopt.md|Configuration option
+event.md|Event
+concept.md|Basic overview
+handler.md|Event handler
+jsevent.md|JavaScript event processing
+uiobject.md|UI elements
+uibutton.md|Button
+uitab.md|Tab
+uitree.md|Tree
+resource.md|Resource/Package
+routingmc.md|Mouse click routing