doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn

   1 The `ftemplate` directive is supplied by the [[!iki plugins/contrib/ftemplate desc=ftemplate]] plugin.
   2
   3 This is like the [[ikiwiki/directive/template]] directive, with the addition
   4 that one does not have to provide all the values in the call to the template,
   5 because ftemplate can query structured data ("fields") using the
   6 [[plugins/contrib/field]] plugin.
   7
   8 Templates are files that can be filled out and inserted into pages in
   9 the wiki, by using the ftemplate directive. The directive has an id
  10 parameter that identifies the template to use.
  11
  12 Additional parameters can be used to fill out the template, in
  13 addition to the "field" values.  Passed-in values override the
  14 "field" values.
  15
  16 There are two places where template files can live.  One is in the /templates
  17 directory on the wiki.  These templates are wiki pages, and can be edited from
  18 the web like other wiki pages.
  19
  20 The second place where template files can live is in the global
  21 templates directory (the same place where the page.tmpl template lives).
  22 This is a useful place to put template files if you want to prevent
  23 them being edited from the web, and you don't want to have to make
  24 them work as wiki pages.
  25
  26 ### EXAMPLES
  27
  28 #### Example 1
  29
  30 PageA:
  31
  32     \[[!meta title="I Am Page A"]]
  33     \[[!meta description="A is for Apple."]]
  34     \[[!meta author="Fred Nurk"]]
  35     \[[!ftemplate id="mytemplate"]]
  36
  37 Template "mytemplate":
  38
  39     # <TMPL_VAR NAME="TITLE">
  40     by <TMPL_VAR NAME="AUTHOR">
  41
  42     **Summary:** <TMPL_VAR NAME="DESCRIPTION">
  43
  44 This will give:
  45
  46     <h1>I Am Page A</h1>
  47     <p>by Fred Nurk</p>
  48     <p><strong>Summary:</strong> A is for Apple.
  49
  50 #### Example 2: Overriding values
  51
  52 PageB:
  53
  54     \[[!meta title="I Am Page B"]]
  55     \[[!meta description="B is for Banana."]]
  56     \[[!meta author="Fred Nurk"]]
  57     \[[!ftemplate id="mytemplate" title="Bananananananas"]]
  58
  59 This will give:
  60
  61     <h1>Bananananananas</h1>
  62     <p>by Fred Nurk</p>
  63     <p><strong>Summary:</strong> B is for Banana.
  64
  65 #### Example 3: Loops
  66
  67 (this example uses the [[plugins/contrib/ymlfront]] plugin)
  68
  69 Page C:
  70
  71     ---
  72     BookAuthor: Georgette Heyer
  73     BookTitle: Black Sheep
  74     BookGenre:
  75       - Historical
  76       - Romance
  77     ---
  78     \[[ftemplate id="footemplate"]]
  79
  80     I like this book.
  81
  82 Template "footemplate":
  83
  84     # <TMPL_VAR BOOKTITLE>
  85     by <TMPL_VAR BOOKAUTHOR>
  86
  87     <TMPL_IF BOOKGENRE>(
  88     <TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE>
  89     <TMPL_UNLESS __last__>, </TMPL_UNLESS>
  90     </TMPL_LOOP>
  91     )</TMPL_IF>
  92
  93 This will give:
  94
  95     <h1>Black Sheep</h1>
  96     <p>by Georgette Heyer</p>
  97
  98     <p>(Historical, Romance)</p>
  99
 100     <p>I like this book.</p>
 101
 102 ### LIMITATIONS
 103
 104 One cannot query the values of fields on pages other than the current
 105 page.  If you want to do that, check out the [[plugins/contrib/report]]
 106 plugin.