Karma's Nucleus DevBlog

This post tries to explain how the parsing of skins/templates works in Nucleus.

Let's start with a peculiarty. Everyone is using skinvars as <%skinvar%>, but did you know that these will also work: <%skinvar<%, %>skinvar<% and %>skinvar%>? They do. This is because of the way the parser works.

PARSER.php

Most of the skins and templatevars are parsed using an object of the PARSER class. Some templateparts are still parsed using the TEMPLATE::fill function, however (see below)

Basic characteristics of a parser object are these:

• A reference to an object that will 'handle' skinvars. This can be an object of one of the following classes: ITEMACTIONS (item templates), COMMENTACTIONS (comments templateparts), PAGEFACTORY (add/edit item forms) or ACTIONS (skins). All these classes also inherit from BaseActions, which contains common actions like 'include' and common functions to handle if-structures.
• A list of actions (skinvars) that are allowed in the current parsing context. If a skinvar is not there, you'll end up with the dreaded 'DISALLOWED' message.

The parser starts as follows: the text that needs to be parsed is split into pieces by the PHP split function preg_split function (should be faster according to PHP split doc ). The pattern by which the splitting is done, is (<%|%>), and this is what causes the peculiarity described above.

The result is an array with alternately a piece of direct content, and a skinvar with its parameters. The direct content is sent to the output right away, while the skinvar pieces are handled by the doAction method.

doAction checks if it is allowed and worthwhile to execute the skinvar (it's not worthwhile if the skinvar is inside an undisplayed if-section).

When allowed, the parser tries two things:

1. Call the parse_skinvar method on the action handler object
2. If that fails, and plugins are available in this context, translates the skinvar to <%plugin(PluginName,params)%> and tries the doAction method again. (plugins are handled by the parse_plugin method)

TEMPLATE::fill method

In the early Nucleus days, all templates were parsed using TEMPLATE::fill. Today, it is still used for some parts like the category and archive lists. It's a very simple function which takes an associative array mapping templatevar to the contents. The method simply iterates through these and uses str_replace("<%$key%>",$values[$key],$template); to fill out the template-vars. This is the reason why no plugins can be used in these template-parts.