doc/plugins/contrib/ftemplate.mdwn

   1 [[!template id=plugin name=ftemplate author="[[rubykat]]"]]
   2 [[!tag type/meta type/format]]
   3 [[!toc]]
   4 ## NAME
   5
   6 IkiWiki::Plugin::ftemplate - field-aware structured template plugin
   7
   8 ## SYNOPSIS
   9
  10     # activate the plugin
  11     add_plugins => [qw{goodstuff ftemplate ....}],
  12
  13 ## DESCRIPTION
  14
  15 This plugin provides the **ftemplate** directive.  This is like
  16 the [[ikiwiki/directive/template]] directive, with the addition that one does not
  17 have to provide all the values in the call to the template,
  18 because ftemplate can query structured data ("fields") using
  19 the [[field]] plugin.
  20
  21 Templates are files that can be filled out and inserted into pages in
  22 the wiki, by using the ftemplate directive. The directive has an id
  23 parameter that identifies the template to use.
  24
  25 Additional parameters can be used to fill out the template, in
  26 addition to the "field" values.  Passed-in values override the
  27 "field" values.
  28
  29 There are two places where template files can live.  One is, as with the
  30 [[plugins/template]] plugin, in the /templates directory on the wiki.  These
  31 templates are wiki pages, and can be edited from the web like other wiki
  32 pages.
  33
  34 The second place where template files can live is in the global
  35 templates directory (the same place where the page.tmpl template lives).
  36 This is a useful place to put template files if you want to prevent
  37 them being edited from the web, and you don't want to have to make
  38 them work as wiki pages.
  39
  40 ### EXAMPLES
  41
  42 #### Example 1
  43
  44 PageA:
  45
  46     [[!meta title="I Am Page A"]]
  47     [[!meta description="A is for Apple."]]
  48     [[!meta author="Fred Nurk"]]
  49     [[!ftemplate id="mytemplate"]]
  50
  51 Template "mytemplate":
  52
  53     # <TMPL_VAR NAME="TITLE">
  54     by <TMPL_VAR NAME="AUTHOR">
  55
  56     **Summary:** <TMPL_VAR NAME="DESCRIPTION">
  57
  58 This will give:
  59
  60     <h1>I Am Page A</h1>
  61     <p>by Fred Nurk</p>
  62     <p><strong>Summary:</strong> A is for Apple.
  63
  64 #### Example 2: Overriding values
  65
  66 PageB:
  67
  68     [[!meta title="I Am Page B"]]
  69     [[!meta description="B is for Banana."]]
  70     [[!meta author="Fred Nurk"]]
  71     [[!ftemplate id="mytemplate" title="Bananananananas"]]
  72
  73 This will give:
  74
  75     <h1>Bananananananas</h1>
  76     <p>by Fred Nurk</p>
  77     <p><strong>Summary:</strong> B is for Banana.
  78
  79 ### LIMITATIONS
  80
  81 One cannot query the values of fields on pages other than the current
  82 page.
  83
  84 ## PREREQUISITES
  85
  86     IkiWiki
  87     IkiWiki::Plugin::field
  88     HTML::Template
  89     Encode
  90
  91 ## DOWNLOAD
  92
  93 * browse at GitHub: <http://github.com/rubykat/ikiplugins/blob/master/IkiWiki/Plugin/ftemplate.pm>
  94 * git repo at git://github.com/rubykat/ikiplugins.git