blob: ebeacea3353a6be67afd7ee91eb29f6fb69592cb [file] [log] [blame]
text=As described in the [[LayoutBasics]] page, HTML based templates can be used to customize the layout and appearance of Wiki pages. Template files can include links to external stylesheets (.css files). This page explains how template files are processed and how CSS files are included.²²!! Templates: Directives and Variables²²HTML comments can be included in templates, for example: <!-- this is a comment -->. Some comments work as directives that have special significance. There are no spaces between the comment delimeters and the keywords; that is, [@<!--PageText-->@] is valid, but [@<!-- PageText -->@] is not. Available directives and variables are:²²:[=<!--PageText-->=]:This indicates where the content of the current Wiki page should be inserted.²²:[=<!--HeaderText-->=]:This directive allows PmWiki to insert appropriate meta tags into the <head> section of the HTML output (used to control indexing by search engines). PmWiki will also check for the existence of relevant CSS files in pub/css; $Group.css and $Group.$Name.css will be included here if they exist.²²:Call a PHP function [=<!--function:SomeFunction ''arguments''-->=]:You could use this to call a function you defined in your local/config.php which may print out different text based on, say, the current page or group. The function receives full page name (ex. [=PmWiki.LayoutAdvanced=]) and the text following function name (which is optional and can be omitted).²²:[=<!--Page...Fmt-->=] directives:A directive in this form (ie. starting with "Page" and ending with "Fmt") indicates the beginning of a section of the template. The section that follows is placed in a variable by the same name. For example, [=<!--PageFooterFmt-->=] indicates the start of a footer which is stored in the $PageFooterFmt variable. The section continues until the next [=<!--Page...Fmt-->=] directive, or the end of the file. It is also possible to indicate the end of a section using [=<!--/Page...Fmt-->=]. Note that, by default, only $PageHeaderFmt, $PageFooterFmt and $PageTitleFmt are included in the output when a WikiPage is viewed. Other variables can be defined and used, but they will only appear in certain situations. For example, [=<!--PageEditFmt-->=] can be used to define a section that only appears when the Edit action is in use (ie. a page is being edited).²²:Including variables:PHP variables are evaluated when PmWiki processes a template file. For example, you can insert a logo using [=$PageLogoFmt=], or create an Edit Page link using [=<a href='$PageUrl?action=edit'>$[Edit Page]</a>=]²²:Include a Wiki page: To have a template file include the contents of another page, simply use [=<!--wiki:SomeGroup.SomePage-->=] where [=SomeGroup.SomePage=] is the name of the page to be displayed. $-substitutions work here, so the template file can specify [=<!--wiki:$Group.SomePage-->=] which says to use "[=SomePage=]" within the group of the current page. The directive can specify multiple pages to be examined, and only the first of these is displayed, thus [=<!--wiki:$Group.SomePage Main.SomePage-->=] displays "[=SomePage=]" in the current group if it exists, and [=Main.SomePage=] if it doesn't. To always display [=Main.SomePage=], even if [=$Group.SomePage exists=], use something like [=<!--wiki:$Group.SomePage-->=] or [=<!--wiki:Main.SomePage-->=] which displays "[=SomePage=]" in the current group if it exists, and follows that with [=Main.SomePage=]. Within page markup, the [=(:include:)=] directive is used to include/display the contents of another wiki page.²²²²!! CSS Files: Controlling Page Style²²(Note: this is a first attempt at describing CSS within PmWiki - still needs work!)²²CSS rules can come from any of the following sources:² 1. CSS rules in the $HTMLStylesFmt array (modules and cookbook recipes)² 2. <link> and <style> tags placed in $HTMLHeaderFmt by ² site/page/group config.php entries and cookbook recipes² 3. <link> and <style> tags placed in $HTMLHeaderFmt by ² skin customizations² 4. pub/css/local.css² 5. pub/css/$Group.css² 6. pub/css/$Group.$Name.css² 7. <link> and <style> tags specified in the skin's .tmpl file²²By default, items 1-6 above occur in the order given above, and are placed²in the output at the point where [=<!--HeaderText-->=] appears in the .tmpl²file. For item 7, the order (and thus priority) of <link> and <style> ²tags in the .tmpl file relative to 1-6 depends on where the skin author ²places them relative to [=<!--HeaderText-->=].²²For any CSS rules that have the same weight (i.e., importance and²specificity), the one that occurs latest in the HTML output always²wins. So, for example, if a skin template says²² [=<link rel='stylesheet' type='text/css' href='$SkinDirUrl/myskin.css' />² <!--HeaderText-->=]²²then the rules specified in 1-6 above will override any equivalent-weight²rules from myskin.css. Thus, an administrator could use pub/css/local.css²to override any of the defaults, whether they come from PmWiki, a cookbook²script, or a skin. However, if the tags are in reverse sequence²² [=<!--HeaderText-->² <link rel='stylesheet' type='text/css' href='$SkinDirUrl/myskin.css' />=]²²then any rules given in the myskin.css stylesheet will override any²equivalent-weight rules from 1-6 above. And, of course, the .tmpl²file can sandwich stylesheets around [=<!--HeaderText-->=]:²² [=<link rel='stylesheet' type='text/css' href='$SkinDirUrl/sheet-1.css' />² <!--HeaderText-->² <link rel='stylesheet' type='text/css' href='$SkinDirUrl/sheet-2.css' />=]²²In this case, the administrator can easily override the settings in²sheet-1.css via the mechanisms listed in 1-6 above, and sheet-2.css can²override the administrator's settings.²²The above glosses over a few details -- such as the fact that those²rare entries to $HTMLHeaderFmt by markup and action handlers will ²typically show up after item 6, and that it's possible for a local²customization (or skin or cookbook script) to completely change²the sequence to be something else, but this is how things "normally²work".²²Category: [[!Skins]]²²%trail%<<|PmWiki.DocumentationIndex|>>
author=David A Spitzley
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.7.6) Gecko/20050317 Firefox/1.0.2