DokuWiki

It's better when it's simple

User Tools

Site Tools

Trace:
plugin:template

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:template [2009-10-07 00:08] – 82.237.128.230plugin:template [2019-09-10 20:05] (current) – Aleksandr
Line 2: Line 2:
  
 ---- plugin ---- ---- plugin ----
-description: Render a data set from a template.+description: Render a data set from a template
 author     : Spider Joe author     : Spider Joe
-email      : http://www.spiderjoe.com +email      :  
-type       : +type       : syntax
 lastupdate : 2005-09-09 lastupdate : 2005-09-09
 compatible :  compatible : 
Line 12: Line 12:
 similar    :  similar    : 
 tags       : extension, command, template tags       : extension, command, template
----- 
  
 +downloadurl: 
 +bugtracker : 
 +sourcerepo : 
 +donationurl: 
 +
 +screenshot_img: 
 +----
  
 ===== Overview ===== ===== Overview =====
  
-The **Template Command** renders a data set from a template. The data set is just a [[:DokuWiki]] page containing a series of lists representing records (<del>[[http://www.spiderjoe.com/spiders/calendar?do=edit|example]]</del>). The template is a PHP file in ''lib/tpl/'' that generates either HTML or DokuWiki [[:syntax]] for inclusion at the place of the template command (<del>[[http://www.spiderjoe.com/spiders/calendar|example]]</del>). The command is an extension of the [[plugin:command|Command Plugin]], requiring that plugin and implementing a command of that plugin.+The **Template Command** renders a data set from a template. The data set is just a DokuWiki page containing a series of lists representing records (<del>[[http://www.spiderjoe.com/spiders/calendar?do=edit|example]]</del>). The template is a PHP file in ''lib/tpl/'' that generates either HTML or DokuWiki [[:wiki:syntax]] for inclusion at the place of the template command (<del>[[http://www.spiderjoe.com/spiders/calendar|example]]</del>). The command is an extension of the [[plugin:command|Command Plugin]], requiring that plugin and implementing a command of that plugin.
  
 This command is useful for... This command is useful for...
  
-  * Representing data in [[:DokuWiki]] separately from its formatting.+  * Representing data in DokuWiki separately from its formatting.
   * Applying repetitive formatting to each of multiple data items.   * Applying repetitive formatting to each of multiple data items.
-  * Generating rich HTML for inclusion in a [[:DokuWiki]] page. +  * Generating rich HTML for inclusion in a DokuWiki page. 
-  * Expressing [[:DokuWiki]]-maintained data in rich HTML.+  * Expressing DokuWiki-maintained data in rich HTML.
  
-The command defines a kind of page called a //data page//. A data page is just a series of DokuWiki [[:syntax#lists|lists]] delimited by horizontal rules. Each list represents a record, and each item in a list represents a field of the record.+The command defines a kind of page called a //data page//. A data page is just a series of DokuWiki [[:wiki:syntax#lists|lists]] delimited by horizontal rules. Each list represents a record, and each item in a list represents a field of the record.
  
 A template command takes optional parameters, a template file name, and the name of a data page. Here are some example uses: A template command takes optional parameters, a template file name, and the name of a data page. Here are some example uses:
Line 39: Line 45:
 </code> </code>
  
-The parameters are handed to the template file, allowing for parametrized templates. The template file may produce either HTML or DokuWiki [[:syntax]] that is in turn translated to HTML --- which ever is easiest for the template writer.+The parameters are handed to the template file, allowing for parametrized templates. The template file may produce either HTML or DokuWiki [[:wiki:syntax]] that is in turn translated to HTML --- which ever is easiest for the template writer.
  
 Here are two demo pages that are generated by this command: Here are two demo pages that are generated by this command:
Line 102: Line 108:
 ===== Data Page Format ===== ===== Data Page Format =====
  
-A data page is a page that represents a set of records. Each record is a DokuWiki [[:syntax#lists|list]], and each item of the list provides a field of the record. Multiple records are delimited with the horizontal rule, denoted in the DokuWiki [[:syntax]] by "''%%----%%''".+A data page is a page that represents a set of records. Each record is a DokuWiki [[:wiki:syntax#lists|list]], and each item of the list provides a field of the record. Multiple records are delimited with the horizontal rule, denoted in the DokuWiki [[:wiki:syntax]] by "''%%----%%''".
  
 Here is an example data page: Here is an example data page:
Line 157: Line 163:
 Text that appears before the first list item of a record is ignored and may be used to comment the page or the record. Note that DokuWiki needs a blank line before each horizontal rule. Records not containing any list items are ignored and are not handed to the template. This happens when two horizontal rules appear back-to-back or when one appears at the start or end of the file. Text that appears before the first list item of a record is ignored and may be used to comment the page or the record. Note that DokuWiki needs a blank line before each horizontal rule. Records not containing any list items are ignored and are not handed to the template. This happens when two horizontal rules appear back-to-back or when one appears at the start or end of the file.
  
-Note that the ''field_value'' and ''multi_para_value'' representations need not be equivalent. In an HTML template, each paragraph of a ''multi_para_value'' is wrapped in <p> tags, while in a DokuWiki [[:syntax]] template, there are no <p> tags, but any blank lines present will be included.+Note that the ''field_value'' and ''multi_para_value'' representations need not be equivalent. In an HTML template, each paragraph of a ''multi_para_value'' is wrapped in <p> tags, while in a DokuWiki [[:wiki:syntax]] template, there are no <p> tags, but any blank lines present will be included.
  
 Whitespace preceding or trailing each ''field_value'' or ''multi_field_value'' is trimmed and so is not significant. Whitespace preceding or trailing each ''field_value'' or ''multi_field_value'' is trimmed and so is not significant.
Line 163: Line 169:
 ===== Template Files ====== ===== Template Files ======
  
-A template file is a file that uses PHP to generate HTML or DokuWiki [[:syntax]] from a data set. The file is placed in the active ''lib/tpl/'' directory or in some subdirectory thereof. (The default active template directory is ''lib/tpl/default/''.)+A template file is a file that uses PHP to generate HTML or DokuWiki [[:wiki:syntax]] from a data set. The file is placed in the active ''lib/tpl/'' directory or in some subdirectory thereof. (The default active template directory is ''lib/tpl/default/''.)
  
 How a template file works can be summarized in a few points: How a template file works can be summarized in a few points:
  
-  - Think of the file as a regular HTML or DokuWiki [[:syntax]] file that may contain embedded PHP. Everything outside of the PHP tags and all output echoed by PHP becomes part of the generated result.+  - Think of the file as a regular HTML or DokuWiki [[:wiki:syntax]] file that may contain embedded PHP. Everything outside of the PHP tags and all output echoed by PHP becomes part of the generated result.
   - The PHP in the file runs within an outer, invisible PHP function. All this means is that you must declare any globals you want to use.   - The PHP in the file runs within an outer, invisible PHP function. All this means is that you must declare any globals you want to use.
   - The ''$TEMPLATECOMMAND_SOURCE'' variable is available to the PHP code. This variable contains an object from which the code gets its source data.   - The ''$TEMPLATECOMMAND_SOURCE'' variable is available to the PHP code. This variable contains an object from which the code gets its source data.
Line 174: Line 180:
  
   * ''getParamHash()'' --- Returns an associative array of all the parameters that the user provided to the template command. The [[plugin:command|Command Plugin]] allows parameters to be assigned via an "''=''". When a parameter is so assigned, the value to the left of the "''=''" is a key of the array, and the value to the right is the value at that key. When a parameter is included without an "''=''", the parameter provided becomes the key and the value at that key is the empty string. For example, "''#template?1&1&2&a&b=&c=3&d=4&d=5(format.php|data)#''" produces array('1'=>'', '2'=>'', 'a'=>'', 'b'=>'', 'c'=>'3', 'd'=>'5').   * ''getParamHash()'' --- Returns an associative array of all the parameters that the user provided to the template command. The [[plugin:command|Command Plugin]] allows parameters to be assigned via an "''=''". When a parameter is so assigned, the value to the left of the "''=''" is a key of the array, and the value to the right is the value at that key. When a parameter is included without an "''=''", the parameter provided becomes the key and the value at that key is the empty string. For example, "''#template?1&1&2&a&b=&c=3&d=4&d=5(format.php|data)#''" produces array('1'=>'', '2'=>'', 'a'=>'', 'b'=>'', 'c'=>'3', 'd'=>'5').
-  * ''getTextRecords()'' --- Returns an array of records, ordered according to their order of appearance within the data page. Each record is an associative array mapping the ''field_name'' to its ''field_value'' or ''multi_para_value''. The field values will be the raw text that appears within the data page, as seen when editing the data page; DokuWiki [[:syntax]] will not have been translated to HTML. Calling this method informs the template command that the template is generating DokuWiki [[:syntax]]. The command will subsequently translate it to HTML. +  * ''getTextRecords()'' --- Returns an array of records, ordered according to their order of appearance within the data page. Each record is an associative array mapping the ''field_name'' to its ''field_value'' or ''multi_para_value''. The field values will be the raw text that appears within the data page, as seen when editing the data page; DokuWiki [[:wiki:syntax]] will not have been translated to HTML. Calling this method informs the template command that the template is generating DokuWiki [[:wiki:syntax]]. The command will subsequently translate it to HTML. 
-  * ''getHtmlRecords()'' --- Returns an array of records, ordered according to their order of appearance within the data page. Each record is an associative array mapping the ''field_name'' to its ''field_value'' or ''multi_para_value''. The field values will already have their DokuWiki [[:syntax]] translated to HTML. Calling this method informs the template command that the template is generating the HTML to be displayed.+  * ''getHtmlRecords()'' --- Returns an array of records, ordered according to their order of appearance within the data page. Each record is an associative array mapping the ''field_name'' to its ''field_value'' or ''multi_para_value''. The field values will already have their DokuWiki [[:wiki:syntax]] translated to HTML. Calling this method informs the template command that the template is generating the HTML to be displayed.
  
 All field values are reported with preceding and trailing whitespace trimmed. Note that in records retrieved via ''getHtmlRecords()'', each paragraph of a ''multi_para_value'' field value will be wrapped in <p> tags, as we expect DokuWiki to do. All field values are reported with preceding and trailing whitespace trimmed. Note that in records retrieved via ''getHtmlRecords()'', each paragraph of a ''multi_para_value'' field value will be wrapped in <p> tags, as we expect DokuWiki to do.
Line 181: Line 187:
 ===== Source (template.php) ===== ===== Source (template.php) =====
  
-<code php><?php+<file php template.php> 
 +<?php
 /** /**
  * Template Command: Render a data set from a template.  * Template Command: Render a data set from a template.
Line 602: Line 609:
     }     }
 } }
-?></code>+?> 
 +</file>
  
 ===== Examples ===== ===== Examples =====
  
-Bear in mind that, although the following examples generate HTML, the template file may instead generate DokuWiki [[:syntax]] by calling ''$TEMPLATECOMMAND_SOURCE->getTextRecords()'' instead of ''$TEMPLATECOMMAND_SOURCE->getHtmlRecords()''. I just don't have a live example to show you. You might want to generate DokuWiki syntax if it's easier than generating the HTML, as it usually will be. Also, these examples used to use a separate data page. I have since moved the data directly into the command using the new '%%...%%' syntax.+Bear in mind that, although the following examples generate HTML, the template file may instead generate DokuWiki [[:wiki:syntax]] by calling ''$TEMPLATECOMMAND_SOURCE->getTextRecords()'' instead of ''$TEMPLATECOMMAND_SOURCE->getHtmlRecords()''. I just don't have a live example to show you. You might want to generate DokuWiki syntax if it's easier than generating the HTML, as it usually will be. Also, these examples used to use a separate data page. I have since moved the data directly into the command using the new '%%...%%' syntax.
    
  
Line 690: Line 698:
     $side = ($side == 'left') ? 'right' : 'left';     $side = ($side == 'left') ? 'right' : 'left';
 } }
-?></code>+?> 
 +</code>
  
 > Note that the JavaScript function "svchk()" no longer exists (and is now unnecessary) in DokuWiki, and does cause JavaScript errors, so references should be removed. > Note that the JavaScript function "svchk()" no longer exists (and is now unnecessary) in DokuWiki, and does cause JavaScript errors, so references should be removed.
Line 697: Line 706:
 ===== Discussion ===== ===== Discussion =====
  
-  * The template command allows the user to name any file in the [[:DokuWiki]] ''%%lib/tpl/%%'' templates directory. The command specifically does not allow the filename to include '%%..%%', but there are no other constraints. Is there a potential security problem I need to handle? Thanks!  --- [[http://www.spiderjoe.com|Spider Joe]]+  * The template command allows the user to name any file in the DokuWiki ''%%lib/tpl/%%'' templates directory. The command specifically does not allow the filename to include '%%..%%', but there are no other constraints. Is there a potential security problem I need to handle? Thanks!  --- [[http://www.spiderjoe.com|Spider Joe]]
  
   * The example links (http://www.spiderjoe.com/spiders/calendar) do not work. -- [[wonko@wonkology.org|Wonko]] 2006-07-01   * The example links (http://www.spiderjoe.com/spiders/calendar) do not work. -- [[wonko@wonkology.org|Wonko]] 2006-07-01
  
-  * <del>[[:DokuWiki]] syntax is not processed if I simple make the template ''echo'' it. Please give an example. Thanks!</del>. Ok, I read more carefully and found that it depended in which function was called to get the records. I modified the page a bit to make it more explicitly to those of us who just skim through the instructions :D. 2006-09-05+  * <del>DokuWiki syntax is not processed if I simple make the template ''echo'' it. Please give an example. Thanks!</del>. Ok, I read more carefully and found that it depended in which function was called to get the records. I modified the page a bit to make it more explicitly to those of us who just skim through the instructions :D. 2006-09-05
  
-  * First, thanks for this plugin :) . I encountered some problems using this plugin with the [[http://www.dokuwiki.org/plugin:tag|tag plugin]]. Details : i used the "getTextRecords" function to generate a DokuWiki code. Within my php code when i echo the following statement : <code>"{{tag>foo bar}}"</code> statement (cf tag plugin page for more info about it). The render is correct (i.e. the tags are displayed under an horizontal line as expected) but the problem is that the page is not associated with the tags. For example when I click on the tag the page are not listed as a tagged page, even after a rebuild index of tags (via tag plugin manager menu)... any idea? How could i generate dynamic tags?+  * First, thanks for this plugin :) . I encountered some problems using this plugin with the [[plugin:tag|tag plugin]]. Details : i used the "getTextRecords" function to generate a DokuWiki code. Within my php code when i echo the following statement : <code>"{{tag>foo bar}}"</code> statement (cf tag plugin page for more info about it). The render is correct (i.e. the tags are displayed under an horizontal line as expected) but the problem is that the page is not associated with the tags. For example when I click on the tag the page are not listed as a tagged page, even after a rebuild index of tags (via tag plugin manager menu)... any idea? How could i generate dynamic tags?
  
 ===PHP error=== ===PHP error===
plugin/template.1254866905.txt.gz · Last modified: 2009-10-07 00:08 by 82.237.128.230
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

Global DokuWiki Links