1====== odtsupport Plugin ====== 2 3---- plugin ---- 4description: Provides helpers that can be useful when creating ODT files with the odt plugin. For example, the plugin can pipe wiki page metadata into a field within the ODT result. 5author : Thomas Schäfer 6email : thomas@hilbershome.de 7type : syntax 8lastupdate : 2023-01-31 9compatible : 2020-07-29 "Hogfather",2022-07-31 "Igor" 10depends : odt, text 11conflicts : 12similar : 13tags : export, odt 14 15downloadurl: https://github.com/ternite/dokuwiki-plugin-odtsupport/archive/v0.87.zip 16bugtracker : https://github.com/ternite/dokuwiki-plugin-odtsupport/issues 17sourcerepo : https://github.com/ternite/dokuwiki-plugin-odtsupport 18donationurl: 19 20screenshot_img : 21---- 22 23===== Installation ===== 24 25Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually. 26 27:!: **External requirements:** This plugin requires the following additional components that must be installed separately: 28 * [[odt]] 29 * [[text]] (optional: allows to use the search for generated pagecodes) 30 * [[fields]] (mandatory for some commands) 31 32If you installed the [[text]] plugin, the following syntax elements will give their results to be included within the dokuwiki search: //hash, pagehash, pagehash4, pagehashtofield, pagehashtofield4//. 33 34//metadatatofield//, //pagehashtofield//, //pagehashtofield4// will silently fail, unless you installed the [[fields]] plugin. 35 36===== What's it for? ===== 37 38Take a look at the following image. It shows a footer of a generated ODT file. The code "b41f" on the left has been generated by this plugin, and the change date on the right hand side has been taken from the original wiki page's metadata. 39 40{{https://github.com/ternite/dokuwiki-plugin-odtsupport/raw/main/footer-example.png}} 41 42The code "b41f" is a short name for the page it was generated for. In addition to being generated into the ODT file, this code can be used within the dokuwiki search as a helper to quickly find said page. 43 44How am I using that? At my work we produce documents that are reviewed by independent external reviewers that check for regulatory adherence. For that purpose, we need paper copies of wiki pages. We use the [[odt]] plugin to create such documents. 45 46In order to be able to quickly access the original wiki page of a paper document, I added that 4-chars quickcode that can be entered into the dokuwiki search. 47 48In order to be able to check the version/modification date of a paper document, I added the wiki page's modification date to the ODT file. 49 50An addition introduced with version v0.85 is the possibility to use 'serverurl'. This function allows to create links to a specific server address, with some adjustment that can be made to the specific subdirectory and presentation string. Access to the pagehash is available, too. This allows to create links to locations that were specifically made available for the current dokuwiki page. 51 52 53===== Syntax ===== 54 55==== hash ==== 56 57<code>{{hash>string}}</code> 58 59//Example:// <code>{{hash>TEST}}</code> will result in the following output: a96df14f8b5ccb567eede45bdddf189f 60 61==== pagehash ==== 62 63<code>{{pagehash}}</code> 64 65Take the page's namespace(s) and pagename to create an MD2 hash value and output it. 66 67==== pagehash4 ==== 68 69<code>{{pagehash4}}</code> 70 71Take the page's namespace(s) and pagename to create an MD2 hash value and output it's first 4 characters. Since that's rather short, it's possible that two distinct pages share the same short hash. 72 73==== metadatatofield ==== 74 75 * **required plugin: [[fields]] ** 76 77<code>{{metadatatofield>string}}</code> 78 79Relay a properly addressed metadata value of the wiki page into a field in an exported ODT file. (Replace "string" with the correct address.) 80 81Refer to [[:devel:metadata#data_structure]] to see how to address metadata. The field that is created will always be named like the addressing metadata string stripped by white spaces and non-alphanumeric chars (except for an underscore, this one will be allowed). E.g.: "last_change date" will result in a field named "last_changedate". 82 83If the metadata address contains the string 'date', the field will be filled with a formatted date. 84 85//Example:// <code>{{metadatatofield>last_change date}}</code> takes the metadata value addressed by "last_change date" (that's the page's "timestamp, date of last modification") and writes it into the field "last_changedate" within the exported ODT file. 86 87==== pagehashtofield ==== 88 89 * **required plugin: [[fields]] ** 90 91 92<code>{{pagehashtofield>string}}</code> 93 94Take the page's namespace(s) and pagename to create an MD2 hash value and write it to an exported ODT file into the field named like the given "string". 95 96//Example:// <code>{{pagehashtofield>pagecode}}</code> will result in an ODT field with the name "pagecode" containing the corresponding hash value of the wiki page's address. 97 98==== pagehashtofield4 ==== 99 100 * **required plugin: [[fields]] ** 101 102<code>{{pagehashtofield4>string}}</code> 103 104Same as //pagehashtofield//, but will only output the first 4 characters. 105 106==== serverurl ==== 107 108<code>{{serverurl>string:string2}}</code> 109 110Inserts a link to an URL defined in the configuration key 'serverurl' (see configuration). The provided //string// will be appended to the file link. The presentation text is defined by //string2//. 111 112You can use the keywords //<PAGEHASH>// and //<PAGEHASH4>// to insert page hashes within //string// and //string2//. 113 114//Example:// (given that the //serverurl// configuration setting is set to 'file:\\\\\SERVER\documents', and the page's 4-hash is 'abbt') 115 116<code>{{serverurl>\subfolder:My <PAGEHASH4> subfolder}}</code> will result in a link to the following url: //file:\\\\\SERVER\documents\subfolder// and the presentation text will be //My abbt subfolder//. 117 118===== Configuration and Settings ===== 119 120 * **dateformat** - Date format string compliant with the PHP function date(). It's used for the command 'metadatatofield', in case a date is read from the metadata. 121 * **serverurl** - URL to a server location. See serverurl syntax description. 122 * **firstdefinitionwins** - When using 'metadatatofield' or 'pagehashtofield', this configuration option allows to specify that only the first occurence of them will result in setting a field within an ODT file. 123 124===== Development ===== 125 126[[https://github.com/ternite/dokuwiki-plugin-odtsupport|Sources]] on github. 127 128=== Change Log === 129 130 * **2021-03-13** 131 * v0.82-alpha (Initial release) 132 * **2021-03-22** 133 * v0.83 (Added structured dependency to the fields plugin.) 134 * **2021-05-27** 135 * v0.84 Smaller fixes 136 * **2022-01-28** 137 * v0.85 Added serverurl functionality 138 * **2022-12-15** 139 * v0.86 Added possibility to use hash4 pattern 140 * Also, the repository had to be recreated. The reason for the loss on github.com is unknown. 141 * **2023-01-31** 142 * v0.87 Added optional usage of the [[usecounter]] plugin and the config option 'firstdefinitionwins'. 143 144=== Known Bugs and Issues === 145 146See [[https://github.com/ternite/dokuwiki-plugin-odtsupport/issues|issue tracker]] on github. 147 148===== FAQ ===== 149 150None, yet. 151 152===== Discussion ===== 153 154Start here.
