The RcbtNG template engine

Description

This is the default implementation of the TIP_Template_Engine abstract class. The format of an rcbt file is quite simple: it is a pure HTML file that can contains some tags: these tags are simple text enclosed by curly braces.

The curly braces must be used only to enclose tags. For performance reasons, the Rcbt implementation does not provide any way to escape curly braces!

How does it work?

The template that not is a tag and that is not inside a context (part of a text between a special built-id tag and {}) it is passed-throught and it goes directly to the output without modifications.

When a tag is found, it is parsed and divided into its component (module, name and params) and executed in place. This means the engine calls the function module->getTag(name,params) using the parsed module, name and params. See the template engine tutorial for technical details on the TIP_Module::getTag() method.

Tag sintax

An RCBT tag has the following syntax:

{[module.]name([params])}

• module (case insensitive)
  Identifies the module to use while executing this tag. If not specified, the current module will be used.
• name (case insensitive)
  Defines the tag to generate. The available tags are module dependent: consult the module documentation to see which tags are available, particulary the TIP_Module class. If not specified the 'html' tag will be generated.
• params (case sensitive)
  The arguments to pass to the tag generation method. Obviously, what params means depend by the tag called.

The content of params will be recursively executed before the call: this means the parameters can contains itsself any sort of valid tags.

The square brakets identify an optional part. All the following tags are valid tags:

{Blog.run(block.html)}: a complete tag
{User.logout()}: a tag without parameters
{Html(age)}: a tag without module
{logout()}: a tag without module and parameters
{age}: this is a special case and it is equivalent to {html(age)}
{(age)}: another special case equivalent to {tryHtml(age)}
{}: this special sequence is used to close a context opened by some built-in tags

Built-in tags

Some tag is built-in, that is when the engine found one of such tag, it does not call the getTag() method but it executes a special operation. The following list shows these built-ins tags (the [module.] part of the tags is omitted for clarity):

• {if([conditions])}
  Executes the text enclosed by this tag and the {} empty tag only if conditions is true. During the execution of this text the current module will be the module specified in the if tag (if any).
• {else()}
  Reverts the output mode imposed by the previous if tag: the natural complement of the previous tag.
• {select([filter])}
  Performs the specified select on the data object of the current content (or of the specified one) and runs the text enclosed by this tag and the {} empty tag with this select active. This can be helpful, for instance, to show the summary fields of a select. During the execution of this text, the default module will be the module specified in this tag (if any).
• {forSelect([filter])}
  Performs the specified select on the data object and, for every row, runs the text enclosed by this tag and the {} empty tag. During the expansion of this text, the current module will be the module specified by this tag (if any).
• {selectRow([id])}
  A shortcut of the forSelect tag, using id as the filter value for the primary key (that is WHERE `primarykey`=id).
• {forEach([name])}
  • If you do not specify name, it is the same as forSelect but traverses the current view instead of building a new one.
  • If name is a number, the enclosed text is executed name times; while parsing the enclosed text, the special tag {CNT} will keep track of the current cycle (that is it will be the value of the counter).
  • In any other cases, a special view is created by calling TIP_Content::startView(name). A common value for name is FIELDS that generates a special view that browses the field structure. Take a look to the documentation of the TIP_View derived objects for further informations.