summaryrefslogtreecommitdiff
path: root/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn
diff options
context:
space:
mode:
Diffstat (limited to 'doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn')
-rw-r--r--doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn106
1 files changed, 106 insertions, 0 deletions
diff --git a/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn b/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn
new file mode 100644
index 000000000..3009fc830
--- /dev/null
+++ b/doc/plugins/contrib/ftemplate/ikiwiki/directive/ftemplate.mdwn
@@ -0,0 +1,106 @@
+The `ftemplate` directive is supplied by the [[!iki plugins/contrib/ftemplate desc=ftemplate]] plugin.
+
+This is like the [[ikiwiki/directive/template]] directive, with the addition
+that one does not have to provide all the values in the call to the template,
+because ftemplate can query structured data ("fields") using the
+[[plugins/contrib/field]] plugin.
+
+Templates are files that can be filled out and inserted into pages in
+the wiki, by using the ftemplate directive. The directive has an id
+parameter that identifies the template to use.
+
+Additional parameters can be used to fill out the template, in
+addition to the "field" values. Passed-in values override the
+"field" values.
+
+There are two places where template files can live. One is in the /templates
+directory on the wiki. These templates are wiki pages, and can be edited from
+the web like other wiki pages.
+
+The second place where template files can live is in the global
+templates directory (the same place where the page.tmpl template lives).
+This is a useful place to put template files if you want to prevent
+them being edited from the web, and you don't want to have to make
+them work as wiki pages.
+
+### EXAMPLES
+
+#### Example 1
+
+PageA:
+
+ \[[!meta title="I Am Page A"]]
+ \[[!meta description="A is for Apple."]]
+ \[[!meta author="Fred Nurk"]]
+ \[[!ftemplate id="mytemplate"]]
+
+Template "mytemplate":
+
+ # <TMPL_VAR NAME="TITLE">
+ by <TMPL_VAR NAME="AUTHOR">
+
+ **Summary:** <TMPL_VAR NAME="DESCRIPTION">
+
+This will give:
+
+ <h1>I Am Page A</h1>
+ <p>by Fred Nurk</p>
+ <p><strong>Summary:</strong> A is for Apple.
+
+#### Example 2: Overriding values
+
+PageB:
+
+ \[[!meta title="I Am Page B"]]
+ \[[!meta description="B is for Banana."]]
+ \[[!meta author="Fred Nurk"]]
+ \[[!ftemplate id="mytemplate" title="Bananananananas"]]
+
+This will give:
+
+ <h1>Bananananananas</h1>
+ <p>by Fred Nurk</p>
+ <p><strong>Summary:</strong> B is for Banana.
+
+#### Example 3: Loops
+
+(this example uses the [[plugins/contrib/ymlfront]] plugin)
+
+Page C:
+
+ ---
+ BookAuthor: Georgette Heyer
+ BookTitle: Black Sheep
+ BookGenre:
+ - Historical
+ - Romance
+ ---
+ \[[ftemplate id="footemplate"]]
+
+ I like this book.
+
+Template "footemplate":
+
+ # <TMPL_VAR BOOKTITLE>
+ by <TMPL_VAR BOOKAUTHOR>
+
+ <TMPL_IF BOOKGENRE>(
+ <TMPL_LOOP GENRE_LOOP><TMPL_VAR BOOKGENRE>
+ <TMPL_UNLESS __last__>, </TMPL_UNLESS>
+ </TMPL_LOOP>
+ )</TMPL_IF>
+
+This will give:
+
+ <h1>Black Sheep</h1>
+ <p>by Georgette Heyer</p>
+
+ <p>(Historical, Romance)</p>
+
+ <p>I like this book.</p>
+
+### LIMITATIONS
+
+One cannot query the values of fields on pages other than the current
+page. If you want to do that, check out the [[plugins/contrib/report]]
+plugin.