====== fields Plugin ======

---- plugin ----
description: Allows storage and retrieval of user-defined fields throughout the page
author     : Aurélien Bompard, lpaulsen93
email      : aurelien@bompard.org
type       : syntax
lastupdate : 2021-03-27
compatible : Binky, Adora Belle, 2006-11-06, 2016-06-26 "Elenor Of Tsort", Greebo, Hogfather
depends    : 
conflicts  : 
similar    : data, easyvar, replace, kixovar, macros, textinsert
tags       : meta, odt, replace

downloadurl: https://github.com/lpaulsen93/dokuwiki-plugin-fields/archive/master.zip
sourcerepo : https://github.com/lpaulsen93/dokuwiki-plugin-fields
bugtracker : https://github.com/lpaulsen93/dokuwiki-plugin-fields/issues
donationurl: https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=59CSTDNRERRNU&lc=FR&item_name=Aur%c3%a9lien%20Bompard&item_number=dokuwiki&currency_code=EUR&bn=PP%2dDonationsBF%3abtn_donate_SM%2egif%3aNonHosted
----

This plugin allows you to define "fields" in a page, which can be used anywhere ((it doesn't appear to work in headings, not in DATA plugin)) in the document. This can be very useful to set an author name, a reference string, or a version number for example, and use those variables anywhere in the page.


===== Download =====

Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.

I use [[wp>Git (software)|Git]] to manage the source code, which is [[https://github.com/lpaulsen93/dokuwiki-plugin-fields|hosted on Github]]. You can obtain the development version with this command :
<code>git clone https://github.com/lpaulsen93/dokuwiki-plugin-fields.git</code>

Some interesting links on Git:
  * [[http://www.kernel.org/pub/software/scm/git/docs/everyday.html|Everyday Git with 20 commands]]
  * [[http://cworth.org/hgbook-git/tour/|A tour of Git]]
  * [[http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html|A tutorial introduction to Git]].

If you have any requests (bugs, features, etc.), please use [[https://github.com/lpaulsen93/dokuwiki-plugin-fields/issues|the plugin's tracker]], I don't monitor this page.

===== Usage =====

To **set a field**, use the following syntax:

<code>{{fields>FIELD_NAME=FIELD_VALUE}}</code>

where "FIELD_NAME" is the name of the field and "FIELD_VALUE" is the value (obviously :) ). Neither the name nor the value need to be uppercase, in fact they may contain any character. The field value can even contain equal signs ("=").

To **display a field**, use the following syntax:

<code>{{fields>FIELD_NAME}}</code>

**Note**: This plugin supports XHTML rendering as well as [[plugin:odt|ODT rendering]].

==== Usage in ODT rendering ====

In OpenOffice.org, add a field in this way:
  * Insert -> Field -> Other -> Variable -> User Field
  * You can leave the value empty
  * Add this field in your document (usually by clicking on 'insert' in the above window)
  * It's done :-)

===== Discussion =====

Feel free to contact me by mail, as I don't monitor this page. If you have any requests (bugs, features, etc.), please use [[https://github.com/lpaulsen93/dokuwiki-plugin-fields/issues|the plugin's tracker]].

==== Issues ====

=== Writes directly HTML code ===

The content of the "fields" seems to be directly output as HTML-Code((I have not looked into the plugin's code yet)), i.e.

  * you cannot use any DokuWiki formatting in field content
  * you //can// use nearly any HTML directive in field content - from simple font style as //italic// to :!: Script Code((only HTML based, i.e. Javascript etc. via ''<SCRIPT>'', no PHP or something via ''<?..?>'')) 

The latter opens the usual question //bug or feature//: for my purposes in a "super-closed" wiki (only approved users can even read the wiki and not all of them can edit everything) it may be a benefit in some cases while especially **in open wikis** (anonymous people can edit) **it //is// a security hole** - __but__ @Aurélien: please do NOT retract this wonderful tool

 --- [[user>hh lohmann|hh lohmann]] //2014/01/10 09:10//

> If this is true (also haven't checked the code yet), then this should be properly [[devel:security#reporting_security_issues|reported]] and a ''securityissue'' be added to the plugin's data. --- [[user>ach|Anika Henke]] //2014/01/14 01:37//

==== Fields of Application ====

//(note: the same term "fields" here reveals to be pure coincidence!)//

=== Multiple use of same token ===

As stated in the main description: If you have the same information at many places, you can maintain (change) it centrally by using a //field//.

:-P You may also span this over pages by including field definitions via [[plugin:include]].

 --- [[user>hh lohmann|hh lohmann]] //2014/01/10 09:17//

=== Separation of presentation and content ===

The //fields// allow a clear and concise maintenance of data since you can access the fields' content totally apart from its presentation - vice versa you can maintain complex presentation layouts since being not intermingled with data maintenance concerns (see also [[wp>Separation of presentation and content]]).

:-P In conjunction with [[plugin:include]] you can drive this further by applying (via including) a uniform and centrally (and so separately) maintained template to "local" data.

//Hint//: compare this to dokuwiki.org's uniform plugin description pages via [[plugin:repository]]

 --- [[user>hh lohmann|hh lohmann]] //2014/01/10 09:17//