====== Namespace Templates ======

Sometime you might want to have every page in a certain namespace based on a common skeleton. For example, in the ''address'' namespace you could have an already prepared table, which only needs to be filled with data. This can be easily achieved with so called "namespace templates". 

When a page is created, [[DokuWiki]] looks up whether a template files exists and it shows it within the editor window. The templates therefore are .txt files and should contain wiki markup.

===== Template files =====
Two kinds of template files can be used :

  * ''_template.txt'', which are used in the current namespace.
  * ''%%__%%template.txt'' (two leading underscores), which work as the normal ''_template.txt'' files apart from the fact they are used in all namespaces below as well (they are inherited).

One way to create the template file is to

  * use the wiki to save a page with the content that you want to use as a template into the appropriate namespace
  * use FTP or WebDAV to make a copy of it in the same folder and rename it, then
  * use the wiki to delete the original page.((These changes only apply to new pages that you create in the namespace.))

===== Syntax =====
The content of the file is just standard [[syntax|wiki markup]].

==== Replacement patterns ====
Inside of the file, you may also use some replacement patterns to make the template a little more dynamic.

^ @ID@     | full ID of the page                                                                    |
^ @NS@     | namespace of the page                                                                  |
^ @PAGE@   | page name (ID without namespace and underscores replaced by spaces)                    |
^ @!PAGE@  | same as above but with the first character uppercased                                  |
^ @!!PAGE@ | same as above but with the first character of all words uppercased                     |
^ @!PAGE!@ | same as above but with all characters uppercased                                       |
^ @FILE@   | page name (ID without namespace, underscores kept as is)                               |
^ @!FILE@  | same as above but with the first character uppercased                                  |
^ @!FILE!@ | same as above but with all characters uppercased                                       |
^ @USER@   | ID of user who is creating the page                                                    |
^ @NAME@   | name of user who is creating the page                                                  |
^ @MAIL@   | mail address of user who is creating the page                                          |
^ @DATE@   | date and time when edit session started                                                |

In addition you may also use any [[phpfn>strftime]] placeholder to insert the time of page creation in any format you like. If you want to use a literal ''%'' character in your template you need to double it.

===== Editing templates =====

You can't edit the ''_template.txt'' through DokuWiki -- only someone who can edit the files inside the DokuWiki folders (usually an administrator using FTP or WebDAV) can. There are two tricks to accomplish this, though: one involving setting up symbolic links once, and one involving a code change.

==== Editable templates through symbolic links ====

This way, you can store your templates in a special namespace. By making a symlink to them you can use the template. You can also choose to make a template non-editable by not using a symlink.

  - Create a namespace called "templates", or something similar.
  - In this namespace, create a page for each [[:namespace_templates | Namespace Template]] that you wish to be available.
  - Follow the instructions given above, but make _template.txt a hard link ((soft links seem not to work, but see the note about FollowSymLinks below)) to the correct page under your templates namespace.  You now have a template that can be modified easily via the wiki interface.

>> I've used another method, creating a ''template.txt'' which is a symbolic link to the ''_template.txt'', in it's own namespace 
>> (''%% cd /var/www/html/dokuwiki/data/pages/namespace/something ; ln -s _template.txt template.txt%%'' ). 
>> This way I can edit the template by going to some page in the namespace and then replace the pagename by 'template' in the URL. 
>> (i.e. ''%%http://www.mywiki.somewhere/dokuwiki/doku.php?id=namespace:something:template%%'' )
>>
>> So this way you can use softlinks, but somewhat differently :)
\\ 
> For softlinks the webserver probably needs the FollowSymLinks option set on the directory(tree).
\\
==== Editable templates for all users  ====

This way, all your templates will be editable by anybody with write access.

  - Change the default template name to "template.txt" (or aaa_template.txt) at around line 817 ''inc/common.php'' ((Lines 811 and 812 in version 2009-02-14)). 
  - Now any user with write access in the namespace can create a page called "template" in that namespace which will serve as the template.
  * Note: This method has the advantage that new templates will immediately be recognized. This may not be the case with the other methods (adding files or symlinks manually into the DokuWiki folders).

==== @GROUPS@ support ====
It may be interesting to have support for the ''@GROUPS@'' keyword to extend to the group list of the user creating the page (e.g. to specify a set of tags on a user's home page). The following patch implements it.

<code unidiff>
Index: dokuwiki-2009-02-14/inc/common.php
===================================================================
--- dokuwiki-2009-02-14.orig/inc/common.php    2009-11-19 11:58:41.000000000 +0100
+++ dokuwiki-2009-02-14/inc/common.php 2010-01-05 10:17:35.000000000 +0100
@@ -840,6 +840,7 @@
                         '@USER@',
                         '@NAME@',
                         '@MAIL@',
+                        '@GROUPS@',
                         '@DATE@',
                      ),
                      array(
@@ -855,6 +856,7 @@
                         $_SERVER['REMOTE_USER'],
                         $INFO['userinfo']['name'],
                         $INFO['userinfo']['mail'],
+                        implode(" ", $INFO['userinfo']['grps']),
                         $conf['dformat'],
                      ), $tpl);
 

</code>

 --- //[[shtrom-doku@ssji.net|Olivier Mehani]] 2010/01/05 10:19//

====== Suggestions ======

  * Maybe setting the default template pagename in the config prevents messing with common.php, which will break the hack when an update is performed. With ACL access to these template files can be restricted.
  * It would be useful to have templates for special page names. For example <nowiki>__index.txt</nowiki> would be the template for alle pages called "index" in the whole namespace. Would be useless with one underline, since there can only be one page per name in a single namespace.
    * I was inspired by this suggestion (and also annoyed at creating a lot of pages that had the same formatting) so I did some editing. http://pastebin.com/YHGk6T4F That is the common.php I run that searches parent namespaces for a template named after the current page. If it doesn't find one, it looks for <nowiki>_template.txt</nowiki> then <nowiki>__template.txt</nowiki> as the main branch currently does.  --- [[user>serenewaffles|serenewaffles]] //2012/01/29 19:01//
  * To avoid naming conflicts, a different template name system should help: template.tpl for the current namespace, template.rtpl for all namespaces below (//recursive template//)