PmWiki Customization Concepts

This is a list of PmWiki concepts that specifically deal with customization and is organized in alphabetical order (and can be reused in other Wiki pages on this site). A lot of the terms used on this page are also on this page or on the Concept page.

Local Customization

A WikiAdministrator can make a lot of local customizations simply by setting variables in the local/config.php file. Depending on the type of installation (simple or farm), and the type of feature that needs customization, changes in one or more configuration files may be required.

From its inception, PmWiki has been designed so that Wiki Administrators can greatly customize the way PmWiki displays pages and the markup sequences used to generate pages. (This is even mentioned explicitly in Pm Wiki Philosophy #4.) As a result, the core pmwiki.php script makes extensive use of variables to determine how markup sequences will be processed and what each individual page will output.

Internationalizations

PmWiki supports internationalization (internationalisation) of web pages, allowing accented characters to appear in page names and almost complete customization of PmWiki's prompts. Internationalizations are available for many languages.

Skin

A skin is a bunch of files that control what PmWiki pages look like (colors, fonts, borders, etc.) and how they are laid out. The easiest way to understand what a skin does is to try some out using the links below. They lead to the same page PmWiki.Skins) on the pmwiki.org site, and open in a separate window.

• BeeblebroxNetGila
• JHSkin
• GeminiSkin
• LightSkin
• Monobook Skin
• Simple Skin

As you saw, all skins show the same page contents, but the other elements such as the sidebar, header, and footer, all changed. For example, different skins may display the sidebar on the left, on the right, or even not at all. Some skins have action links and features that others do not, especially if they were designed to take advantage of particular cookbook recipes.

So, a skin is just the set of files that determine how pages are displayed in PmWiki. Normally skins are stored as subfolders of /pub/skins/. Each skin typically has one or more of the following kinds of files:

• A template file, such as pmwiki.tmpl, skin.tmpl, or gemini.tmpl. The template is written in HTML or XHTML, and is the framework or skeleton for the skin. It contains special markers that tell PmWiki where to insert the page's contents.
• CSS files, which can control the skin's appearance.
• Image files, for decorating a page with images. Common image file formats are .jpg, .png, and .gif.
• PHP files, such as skin.php. These let skins provide extra customization setting or capabilities that HTML and CSS alone cannot.
• Documentation files, usually something like readme.txt or skinname.txt. These usually give you information about any special installation steps or nifty features the skin has.

Custom Markup

PmWiki's markup translation engine is handled by a set of rules; each rule searches for a specific pattern in the markup text and replaces it with some replacement text. Internally, this is accomplished by using PHP's "preg_replace" function.

Rules are added to the translation engine via PmWiki's Markup() function, which looks like

where $name is a unique name (a string) given to the rule, $when says when the rule should be applied relative to other rules, $pattern is the pattern to be searched for in the markup text, and $replace is what the pattern should be replaced with.

For example, here's the code that creates the rule for ''emphasized text'' (in scripts/stdmarkup.php):

Basically this statement says to create a rule called "em" to be performed with the other "inline" markups, and the rule replaces any text inside two pairs of single quotes with the same text ($1) surrounded by <em> and </em>.

The first two parameters to Markup() are used to specify the sequence in which rules should be applied. The first parameter provides a name for a rule -- "em" in the example above. We could've chosen other names such as "''", or even "twosinglequotes". In general PmWiki uses the markup itself to name the rule (i.e., PmWiki uses "''" instead of "em"), but to keep this example easier to read later on we'll use a mnemonic name for now.