|
| 1 | +# 📑 Documenting objects |
| 2 | + |
| 3 | +To maintain the clarity of the application and plugins, it is recommended that new objects always be documented whenever possible. |
| 4 | + |
| 5 | +In HelpViewer, documentation is organized as a tree of objects and automatic lists with the option to click through to a detailed page. Everything is controlled by 🧩 [object browser][oexplorer], which displays content according to the current state of the system. On individual pages, it can then supplement information from manually prepared documentation (if available), thereby expanding automatically generated chapters. |
| 6 | + |
| 7 | +This manual documentation can be expanded in the [helpInternalRef][RhelpInternalRef] repository (zip/i directory in the HelpViewer project). This repository becomes part of the released package and has a structure corresponding to a standard help file. The format and preparation procedure are described in the [author documentation][AuthDoc]. |
| 8 | + |
| 9 | +Within this special help, you only add .md files. There is no need to deal with the tree or indexes, as they are dynamically created by the 🧩 [object explorer][oexplorer] according to the state of the system. |
| 10 | + |
| 11 | +## Naming convention for descriptive documents |
| 12 | + |
| 13 | +General location structure: |
| 14 | +**i/(language, ISO 639-1 abbreviation)/(object type abbreviation)_(plugin class name)\_(plugin instance name)\_(object name).md** |
| 15 | + |
| 16 | +If you have problems with text not displaying, you can also obtain the exact expected location from the **browser dev console** messages (Warning level, message starts with: 'ObjectExplorer: requested path:'). |
| 17 | + |
| 18 | +In the examples, the **en** subdirectory represents the language. |
| 19 | + |
| 20 | +| Object type | Full path example and description | |
| 21 | +|---|---| |
| 22 | +| Plugin group | **i/en/grp_UI.md** (UI can be replaced by any other group from the [group list][oexplorerGrp] in the object browser) | |
| 23 | +| 🧩 Plugin class | **i/en/plg_pColorTheme.md** (pColorTheme is the name of the plugin class) | |
| 24 | +| 🔹 Plugin instance | **i/en/oeod_inst_puiButtonKeywordIndex_keywordList.md** (puiButtonKeywordIndex is the name of the plugin class, keywordList is the name of the instance or is not specified if aliasName (id) is empty) | |
| 25 | +| ⚡ Event | **i/en/event_PluginsDump.md** (PluginsDump is the name of the event) | |
| 26 | +| ⚡ Event field | **i/en/p_PluginsDump_createdAt.md** (PluginsDump is the name of the event, createdAt is the name of the field) | |
| 27 | +| ⚡ Event field (backup description across documentation) | **i/en/p__createdAt.md** (createdAt is the field name, there are two underscores in the path, leave these) | |
| 28 | +| ⚙️ Configuration option | **i/en/cfgopt_puiButtonKeywordIndex_keywordList_CAPTION.md** (puiButtonKeywordIndex is the name of the plugin class, keywordList is the name of the plugin instance, CAPTION is the name of the configuration key on the code side) | |
| 29 | +| 🛰️ [Event sending][eventTra] | **i/en/transmitter_puiSidebar_sidebar_ClickHandlerRegister.md** (puiSidebar is the name of the plugin class, sidebar is the name of the plugin instance, ClickHandlerRegister is the name of the transmitted event) | |
| 30 | +| 📦 Source/Package | **i/en/res_pTRParseMd_-md_MARKED.md** (pTRParseMd is the name of the plugin class, -md is the name of the instance, MARKED is the name of the source) [Source][resource] may have additional descriptive information. | |
| 31 | +| 👂 Event handler | **i/en/hdl_puiButtonKeywordIndex_keywordList_onETIndexFileLoaded.md** (puiButtonKeywordIndex is the name of the plugin class, keywordList is the name of the plugin instance, onETIndexFileLoaded is the full name of the event handler function on the code side) | |
| 32 | +| 🔘 UI element | **i/en/uiobject_puiButtonKeywordIndex_keywordList_downP-Glossary.md** (puiButtonKeywordIndex is the name of the plugin class, keywordList is the name of the plugin instance, downP-Glossary is the id of the html element id of the element) | |
| 33 | +| ⭐ Javascript event | **i/en/sysevent_pConvertSysEventToEvent_pPrePrintEvent_window.beforeprint.md** (pConvertSysEventToEvent is the name of the plugin class, pPrePrintEvent is the name of the plugin instance, window is the name of the HTML element to which the handler was attached, beforeprint is the name of the Javascript event) | |
| 34 | +| ⇄ Integrated process | **i/en/grpproc_fulltextList.md** (toc is the name of the integrated process - the name of the plugin instance) | |
| 35 | +| 📄 Source code listing | **i/en/cpp_pIndexFile.md** (pIndexFile is the name of the plugin class) | |
| 36 | + |
| 37 | +## Convention for linking to documentation from external help |
| 38 | + |
| 39 | +⚠️ For the links to work and the chapter to be displayed, the [object browser][oexplorer] must be open before accessing the data within the session. Indexing always takes place when the tree tab of this plugin is opened. |
| 40 | + |
| 41 | +General link path structure: |
| 42 | +**:(object type):(plugin class name):(plugin instance name):(object name).md** |
| 43 | + |
| 44 | +| Object type | Link path example | |
| 45 | +|---|---| |
| 46 | +| Plugin group | **:_grp:UI.md** | |
| 47 | +| 🧩 Plugin class | **:_plg:pTopicRenderer.md** | |
| 48 | +| 🔹 Plugin instance | **:_inst:pIndexFile:fulltextList.md** | |
| 49 | +| ⚡ Event including handler | **:_evt:DebugEventEvent.md** | |
| 50 | +| 📄⚡ Event without handler | **:_evtD:DebugEventEvent.md** | |
| 51 | +| ⚙️ Configuration option | **:_cfg:pIndexFile:keywordList:FILENAMEKW.md** | |
| 52 | +| 📄⚙️ Configuration option ([dynamic][cfgDyn]) | **:_cfgE:puiButtonObjectExplorer:-load:RENDER-F.md** | |
| 53 | +| 🛰️ [Event sending][eventTra] | **:_tra:puiSidebar:sidebar:ClickHandlerRegister.md** | |
| 54 | +| 📦 Source/Package | **:_res:pTRParseMermaid:-connected:MERMAID.md** | |
| 55 | +| 👂 Event handler | **:_hdl:puiHeader:header:onETButtonSend.md** | |
| 56 | +| 🔘 Button | **:_btn:puiButtonVersionSearch::downP-ChangeVersion.md** | |
| 57 | +| 🎛️ Card | **:_page:puiButtonObjectExplorer:-load:oexpP.md** | |
| 58 | +| 📂 Tree | **:_tree:puiButtonObjectExplorer:-load:objectList.md** | |
| 59 | +| ⭐ Javascript event | **:_evtSys:pConvertSysEventToEvent:pPrePrintEvent:window.beforeprint.md** | |
| 60 | +| ⇄ Integrated process | **:_grpproc:fulltextList.md** | |
| 61 | +| 📄 Source code listing | **:_cpp:pui.md** | |
| 62 | + |
| 63 | +The documentation for authors describes how to [add a link to the chapter text][AuthDocLinks]. |
| 64 | + |
| 65 | +### Obtaining the path to an object from the object browser |
| 66 | + |
| 67 | +1. Open 🧩 [object browser][oexplorer]. |
| 68 | +2. Find the desired object: |
| 69 | + - in the **object tree** |
| 70 | + - or by entering it in the **search bar** and pressing **Enter** |
| 71 | +3. Open the browser's dev tools. |
| 72 | +4. Activate **Select element** and click on the corresponding **a** object. |
| 73 | +5. In the **data-param** attribute, you will find the full path to the object. |
| 74 | + |
| 75 | +[RhelpInternalRef]: https://github.com/HelpViewer/helpInternalRef "HelpViewer documentation for system objects" |
| 76 | +[AuthDoc]: ?d=hlp-aguide/Help-__.zip "Documentation for authors" |
| 77 | +[oexplorer]: oexplorer.md "Object browser" |
| 78 | +[oexplorerGrp]: :_cfg:puiButtonObjectExplorer:-load:GROUPSLIST.md "List of groups in the object explorer" |
| 79 | +[resource]: resource.md#h-2-3 "Resource - further information" |
| 80 | +[cfgDyn]: cfgopt.md#h-2-1 "Dynamic configuration keys" |
| 81 | +[eventTra]: event.md#h-2-2 "Sending an Event" |
| 82 | +[AuthDocLinks]: ?d=hlp-aguide/Help-__.zip&d=hlp-aguide/Help-__.zip&p=links.md#h-3-0 "Links in texts" |
0 commit comments