DokuWiki

It's better when it's simple

User Tools

Site Tools


plugin:datatemplate

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
plugin:datatemplate [2018-03-01 05:16] – [Data Template Plugin] adamshandplugin:datatemplate [2022-12-06 11:59] (current) – [Data Template Plugin] Search for new maintainer(s) Cyrille37
Line 7: Line 7:
 type       : syntax type       : syntax
 lastupdate : 2016-08-03 lastupdate : 2016-08-03
-compatible : 2017-02-19 "Frusterick Manners", 2016-06-26 "Elenor Of Tsort", 2015-08-10 "Detritus", rincewindweatherwax+compatible : 2017-02-19 "Frusterick Manners", 2016-06-26 "Elenor Of Tsort", 2015-08-10 "Detritus", RincewindWeatherwax
 depends    : data, sqlite depends    : data, sqlite
 conflicts  conflicts 
Line 18: Line 18:
 donationurl:  donationurl: 
 ---- ----
 +
 +:?: :!: [[https://github.com/Cyrille37/dokuwiki-plugin-datatemplate/issues/16|Search for new maintainer(s)]]  :!: :?:
  
 This plugin adds the possibility to display the structured data of the [[data|Data Plugin]] using templates. Templates can be applied This plugin adds the possibility to display the structured data of the [[data|Data Plugin]] using templates. Templates can be applied
Line 26: Line 28:
 ===== Download and Installation ===== ===== Download and Installation =====
  
-Download and install the plugin using the [[plugin|Plugin Manager]] using the URL given above. Refer to [[:Plugins]] on how to install plugins manually.+Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually.
  
 ==== Change Log ==== ==== Change Log ====
Line 35: Line 37:
  
 Last github commits on release [[https://github.com/Cyrille37/dokuwiki-plugin-datatemplate/tree/2016-08-03|2016-08-03]]. Last github commits on release [[https://github.com/Cyrille37/dokuwiki-plugin-datatemplate/tree/2016-08-03|2016-08-03]].
 +
 {{rss>https://github.com/Cyrille37/dokuwiki-plugin-datatemplate/commits/2016-08-03.atom date}}  {{rss>https://github.com/Cyrille37/dokuwiki-plugin-datatemplate/commits/2016-08-03.atom date}} 
  
Line 41: Line 44:
 Templates are separate wiki pages containing placeholders. There are two kinds of placeholders: 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 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 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  --- [[user>mcgumbel|mcgumbel]] //2014-09-25 18:32//   * :!: Placeholders with capital letter do not work in the current version  --- [[user>mcgumbel|mcgumbel]] //2014-09-25 18:32//
  
Line 47: Line 50:
  
 A template definition as in A template definition as in
 +
 <code - tpl_member> <code - tpl_member>
 {{@@!imgname@@?nolink&200 }} {{@@!imgname@@?nolink&200 }}
Line 54: Line 58:
   * **E-Mail**: @@email@@   * **E-Mail**: @@email@@
 </code> </code>
 +
 OR OR
 +
 <code - tpl_memberlist> <code - tpl_memberlist>
 === @@%title%@@ === === @@%title%@@ ===
Line 62: Line 68:
 **E-Mail**: @@email@@ **E-Mail**: @@email@@
 </code> </code>
-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.+ 
 +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 ===== ===== Syntax =====
  
-This plugin provides **3** different syntax blocks: ''datatemplateentry''''datatemplatelist'' and ''filterform''The first two are essentially the same as for the data plugin, but with an added ''template'' parameter.+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 ==== ==== datatemplateentry ====
Line 72: Line 84:
 The ''datatemplateentry'' corresponds to the ''[[data#data_entry_(input)|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 ''datatemplateentry'' corresponds to the ''[[data#data_entry_(input)|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:+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: 
 <code> <code>
 ---- datatemplateentry member ---- ---- datatemplateentry member ----
Line 100: Line 113:
  
 ==== datatemplatelist ==== ==== datatemplatelist ====
 +
 The ''datatemplatelist'' corresponds to the ''[[data#data_list_(output)|datalist]]'' of the data plugin. Contrary to its "brother", the ''datatemplatelist'' also supports pagination. The ''datatemplatelist'' corresponds to the ''[[data#data_list_(output)|datalist]]'' of the data plugin. Contrary to its "brother", the ''datatemplatelist'' also supports pagination.
  
 Example syntax: Example syntax:
 +
 <code> <code>
 ---- datatemplatelist ---- ---- datatemplatelist ----
Line 113: Line 128:
 ---- ----
 </code> </code>
 +
 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. 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: 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  ^ ^Column name ^ Appearance^ Placeholder  ^
 | %title%   | The first headline of a page, which has a link to data entry page. | @@%title%@@   | | %title%   | The first headline of a page, which has a link to data entry page. | @@%title%@@   |
Line 125: Line 142:
  
 === Deprecated === === 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. 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.
  
Line 136: Line 154:
  
 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: 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:
 +
 <code> <code>
 ---- filterform ---- ---- filterform ----
Line 141: Line 160:
 ---- ----
 </code> </code>
 +
 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. 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.
  
Line 154: Line 174:
  
 As another example I am using this plugin on my personal website to provide a pretty index page for a collection of [[http://adam.nz/recipe|recipes]] and [[http://adam.nz/library|documents]]. (This was broken for a while after a Doku upgrade, but not that the plugin has been fixed it's working again). -- Adam As another example I am using this plugin on my personal website to provide a pretty index page for a collection of [[http://adam.nz/recipe|recipes]] and [[http://adam.nz/library|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 ===== ===== A technical note about caching =====
  
Line 163: Line 184:
   - **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.   - **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.   - **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.+  - **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 [[devel:caching#purging_the_cache|Dokuwiki purge mechanism]].+One can force a rebuild of the cache by using the [[devel:caching#purging_the_cache|DokuWiki purge mechanism]].
  
 ===== Shortcomings ===== ===== Shortcomings =====
 +
 In the current state, this plugin leaves room for improvements. Some of the currently known issues are 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.   * The plugin is not able to detect circular dependencies in the rendering of templates.
Line 187: Line 209:
  
 Please submit bugs and feature requests in the issue tracker linked at the top. Please submit bugs and feature requests in the issue tracker linked at the top.
- 
plugin/datatemplate.1519877795.txt.gz · Last modified: 2018-03-01 05:16 by adamshand

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
CC Attribution-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki