Table of Contents
Data Template Plugin
Compatible with DokuWiki
2017-02-19 "Frusterick Manners", 2016-06-26 "Elenor Of Tsort", 2015-08-10 "Detritus", Rincewind, Weatherwax
This extension has not been updated in over 2 years. It may no longer be maintained or supported and may have compatibility issues.
Similar to dataloop, structtemplate, templater
This plugin adds the possibility to display the structured data of the Data Plugin using templates. Templates can be applied to individual data entries or lists of multiple entries. Additionally, this plugin offers a custom search form, pagination and result caching.
News: The original author, Christoph Clausen, cannot maintain anymore the plugin, so I adopt it Thanks a lot to him to have built first steps and accepted the adoption in 2016 august.
Download and Installation
Search and install the plugin using the Extension Manager. Refer to Plugins on how to install plugins manually.
Change Log
- 2016-08-02 Add translation for list navigation links and filter button
- 2016-08-02 Cyrille Giquello adopted the plugin with Christoph Clausen agreement
- 2016-07-11 fix deprecated constructor calls
Last github commits on release 2016-08-03.
- release 2016-08-03 (2016-08-02 18:00)
- add translation #1 (2016-08-02 17:56)
- match plugin version with tag (2016-08-02 13:59)
- match plugin version with tag (2016-08-02 13:57)
- match plugin version with tag (2016-08-02 13:54)
- About plugin adoption (2016-08-02 12:33)
- update plugin information (2016-07-11 17:18)
- redo change deprecated parent constructor call (2016-07-11 17:14)
Template Definition
Templates are separate wiki pages containing placeholders. There are two kinds of placeholders:
- Placeholders enclosed by
@@
, e.g.@@Title@@
will be replaced after the template page has been parsed for wiki instructions. The translation rules of the special types of the data plugin still apply. That is, a field with suffix_mail
will be rendered as an e-mail link, etc. - Placeholders with an additional exclamation in front of the placeholder name, like in
@@!Title@@
will be replaced before the template is processed by the DokuWiki parser. This allows for more fine grained control under some circumstances, like the use of images. - Placeholders with capital letter do not work in the current version — mcgumbel 2014-09-25 18:32
Example
A template definition as in
- tpl_member
{{@@!imgname@@?nolink&200 }} * **Position**: @@type@@ * **Address**: \\ @@!addr@@ * **Phone**: @@phone@@ * **E-Mail**: @@email@@
OR
- tpl_memberlist
=== @@%title%@@ === {{@@!imgname@@?nolink&70 }} **Phone**: @@phone@@ \\ **E-Mail**: @@email@@
will use whatever value is stored in the field imgname
as file name in a standard DokuWiki image syntax, leading to a left floating picture with phone and email to the right. If the email
field was appended by _mail
when listed in the cols
parameter of the datatemplatelist
, it will be correctly rendered as an email link.
Syntax
This plugin provides 3 different syntax blocks:
datatemplateentry
datatemplatelist
filterform
The first two are essentially the same as for the data plugin, but with an added template
parameter.
datatemplateentry
The datatemplateentry
corresponds to the dataentry
of the data plugin. Note that the template should use the column names supplied to the headers
parameter (if given) as placeholders for the substitutions.
The value of the template
parameter is a DokuWiki page containing the template definition, as discussed above. A datatemplateentry
could for example look like this:
---- datatemplateentry member ---- template : tpl_member firstname : Christoph lastname : Clausen type : PhD Student active : yes phone : 123-987654 email_mail : example@example.com imgname_img : pics:userpicture.jpg addr : GAP-Optique \\ Rue de l'Ecole de Medecine 20 \\ CH-1211 Geneve 4 ----
Not all types supported by the data plugin are implemented. Current supported types are:
page
– the entry is treated as Wiki pagename and will be linked in outputtitle
– like page, but an additional display title can be given separated by a pipepageid
– the input is the caption for a link to the data entry pagenspage
– like page, but the column name is treated as namespace for the link.mail
– Eventually additional text (separated by space) is used as name that will be linked with the given email addressurl
– the value will be treated as external linkimg
– the input is assumed to be a image URL or local media id and is displayed as givenwiki
– render the input as wikitext
When no type is given the input is handled as wiki text.
datatemplatelist
The datatemplatelist
corresponds to the datalist
of the data plugin. Contrary to its “brother”, the datatemplatelist
also supports pagination.
Example syntax:
---- datatemplatelist ---- template: tpl_memberlist cols : %title%, imgname, phone, email_mail sort : firstname filter : %pageid%~members:* and : type=Group Leader and : active=yes ----
This list all the pages in members:
that satisfy the conditions set in this syntax and uses the tpl_memberlist
page to render a nice entry in the list for each page. When column names of the cols
parameter are appended by a type e.g. _mail
, this type is used when rendering this value.
The cols
parameter defines the placeholders available in the template. For the example above, you can use e.g. @@imgname@@
in your template. The available column names in cols
corresponds with the column names used in the data entries. However there are some additional columns available for adding extra columns to the data list:
Column name | Appearance | Placeholder |
---|---|---|
%title% | The first headline of a page, which has a link to data entry page. | @@%title%@@ |
%pageid% | The page name, which has a link to data entry page | @@%pageid%@@ |
%class% | The class of a data entry | @@%class%@@ |
%lastmod% | The date of last modification of the entry | @@%lastmod%@@ |
Beside the columns you list in cols
there is one column always available, that is %pageid%
.
Deprecated
Untill 18 May 2013 the special placeholders above where available by their localized title. To simplify their usage, you can now only use the column names as mentioned above.
Column name | Title depending on localization1) as used in placeholder |
---|---|
%title% | @@Page@@ |
%pageid% | @@Page Name@@ |
%class% | @@Page Class@@ |
%lastmod% | @@Last Modified@@ |
Filter Form
The filter form adds new functionality to the data
and datatemplate
plugins. It can be used on pages where there is already a datatable
, datalist
or datatemplatelist
. An example of the syntax looks like this:
---- filterform ---- fields: Any, Title, Journal, Author, Volume, Page, Year, Abstract ----
The single parameter fields
is turned into a dropdown list when the page is rendered. Its value is a list of column names or headers that are present in the “cols” data parameter. There is the magic “Any” filter which permits to filter with all data displayed columns.
Next to the dropdown list is a text field. When the form is submitted, only those data entries are displayed, where the column selected in the dropdown box contains the text in the text field. This effectively corresponds to adding a line like filter: Title~*weather*
inside the source of e.g. the datatable
.
It is possible to add more and more filter criteria by repeatedly submitting the form. Also, applied filters can later be removed individually.
Demonstration
For a demonstration, see for instance the Publications page of the Group of Applied Physics at the University of Geneva. There, both the datatemplate list and the filter form can be seen in action. Each item in the list is a datatemplate entry (created by a separate plugin that accepts BibTeX as input).
The Members page is equally based on this plugin, the members are listed by datatemplatelist
and the member pages contains a datatemplateentry
.
As another example I am using this plugin on my personal website to provide a pretty index page for a collection of recipes and documents. (This was broken for a while after a Doku upgrade, but not that the plugin has been fixed it's working again). – Adam
A technical note about caching
The data plugins stores its data as simple key-value pairs in an SQLite database. While this leads to a lot of flexibility, there is a disadvantage when querying the data from the database. To obtain something that looks like a result from “normal” SQL tables, the data plugin tailors together a series of JOIN operations, which can be very time consuming. To give some numbers, a single request with about 300 result items, as is the case for the list of publications mentioned above, took several seconds to resolve. Even though this does not seem too bad, it quickly becomes frustrating, when filtering and page navigation lead to several such requests in a row.
A simple caching technique in the datatemplate list significantly speeds up page queries. This essentially works as follows:
- Validation: A simple query, without pagination and filters added via GET or POST, is performed, containing only the ids of the pages containing the data that is asked for. Since this query only involves a very limited number of JOIN operations, it is reasonably fast. The modification times of the files containing these pages are then checked, and if none of them is newer than the cache, the cache is assumed valid. A separate check removes cache entries corresponding to pages that no longer exist.
- Building: In the case that the cache needs to be rebuilt, the full query is performed. However, to avoid the creation of too many cache files, and that the same data is cached repeatedly, any filters added via GET or POST, as well as limits and offsets for pagination, are removed.
- Storage: The cache file is stores in the cache directory of DokuWiki. The filename is hash of the stripped down SQL query string.
One can force a rebuild of the cache by using the DokuWiki purge mechanism.
Shortcomings
In the current state, this plugin leaves room for improvements. Some of the currently known issues are
- The plugin is not able to detect circular dependencies in the rendering of templates.
- If a template contains relative links, these are not corrected.
The rendering of the templates is not cached.If the use of a template gives the first header of the page, the page title is not updated correspondingly.- There are some problems with the simultaneous use of the include plugin.
- Cache files that are no longer in use are not detected and deleted automatically.
However, there are no promises that these (or other) issues will be addressed in future releases.
Acknowledgements
First years, until 2016 august, of this plugin was released and maintained by Christoph Clausen.
This plugin was inspired by the dataloop plugin by Martyn Eggleton. Much of the template rendering code is based on the templater plugin by Jonathan Arkell.
Bugs, Feature Requests and Patches
Please submit bugs and feature requests in the issue tracker linked at the top.