Chapter 2. r3 Markup Language

r3 uses an XML-style markup. The markup is not true XML because it treats all unrecognized tags as plain text. This has the benefit that templates can contain arbitrary text. However, this also means that r3 templates may not be readable by a generic XML parser.

r3 markup directives all use the r3 namespace.

	Note
	Markup tags are interpreted and executed at generation-time, that is, at the time the template is being translated and when the target is being generated. Interpretation and translation occur in one step, and proceed from the top to the bottom of the page, which means that all directives are processed in the order they occur in the page.

r3:comment

Embeds a comment in the template which is stripped out for processes downstream.

<r3:comment>The following lines do such and such</r3:comment>

r3:cphp

Allows in-line PHP to be executed at template processing time. For example:

<r3:cphp>print("Hello, world!");</r3:cphp>

r3:include

Introduces a sub-template to be included. For example:

<r3:include path="included.r3" args="1,2,3" />

You can get at those args from within a cphp block in the included template like this:

<r3:cphp>
    $args = $context->getTemplateArgs();
    print "first arg is {$args[0]}";
</r3:cphp>

The $context variable is always available within a cphp block.

You can pass variables to a template in the same way:

<r3:cphp>
    $arg1 = "Hello World!";
    $arg2 = "and Goodnight!";
</r3:cphp>
<r3:include path="included.r3" args="$arg1,$arg2" />

r3:loop

Loops over each element of an array. There are two forms.

<r3:loop var="$anArray" as="$val">

<r3:loop var="$anArray" as="$key=>$val">

The first syntax loops over the array, assigning the value of the current element to $val. The second syntax loops over the array, assigning the value of the current key to $key, and the value of the current element to $value.

<r3:cphp>
$myarray = array( "one", "two", "three" );
$myarray2 = array( "key1" => "val1", "key2" => "val2", "key3" => "val3" );
</r3:cphp>

<r3:comment>------ first loop syntax --------</r3:comment>
<r3:loop var="$myarray" as="$val">
    <r3:var>$val</r3:var>
</r3:loop>

<r3:comment>----- second loop syntax ------</r3:comment>
<r3:loop var="$myarray" as="$val">
    <r3:cphp>echo $val;</r3:cphp>
    <r3:loop var="$myarray2" as="$key2=>$val2">
        <r3:cphp>echo "$key2 : $val2";</r3:cphp>
    </r3:loop>
</r3:loop>

r3:switch

Controls program execution based on the value of a test variable.

<r3:switch var="$test">
  <r3:case test="value">do something</r3:case>
  ...
  <r3:default>do the default thing</r3:default>
</r3:switch>

Here's a more complete example. Note that the case statement can test against a value stored in a variable:

<r3:cphp>
$myvar = getenv('TESTVAL');
$two="two";
</r3:cphp>

the testvar is <r3:var value="$myvar" />

<r3:switch var="$myvar">

    <r3:case test="one">
    switch1
    </r3:case>

    <r3:case test="$two">
    switch2
    </r3:case>

    <r3:case test="three">
    <r3:include path="included.ros" />
    </r3:case>

    <r3:default>
    switch-default
    </r3:default>

</r3:switch>

r3:trans

Introduces a piece of text to be translated. For example:

<r3:trans>Text to be translated</r3:trans>

r3:var

Allows embedding of a variable value into the output. For example:

You have <r3:var>$num</r3:var> messages.

r3 Reference Guide

Chapter 2. r3 Markup Language