====== odtsupport Plugin ======

---- plugin ----
description: 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.
author     : Thomas Schäfer
email      : thomas@hilbershome.de 
type       : syntax
lastupdate : 2023-01-31
compatible : 2020-07-29 "Hogfather",2022-07-31 "Igor"
depends    : odt, text
conflicts  : 
similar    : 
tags       : export, odt

downloadurl: https://github.com/ternite/dokuwiki-plugin-odtsupport/archive/v0.87.zip
bugtracker : https://github.com/ternite/dokuwiki-plugin-odtsupport/issues
sourcerepo : https://github.com/ternite/dokuwiki-plugin-odtsupport
donationurl: 

screenshot_img : 
----

===== Installation =====

Install 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.

:!: **External requirements:** This plugin requires the following additional components that must be installed separately: 
  * [[odt]]
  * [[text]] (optional: allows to use the search for generated pagecodes)
  * [[fields]] (mandatory for some commands)

If 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//.

//metadatatofield//, //pagehashtofield//, //pagehashtofield4// will silently fail, unless you installed the [[fields]] plugin.

===== What's it for? =====

Take 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.

{{https://github.com/ternite/dokuwiki-plugin-odtsupport/raw/main/footer-example.png}}

The 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.

How 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.

In 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.

In 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.

An 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.


===== Syntax =====

==== hash ====

<code>{{hash>string}}</code>

//Example:// <code>{{hash>TEST}}</code> will result in the following output: a96df14f8b5ccb567eede45bdddf189f

==== pagehash ====

<code>{{pagehash}}</code>

Take the page's namespace(s) and pagename to create an MD2 hash value and output it.

==== pagehash4 ====

<code>{{pagehash4}}</code>

Take 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.

==== metadatatofield ====

  * **required plugin: [[fields]] **

<code>{{metadatatofield>string}}</code>

Relay a properly addressed metadata value of the wiki page into a field in an exported ODT file. (Replace "string" with the correct address.)

Refer 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".

If the metadata address contains the string 'date', the field will be filled with a formatted date.

//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.

==== pagehashtofield ====

  * **required plugin: [[fields]] **


<code>{{pagehashtofield>string}}</code>

Take 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".

//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.

==== pagehashtofield4 ====

  * **required plugin: [[fields]] **

<code>{{pagehashtofield4>string}}</code>

Same as //pagehashtofield//, but will only output the first 4 characters.

==== serverurl ====

<code>{{serverurl>string:string2}}</code>

Inserts 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//.

You can use the keywords //<PAGEHASH>// and //<PAGEHASH4>// to insert page hashes within //string// and //string2//.

//Example:// (given that the //serverurl// configuration setting is set to 'file:\\\\\SERVER\documents', and the page's 4-hash is 'abbt')

<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//.

===== Configuration and Settings =====

  * **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.
  * **serverurl** - URL to a server location. See serverurl syntax description.
  * **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.

===== Development =====

[[https://github.com/ternite/dokuwiki-plugin-odtsupport|Sources]] on github.

=== Change Log ===

  * **2021-03-13**
    * v0.82-alpha (Initial release)
  * **2021-03-22**
    * v0.83 (Added structured dependency to the fields plugin.)
  * **2021-05-27**
    * v0.84 Smaller fixes
  * **2022-01-28**
    * v0.85 Added serverurl functionality
  * **2022-12-15**
    * v0.86 Added possibility to use hash4 pattern
      * Also, the repository had to be recreated. The reason for the loss on github.com is unknown.
  * **2023-01-31**
    * v0.87 Added optional usage of the [[usecounter]] plugin and the config option 'firstdefinitionwins'.

=== Known Bugs and Issues ===

See [[https://github.com/ternite/dokuwiki-plugin-odtsupport/issues|issue tracker]] on github.

===== FAQ =====

None, yet.

===== Discussion =====

Start here.