Templatery

This dokuwiki plugin is no longer maintained. Due to time constraints and no longer using this plugin myself, I can no longer properly maintain it.

A try at a dokuwiki template plugin. The templatery plugin offers the ability to write a template, and have it included in other pages with filled in fields.

This plugin is different from other template plugins in that it does not modify the dokuwiki source. Instead, it offers special syntax to handle field replacements. This allows faster processing at the expense of flexibility.

The lost flexibility can be regained by using custom template handlers.

Example

The anatomy of a template

Defining a template is done by wrapping normal dokuwiki syntax in <template> tags. For example, a simple template will end up looking like this:

<template example>
Hello, my name is: @@Name@@

<if organisation>
I'm a member of @@Organisation@@.
</if>
</template>

For now, let's assume that we have put this template on a dokuwiki page called template:demo.

Dissecting this template, we get the following parts:

<template example>

This starts a new template. The template can optionally have an identifier (example in this case), these identifiers are used when you define multiple templates on a single page.

Hello, my name is: @@name@@

A piece of text with a field called name; the @@name@@ part will be replaced by the value of the name field when the template is filled with data. Anything between @@s is seen as a field by templatery.

<if organisation>
I'm a member of @@organisation@@.
</if>

A conditional piece of text. If the field organisation is present, the part inside the <if> will be displayed. If the field is not defined, everything inside the <if> tags will be left out.

Closes the template.

Using the template

You can put a template invocation — the use of a template together with some values — on a page with:

{{template>demo|name=Yoda|organisation=the Jedi}}

This tells the wiki to use the template demo, with the values name = Yoda and organisation = Jedi.

To determine the exact template, templatery always looks up your template in the template namespace, so demo is actually seen as template:demo by the templatery plugin. If you give a full page name such as user:yoda:mydemo (i.e. {{template>user:yoda:mydemo|...}}), than that template is used. Even better — if you have multiple templates defined on one page, you can call out which specific template you want to use like demo#example. This will use the example template from the demo page. If you leave out the specific template identifier, templatery will default to using the first template. Putting this all together, the above example is the same as {{template>template:demo#example|name=Yoda|organisation=the Jedi}}.

On a dokuwiki, this will produce:

Hello, my name is: Yoda

I'm a member of the Jedi.

Note, that you are free to use newlines inside the template use:

{{template>demo
|name=Yoda
|organisation=the Jedi
}}

This makes it a little easier to read templates invocation are they are written.

Using parameters

A template can have both named and numbered parameters.

Numbered parameters

Parameters can be numbered:

<template numbered>
0 = @@0@@, 1 = @@1@@
</template>

To pass numbered parameters to a template simply omit the fields:

{{template>demo#numbered
|Alpha
|beta
}}

You can freely mix numbered and named parameters.

Default values

Fields in the template can be given default values:

<template defaults>
@@a|Default value for a@@  & @@B|Default value for b@@
</template>

Place the default value after a | symbol, if the field is not given, the default value will be used.

{{template>demo#defaults
|a=Alpha
}}

Will produce:

Alpha & Default value for b

Conditionals

You can have conditional pieces of template:

<template conditionals>
<if A>
Text if A is set. A = @@a@@ 
</if>
<if !A>
Text if A is **not** set.
</if>
</template>

Now, depending on whether the field A is available, the template will either display the value of A, or a notice that it is not available.

Inline Conditionals

Conditionals will be block-level — that is they will create their own paragraph — if possible and will switch to inline if necessary because they are in a list or table..

This is useful, for example, if you have them in a list:

<template inlineconditionals>
  * Test with <if A>@@A@@</if>
</template>

You can force a conditional to be inline by prefixing it with a *.

<template inlineconditionals2>
Some <*if B>//@@B@@//</if><*if !B>tea</if> please.
</template>

In this case, templatery will treat the conditional as part of the paragraph.

Templates in Templates

You can invoke a template inside a template. This allows you to reuse templates as components of larger templates.

You can even pass on fields to the included template. To do so, you use {{template>name of template|inside field=outside field}}. Any field not mentioned is available in the included template under it's old name.

For example:

<template recursion>
@@0@@<*if 1>, and</if>
<if 1>
{{template>demo#recursion
|0=1
|1=2
|2=3
|3=4
}}
</if>
</template>

Defines a template that will loop over the fields it is given to display them one after the other. You can use it like this:

{{template>demo#recursion
|Alpha
|Beta
|Gamma
}}

And it will produce:

Alpha, and

Beta, and

Gamma