Skin Templates

Tiu paĝo priskribas la aspektŝablonajn dosierojn (.tmpl), kiuj estas uzataj por krei la PmWiki-aspektojn, kaj kiel PmWiki uzas ilin. Kiel priskribite en la aspekto-paĝo, aspekto ? estas kolekto de dosieroj, kiuj difinas la dezajnon por PmWiki paĝoj. Ĉiu aspekto devas inkludi ŝablonan dosieron, kiu provizas la skeleton por montri PmWiki-paĝon.

Trovi kaj prilabori ŝablonojn

Kiam vi indikas la valoron de la variablo $Skin en agorda dosiero kiel local/config.php, kiel

# Uzu la ŝablonon foo.
$Skin = 'foo';

tio indikas al PmWiki serĉi aspekton de tiu nomo, kaj uzi ĝin. La kutima rezulto de tiu serĉo por PmWiki estas inkludi ŝablonan dosieron el la koncerna ŝablona dosierujo. En tiu ekzemplo, probable temus pri la dosiero pub/skins/foo/foo.tmpl.

La detala procedo, kiun PmWiki trairas por trovi ŝablonan dosieron estas grava por tiuj, kiuj kreas kompleksajn aspektojn, tial indas mencii la paŝojn:

Kiam $PageTemplateFmt estas malplena (kiel devus esti), PmWiki kolektas la nomojn de ĉiuj kandidataj aspektoj. Ĝi komencas per ajna agad-specifa aspekto indikita en $ActionSkin[$action]. Sekve, se la momenta agado estas 'login', kaj $ActionSkin['login'] estas 'Bar', tiam PmWiki serĉos aspekton nomita 'Bar'.
Se neniu aspekto estis trovita, ĝi serĉas aspekto(j)n indikitaj en la variablo $Skin (kiu rajtas esti vico) kaj uzas la unuan troveblan aspekton. Se fine de la listo ne troveblis aspekto, ĝi eldonos erarmesaĝon.
Por provi trovi aspekton, PmWiki unue konsultas la variablon $SkinLibDirs kiel elirpunkto. Aspektoj konsistas el servilflankaj dosieroj ŝargataj de PmWiki (kiel .php kaj .tmpl-dosieroj) kaj klientflankaj dosieroj (kiel .css kaj bildoj), kiuj estos prenataj de la foliumilo de la uzanto, kiam ĝi rigardas PmWiki-paĝon kun aspekto. $SkinLibDirs estas vico de ŝlosil/valoro-paroj. La ŝlosilo estas dosierujo por rigardi servilflankajn dosierojn, dum la koresponda valoro estas retligo, kiu indikas al la publikaj klientflankaj resursoj uzataj de la aspekto. La defaŭlta valoro de $SkinLibDirs estas:

Sekureca rimarkigo

La defaŭlta valoro por $SkinLibDirs enhavas servil- kaj klientflankajn dosierojn ene de la sama publike alirebla dosierujo. Tio signifas, ke $SkinDir kaj $SkinDirUrl montras al la sama loko. Tio okazas pro komforto (kaj por la aspektouzanto, kaj por la aspektokreanto), sed tio ne estas nepra.

Flanka efekto estas, ke eblas konstrui retligilon (kiel tiu ĉi), kiu permesas al vi rigardi la enhavon de la .tmpl aŭ .php dosieroj, kiujn tiu aspekto uzas. Tio kutime ne estas problemo, ĉar aspektodosieroj ne devus enhavi riskajn informojn.

Tamen, puristo povus emi ŝovi siajn .tmpl kaj .php dosierojn al ne rete alireblaj dosierujoj, kaj modifi sian vicon $SkinLibDirs laŭe reflekti tion.

 -> $SkinLibDirs = array(
   "./pub/skins/\$Skin"      => "$PubDirUrl/skins/\$Skin",
   "$FarmD/pub/skins/\$Skin" => "$FarmPubDirUrl/skins/\$Skin");

