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 : 2022-01-28
9compatible : 2020-07-29 "Hogfather"
10depends    : odt, text
11conflicts  :
12similar    :
13tags       : export, odt
14
15downloadurl: https://github.com/ternite/dokuwiki-plugin-odtsupport/archive/v0.85.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
123===== Development =====
124
125[[https://github.com/ternite/dokuwiki-plugin-odtsupport|Sources]] on github.
126
127=== Change Log ===
128
129  * **2021-03-13**
130    * v0.82-alpha (Initial release)
131  * **2021-03-22**
132    * v0.83 (Added structured dependency to the fields plugin.)
133  * **2021-05-27**
134    * v0.84 Smaller fixes
135  * **2022-01-28**
136    * v0.85 Added serverurl functionality
137
138=== Known Bugs and Issues ===
139
140See [[https://github.com/ternite/dokuwiki-plugin-odtsupport/issues|issue tracker]] on github.
141
142===== FAQ =====
143
144None, yet.
145
146===== Discussion =====
147
148Start here.