SkinTemplates
System
%STARTINCLUDE% ---+ Skin Templates The framework used to render output. %TOC% %STARTSECTION{"PowerUserGuide"}% ---++ Overview _Skin Templates_ are plain text with embedded _template directives_, [[Macros][macros]] and [[SkinTemplateTokens][tokens]] that are expanded by Foswiki to build an output, usually HTML. #HtmlTemplates Skin templates are used when composing the output from all actions, such as view, edit, and preview. By sharing common template definitions between all these actions, it makes it easy to change the look and feel of all pages by editing just a few templates. Skin templates are either stored as text files with the extension =.tmpl= in the =templates/= directory, or in Foswiki topics. _Template directives_ are expanded when the template is loaded, and are used to define the general structure of the output. _Macros_ and Template _Tokens_ are expanded when the page is rendered, and fill in page-specific information. Note that _Macros_ and _Tokens_ are written using the same syntax. See [[Macros]] for more information on macros. _Tokens_ look exactly like Macros, but they are specific for the script expanding the template, and cannot be used elsewhere in Foswiki. See [[SkinTemplateTokens]] for more information on tokens. #TemplateMacros ---++ How Template Directives Work Template directives look a lot like standard [[macros]]. * =%<nop>TMPL:INCLUDE{"file"}%= includes a template file. The file is found as described [[#FindingTemplates][below]]. * =%<nop>TMPL:DEF{"name"}%= defines a block. *All* text between this and the next =%<nop>TMPL:END%= directive is removed and saved for later use with =%<nop>TMPL:P%=. * =%<nop>TMPL:END%= ends a block definition. * =%<nop>TMPL:PREV%=: returns the previous definition of the block being defined. * =%<nop>TMPL:P{"name"}%= includes a previously defined block. * =%<nop>{...}%= is a comment. Whitespace either side of the comment (newlines, spaces, tabs etc) is treated as part of the comment, and removed when the comment is removed. You can use a block before _or_ after declaring it. If you define the same block twice, only the second definition is used. <blockquote class="foswikiHelp"> %X% Most template directives work only for templates: they do not get processed in normal topic text. The one exception is =%TMPL:P=. </blockquote> ---+++ Parameters to blocks =%<nop>TMPL:DEF%= and =%<nop>TMPL:P%= support simple parameters. Parameters are only available in the immediate definition being included; they are not passed on to any other =TMPL:P= inside the =TMPL:DEF= being expanded unless they are passed on explicitly in a new parameter. ---++++ Block parameters For example, we can define a parameter =P= inside a block: <verbatim class="tml"> %TMPL:DEF{"x"}% x%P%z %TMPL:END% </verbatim> then pass a value to that parameter: <verbatim class="tml"> %TMPL:P{"x" P="y"}% </verbatim> This will expand to =xyz=. ---++++ Naming Any alphanumeric characters can be used in parameter names. =TMPL:P= parameters override any other possible definition of the name, so you should not use parameter names that might clash with [[Macros]]. ---+++ Conditional expansion Three parameter names, =context=, =then= and =else= are *reserved*. They are used to support a limited form of "if" condition that you can use to select which of two =TMPL:DEF= to expand, based on a _context identifier_: <verbatim class="tml"> %TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END% %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END% %TMPL:P{context="inactive" then="link_inactive" else="link_active"}% for %CONTEXT% </verbatim> When the =inactive= context is set, then this will expand the =link_inactive= =TMPL:DEF=; otherwise it will expand =link_active=. This style of conditional expansion is used in preference to the =[[VarIF][%<nop>IF{}]]= macro where possible because it is much more efficient. See [[IfStatements#Context_identifiers][If Statements: Context identifiers]] for details of supported context identifiers. ---+++ =TMPL:INCLUDE= recursion You can use recursion with =%<nop>TMPL:INCLUDE%= for piecewise customisation, or mixing in new features. If there is a recursion in the =%<nop>TMPL:INCLUDE%= chain (eg. =view.tmpl= contains =%<nop>TMPL:INCLUDE{"view"}%=), the templating system will detect that you are trying to include the same template again, and will instead include the _next_ version of the template of that name that it finds in the [[#TemplatePath][template path]]. For example, say you _only_ want to override the breadcrumbs for the view script. You could create a tempate called =view.crumbless.tmpl=: <verbatim class="tml"> %TMPL:INCLUDE{"view"}% %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END% </verbatim> and then =* Set SKIN=crumbless,pattern= Remember: the template path contains the most specific template first. ---+++ Comments Comments =%{...}%= are removed from the templates as soon as the file is read, before any other template macros are evaluated. Whitespace either side of the comment (newlines, spaces, tabs etc) is also removed. #FindingTemplates ---++ Finding Skin Templates Most skin templates are stored in =.tmpl= files in the =templates= directory. For example, =templates/view.tmpl= is the default skin template file for the =bin/view= script. You can also save skin templates in user topics. The ={TemplatePath}= configuration setting (in the Miscellaneous section of the [[%SCRIPTURLPATH{configure}%][configure]] page) defines which directories, files and Foswiki topics will be recognised as containing templates. Skin templates that are loaded using =%<nop>TMPL:INCLUDE= with an explicit =.tmpl= extension are looked for _only_ in the =templates/= directory. For instance =%TMPL:INCLUDE{"example.tmpl"}%= will only return =templates/example.tmpl=, regardless of ={TemplatePath}= and =SKIN= settings. #TemplatePath All other templates are searched for using the ={TemplatePath}=. This is a list of generic name patterns, each of which contains the placeholders =$name= (the template name), =$web= (the web), and =$skin= (the skin), each standing in for part of the name. Each entry in this list is expanded in turn until the template is found. The rules defined by the out-of-the-box setting of ={TemplatePath}= are: 1 =templates/$web/$name.$skin.tmpl= 2 =templates/$name.$skin.tmpl= 3 =$web.$skinSkin$nameTemplate= 4 =%SYSTEMWEB%.$skinSkin$nameTemplate= 5 =templates/$web/$name.tmpl= 6 =templates/$name.tmpl= 7 =$web.$nameTemplate= 8 =%SYSTEMWEB%.$nameTemplate= For example, let's say we are viewing a topic in web =%SANDBOXWEB%= and are searching for the template called =function=. The skin path is set to =custom,pattern=. The following locations will be considered in turn, until a template is found: 1 =templates/%SANDBOXWEB%/function.custom.tmpl= _(rule 1)_ :skull: 1 =templates/%SANDBOXWEB%/function.pattern.tmpl= _(rule 1)_ :skull: 2 =templates/function.custom.tmpl= _(rule 2)_ 2 =templates/function.pattern.tmpl= _(rule 2)_ 3 =%SANDBOXWEB%.CustomSkinFunctionTemplate= _(rule 3)_ 3 =%SANDBOXWEB%.PatternSkinFunctionTemplate= _(rule 3)_ 4 =%SYSTEMWEB%.CustomSkinFunctionTemplate= _(rule 4)_ 4 =%SYSTEMWEB%.PatternSkinFunctionTemplate= _(rule 4)_ 5 =templates/%SANDBOXWEB%/function.tmpl= _(rule 5)_ :skull: 6 =templates/function.tmpl= _(rule 6)_ 7 =%SANDBOXWEB%.FunctionTemplate= _(rule 7)_ 8 =%SYSTEMWEB%.FunctionTemplate= _(rule 8)_ <blockquote class="foswikiHelp">%X% :skull: This usage is supported *for compatibility only* and is *deprecated*. Store web-specific templates in topics instead. </blockquote> When a skin name or template name is used to build a topic name, the first character is automatically capitalised. The _skin path_ is set as described in [[Skins]]. #TemplatePreferences Template file names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the =view= and =edit= scripts, for example when a topic-specific template is required. Two [[%SYSTEMWEB%.PreferenceSettings][preference settings]] can be used to override the skin templates used: * =VIEW_TEMPLATE= sets the template to be used for viewing a topic. * =EDIT_TEMPLATE= sets the template for editing a topic. If these preferences are set * locally (using _Local_ instead of _Set_) in a topic, or * in WebPreferences, or * in [[%LOCALSITEPREFS%]], or * in [[%SYSTEMWEB%.DefaultPreferences]] (using _Set_), then the indicated templates will be chosen for =view= and =edit= respectively. The template search order remains as specified above. #TemplateSecurity ---+++ Security and usability Setting the ={TemplatePath}= is a compromise between the often opposing goals of security and usability. From a security perspective, allowing templates to be loaded from topics might open a door to people who want to inject their own evil HTML in those topics. From a usability perspective, it's very desireable to be able to override templates from topics, as it vastly increases the range of wiki applications. The default ={TemplatePath}= comes down on the side of usability, by allowing templates from topics to be found before templates from the (more secure) =templates= directory. If you are particularly security concious, you may want to *reverse* this order, so that templates in =templates/= are always found before those in topics. You can do this by simply moving rules 3 and 7 to the end of the list. Note that topics containing templates are checked for VIEW access using the normal [[AccessControl][Foswiki access controls]]. Any access control failure is silently ignored, and the template path expansion continues. ---++ Developing new templates ---+++ Debugging When writing new templates, it can sometimes it can be hard to work out where different parts of the generated output come from. To help you debug your new templates, the =Foswiki::Templates= module has a "trace" mode. In this mode, the output is annotated with HTML comments that are wrapped around the output generated by each template, as it is expanded. For example, when trace mode is off, <verbatim class="tml"> %TMPL:DEF{"x:y"}% de %TMPL:END% blah %TMPL:P{"x:y"}% blah </verbatim> will expand to: <verbatim class="tml"> blah de blah </verbatim> With tracing enabled, it will expand to: <verbatim class="tml"> blah <!--x:y--> de <!--/x:y--> blah </verbatim> To enable the trace mode, edit =lib/Foswiki/Templates.pm= in your installation and change =use constant TRACE => 0= to =use constant TRACE => 1=. Note that the trace annotations may make your output look strange. However you can usually "view source" in the browser to see what was generated (or you may be able to run the script from the command-line e.g. =cd bin; perl -T -I . view topic=MyWeb.MyTopic skin=mynewskin=). <blockquote class="foswikiHelp">%I% Don't forget to switch the trace mode off again when you are finished!</blockquote> ---+++ Overview of the default templates Finally, here's a very high-level overview of the default templates. These templates are rarely used on their own, but are used as the base on which skins, such as PatternSkin, are built. =foswiki.tmpl= is the default master template. The main purpose of this template is to instantiate the following blocks: * =htmldoctype= - start of all HTML pages * =bodystart= - start of the body tag * =main= - page content * =bodyend= - end of the page Default definitions are provided for each of these blocks. =foswiki.tmpl= is never used on its own, but is frequently included by other templates. Next, there are a number of action-specific templates, such as =view.tmpl=, =edit.tmpl=, =login.tmpl=. These are the templates loaded by the actions of the same name. Their purpose is to include =foswiki.tmpl=, and provide new, page-specific, definitions of the blocks described above. Several of the action-specific templates have _skinned_ versions, such as =view.print.tmpl= and =view.text.tmpl=. These skinned versions are used to view the page in a specific way - for printing, or as plain text, for example. =messages.tmpl= is an important template; it provides the basic definitions of all error and warning messages that Foswiki issues. These are defined using the =%<nop>MAKETEXT= macro to simplify translation into different languages. =attachtables.tmpl= is another template worthy of separate mention. This template defines the different parts of the page that are involved in displaying tables of attachments. The blocks defined in this template are instantiated directly from code, rather than via =%<nop>TMPL:P=. The remainder of the templates are used for varying purposes; their names, or introductory comments, should clarify. A skin can provide a new version of any or all of these templates, depending on the depth of customisation. See the template files named =*.pattern.*= to see what PatternSkin defines. %ENDSECTION{"PowerUserGuide"}% --- *Related Topics:* [[Skins]] [[Macros]] [[JavascriptFiles]] <!-- %JQREQUIRE{"chili"}% --> %STOPINCLUDE%
History: r1 - 06 Oct 2011 - 03:01:02 -
ProjectContributor
WikiRing.com partner