This page describes the format of the skin template files (.tmpl) that are used to create PmWiki skins. As described in the skins page, a skin is a collection of files that specifies the layout for PmWiki pages. Each skin must include a template file that provides the skeleton for displaying a PmWiki page.
A template file is basically an HTML file that also contains variable substitutions (indicated by '$') and special directives embedded in HTML comments. Two special directives are required in the template file. The directive <!--PageText--> belongs to the <body> section of the HTML document, and tells PmWiki where the main content of each wiki page should be placed. The other required directive is <!--HeaderText-->, which goes somewhere in the <head> section of the HTML document (usually near the top).
When PmWiki displays a page, it replaces the directives and variable substitutions with the values appropriate to the current page. For example, the <!--PageText--> directive is replaced with the page's contents, while any instances of $PageUrl are replaced with the url (address) of the current page.
There is a long list of variables available for substitution in pages; some of the most useful include:
$PageUrl the url of the current page
$ScriptUrl the base url to the pmwiki.php script
$Title the page's title (e.g., "`SkinTemplates")
$Titlespaced the page's title with spaces (e.g., "Skin Templates")
$Group the name of the current group (e.g., "`PmWiki")
$FullName the page's full name (e.g., "`PmWiki.SkinTemplates")
$LastModified the page's last modification time
$PageLogoUrl the url of a site logo
$WikiTitle the site's title
$SkinDirUrl the url of the skin's folder
This last variable, $SkinDirUrl, is particularly useful in templates as it allows the skin designer to refer to other files (such as images or style sheets) in the skin folder without having to know the exact url.
The template is not limited to using the variables listed here; nearly any PHP global variable that begins with a capital letter can be used in a skin template.
Besides the required <!--PageText--> and <!--HeaderText--> directives, PmWiki provides other built-in directives for generating page output. It's not necessary to use any of these directives, but they can often add capabilities to a skin
<!--wiki:Main.SomePage--><!--wiki:Main.SomePage--> directive outputs the contents of Main.SomePage. $-substitutions are allowed in directives, thus a directive like <!--wiki:$Group.SomePage--> will include "SomePage" of the current group.
<!--wiki:$Group.SomePage Site.SomePage--> will display the contents of SomePage in the current group if it exists, and Site.SomePage if it doesn't. To always display Site.SomePage, even if $`Group.SomePage exists, use two consecutive <!--wiki:...--> directives.
<!--file:somefile.txt--><!--file:somefile.txt--> outputs the contents of another file (on the local filesystem) at the point of the directive. If the file to be included is a .php script, then the PHP script is executed and its output is sent to the browser. Like the <!--wiki:...--> directive above, $-substitutions are available to be able to output files based on the current page name or group.
<!--markup:...--><!--function:SomeFunction args-->A template file can designate "sections" that are included or excluded from the output based on page directives or other criteria. A section always begins with <!--Page...Fmt--> and continues to the next section, the end of the template file, or <!--/Page...Fmt-->. For example, a template can specify a <!--PageLeftFmt--> section that is excluded from the output whenever the (:noleft:) directive is encountered in the page's contents. PmWiki's predefined sections (and their corresponding page directives) are:
<!--PageHeaderFmt--> (:noheader:)
<!--PageFooterFmt--> (:nofooter:)
<!--PageTitleFmt--> (:notitle:)
<!--PageLeftFmt--> (:noleft:)
<!--PageRightFmt--> (:noright:)
Skin designers can define custom sections and markups, but currently all section names in the template must begin with "Page" and end with "Fmt".
Skins can also be internationalized by using $[...] substitutions. Any string placed inside of $[...] is treated as a "translatable phrase", and the phrase is looked up in the current translation tables for a corresponding output phrase. If a translation is available, then the translated phrase is substituted at that point, otherwise the original phrase is left intact.
For example, the substitution $[Edit] will display the current translation of "Edit" if it is known, otherwise it displays "Edit". Thus, the same template can be used for multiple languages, displaying "Editer" when French translations are loaded, "Bearbeiten" when German translations are loaded, and "Edit" when no translation is available.
<< | DocumentationIndex | >>
This page may have a more recent version on pmwiki.org: PmWiki:SkinTemplates, and a talk page: PmWiki:SkinTemplates-Talk.