version=pmwiki-2.1.26 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US; rv:1.8.0.6) Gecko/20060728 Firefox/1.5.0.6
author=swestrup
csum=Added description of how multiple .tmpl files work.
host=216.138.194.169
name=PmWiki.SkinTemplates
rev=18
targets=PmWiki.Skins,PmWiki.PageVariables,PmWiki.PageDirectives,PmWiki.Internationalizations,PmWiki.DocumentationIndex
text=This page describes the skin template files (.tmpl) that are used to create PmWiki ''skins'', and how PmWiki uses them. 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.%0a%0a!! Template Processing%0a%0aPmWiki processes any skin.php file in the skin directory before loading any templates. If there is no skin.php file, or if the skin.php file doesn't load a template, then PmWiki falls back to looking%0afor a template with the same name of the skin, or a single .tmpl file if it exists.%0a%0aIn simpler setups (which is what the vast majority of skins have), the skin.php file is absent or makes no mention of the .tmpl file, and so PmWiki finds and loads the template itself. To exert greater control over the process, simply call LoadPageTemplate() inside the skin.php file, with the name of the .tmpl file to be loaded:%0a%0a->[@LoadPageTemplate($pagename, "$SkinDir/xyz.tmpl");@]%0a%0aFor example, a skin might specify a special template to be used if the action is 'print':%0a%0a->[@if ($GLOBALS['action'] == 'print')@]%0a-->[@LoadPageTemplate($pagename, "$SkinDir/print.tmpl");@]%0a%0aWhen the action is something else, the default skin gets loaded instead.%0a%0a!!Template file format%0a%0aA 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 [@%3c!--PageText-->@] belongs to the %3cbody> section of the HTML document, and tells PmWiki where the main content of each wiki page should be placed.  The other required directive is [@%3c!--HTMLHeader-->@], which goes somewhere in the %3chead> section of the HTML document.%0a%0aThere is also an optional [@%3c!--HTMLFooter-->@] directive, which typically goes before the final %3c/body> tag and is used by some recipes to insert things at the end of the HTML document.   %0a%0aWhen PmWiki displays a page, it replaces the directives and variable substitutions with the values appropriate to the current page.  For example, the [@%3c!--PageText-->@] directive is replaced with the page's contents, while any instances of $PageUrl are replaced with the url (address) of the current page.%0a%0aThere is a long list of variables available for substitution in pages; some of the%0amost useful include:%0a%0a    [@$PageUrl         the url of the current page%0a    $ScriptUrl       the base url to the pmwiki.php script%0a    $Title           the page's title (e.g., "`SkinTemplates")%0a    $Titlespaced     the page's title with spaces (e.g., "Skin Templates")%0a    $Group           the name of the current group  (e.g., "`PmWiki")%0a    $FullName        the page's full name (e.g., "`PmWiki.SkinTemplates")%0a    $LastModified    the page's last modification time%0a    $PageLogoUrl     the url of a site logo%0a    $WikiTitle       the site's title%0a    $SkinDirUrl      the url of the skin's folder@]%0a%0aThis 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.%0a%0aThe 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.  [[Page variables]] can also be used in templates.%0a%0a!! Skin directives%0a%0aBesides the required [@%3c!--PageText-->@] and [@%3c!--HTMLHeader-->@] 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 %0a%0a:[@%3c!--wiki:Main.SomePage-->@]:%0a: :The [@%3c!--wiki:Main.SomePage-->@] directive outputs the contents of `Main.SomePage.  $-substitutions are allowed in directives, thus a directive like [@%3c!--wiki:$Group.SomePage-->@] will include "`SomePage" of the current group.  %0a%0a: :If multiple pages are listed in the directive, then only the first available page is used.  Thus [@%3c!--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 [@%3c!--wiki:...-->@] directives.%0a%0a:[@%3c!--file:somefile.txt-->@]:%0a: :The directive [@%3c!--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 [@%3c!--wiki:...-->@] directive above, $-substitutions are available to be able to output files based on the current page name or group.%0a%0a:[@%3c!--markup:...-->@]:%0a: :The markup directive processes any text that follows the colon as wiki markup and displays that in the output.  %0a%0a:[@%3c!--function:SomeFunction args-->@]:%0a: :This directive calls a PHP function named "`SomeFunction", passing the current page's name and the text following the function name as arguments.  PHP functions called in this manner are typically defined in a local customization file. Args allows only one argument, which has to be splitted then. [@%3c!--function:SomeFunction arg1 arg2 arg3-->@] generates one parameter "arg1 arg2 arg3". However variables can be used (like $LastModifiedBy).%0a%0a!! Page sections%0a%0aA 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 [@%3c!--Page...Fmt-->@] and continues to the next section, the end of the template file, or [@%3c!--/Page...Fmt-->@].  For example, a template can specify a [@%3c!--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:%0a%0a    [@%3c!--PageHeaderFmt-->          (:noheader:)%0a    %3c!--PageFooterFmt-->          (:nofooter:)%0a    %3c!--PageTitleFmt-->           (:notitle:)%0a    %3c!--PageLeftFmt-->            (:noleft:)%0a    %3c!--PageRightFmt-->           (:noright:)%0a    %3c!--PageActionFmt-->          (:noaction:)@]%0a%0aSkin designers can define custom sections and markups, but currently all section names in the template must begin with "Page" and end with "Fmt". As mentioned you also have to define the corresponding markup (for example in your config.php) like this: %0a%0a    [@Markup('noxyz', 'directives',  '/\\(:noxyz:\\)/ei',%0a       "SetTmplDisplay('PageXYZFmt',0)");@] %0a%0a!! Internationalization (i18n)%0a%0aSkins can also be [[internationaliz(ations)]]ed 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.%0a%0aFor 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.%0a%0a%0a%0a%25trail%25%3c%3c|[[DocumentationIndex]]|>>%0a%0a>>faq%3c%3c [[#faq]]%0a%0aQ: How do I customize the CSS styling of my PmWiki layout?[[#customcss]]%0a%0aA: See [[Skins]] for how to change the default PmWiki skin.  See also [[Cookbook:Skins]], where you will find pre-made templates you can use to customize the appearance of your site.  You can also create a file called ''local.css'' in the ''pub/css/'' directory and add CSS selectors there (this file gets automatically loaded if it exists).  Or, styles can be added directly into a local customization file by using something like:%0a%0a->[@$HTMLStylesFmt[] = '.foo { color:blue; }';@]%0a%0a%0aQ: Where can the mentioned "translation table" be found for adding translated phrases?%0a%0aA: See [[Internationalizations]].%0a%0a
time=1159038649