Once a valid skin directory has been found, PmWiki starts processing the files in that directory, looking for a .php skin file to run. It first looks for one with the same name as the skin. So, if the skin is 'foo', it looks for foo.php. If no such file is found, it then checks for a file named skin.php. If one of these .php files is found, PmWiki loads and runs it. This allows a skin to define custom markup, or custom configuration parameters. It also allows a skin to choose between which of several different .tmpl files to load.
To specify which .tmpl file to load, simply call LoadPageTemplate() inside the skin .php file, with the name of the .tmpl file to be loaded:
LoadPageTemplate($pagename, "$SkinDir/xyz.tmpl");
For example, a skin might specify a special template to be used if the action is 'print':
```
if ($GLOBALS['action'] == 'print')
  LoadPageTemplate($pagename, "$SkinDir/print.tmpl");
```
When the action is something else, PmWiki will fall back to loading the default .tmpl file instead.
If no appropriate .php file is found, or if that file doesn't load a template, then PmWiki falls back to looking for a template with the same name as the skin, or, failing that, any .tmpl file at all, so long as its the only one in the directory. If it finds one, it will load and process it. If not, it will issue an error.

Template file format

A template file is basically an HTML file that also contains variable substitutions (indicated by '$') and special directives embedded in HTML comments. The following special directives are required in the template file.

The directive  belongs to the <body> section of the HTML document, and tells PmWiki where the main content of each wiki page should be placed.
The directive , which goes somewhere in the <head> section of the HTML document.
The directive  directive, which typically goes before the final </body> tag and is used by some recipes to insert things at the end of the HTML document. Prior to PmWiki 2.2.0 the  directive was optional.

When PmWiki displays a page, it replaces the directives and variable substitutions with the values appropriate to the current page. For example, the  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. Page variables ? can also be used in templates.

Skin directives

Besides the required  and  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



: The  directive outputs the contents of Main.SomePage. $-substitutions are allowed in directives, thus a directive like  will include "SomePage" of the current group.
: If multiple pages are listed in the directive, then only the first available page is used. Thus  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  directives.
: The  directive only displays pages for which the browser has read permissions. The  directive displays pages even if the browser doesn't have read permission.

: The directive  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  directive above, $-substitutions are available to be able to output files based on the current page name or group.

: The markup directive processes any text that follows the colon as wiki markup and displays that in the output.

: 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.  generates one parameter "arg1 arg2 arg3". However variables can be used (like $LastModifiedBy).

Page sections

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  and continues to the next section, the end of the template file, or . For example, a template can specify a  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:)
<!--PageActionFmt-->          (:noaction:)

Skin 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:

Markup('noxyz', 'directives',  '/\\(:noxyz:\\)/ei',
    "SetTmplDisplay('PageXYZFmt',0)");

Internationalization (i18n)

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.

Understanding old config files

This information is deprecated, but we're still including it in the docs so you can better understand any really old local/config.php files you look at.

The original method of telling PmWiki where to find a skin used to be to set $PageTempateFmt to the path of a .tmpl file on the server. This is still respected by PmWiki, so if, for example, you were to set $PageTemplateFmt to ./pub/skins/foo/foo.tmpl then PmWiki would simply load and use that file, but without setting the special $SkinDir and $SkinDirUrl variables that are required by all modern skins.

DO NOT USE $PageTemplateFmt

How do I customize the CSS styling of my PmWiki layout?

See Skins for how to change the default PmWiki skin. See also Skins: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:

$HTMLStylesFmt[] = '.foo { color:blue; }';

Where can the mentioned "translation table" be found for adding translated phrases?

See Internationalizations ?.

Is it possible to have the edit form in full page width, with no sidebar?

If the sidebar is marked with , adding (:noleft:) to Site.EditForm will hide it when a page is edited.

Can I easily hide the Home Page title from the homepage?

Yes, you can use in the wiki page either (:title Some other title:) to change it or (:notitle:) to hide it.

Is it possible to hide the Search-Bar in the default PmWiki Skin?

Yes, please see Cookbook:HideSearchBar.

Tradukado de PmWiki.SkinTemplates
Origina paĝo ĉe PmWikiEo.SkinTemplates - Retroligiloj

Lastaj ŝanĝoj:
PmWikiEo.SkinTemplates: 2012-11-10 22:44

PmWiki.SkinTemplates: 2022-08-19 19:47

Other languages: English ar ? bg ? ca ? cs ? da ? de el ? eo es ? fa ? fi ? fr hu ? id ? it ? ja ? kr ? lt ? lv ? mk ? nl ? no ? pl ? pt ? ptbr ? ro ? ru ? si ? sk ? sq ? sv ? ta ? tl ? tr ? uk ? vi ? zhcn ? zhtw ? | New language