How to Implement PHP Template Processing Recursion with SIREN Template Engine - SIREN PHP Templating Library package blog

What is the Utility of Recursive Templates

Recursive templates can be useful when you have some complex layout for a page, and you want to split each part of the page layout, in separate templates.

This way you can simplify the page layout development and the maintenance that you may want to perform in the future to modernize that page layout.

How to Implement Recursive Template Processing Learning from Code Examples using SIREN Template Engine

The basic requirements to implement template processing are a text containing (named) markers and an array that maps these markers to replacement text. The text itself has a name too and is also contained in the array.

What SIREN PHP Templating Library does is scan the text, detect the marker(s), extract its name and replace it with the corresponding text found in the array. In SIREN the (named) markers are called variables and they have a value (replacement text).

Regular Template Usage

First let's see what the process of template replacement is all about. Than we look at how recursion can add value to this process.

    Example 1.  Regular usage, no recursion.
    The text 'My name is {firstName} {middleName} {lastName)'  
    The array {'firstName' => 'Martin', 'lastName' => 'King', middleName => 'Luther']  
         $snippet = new Snippet();  
         $snippet->setVar('text', 'My name is {firstName} {middleName} {lastName}');  
         $snippet->setVar('firstName', 'Martin');  
         $snippet->setVar('middleName', 'Luther');  
         $snippet->setVar('lastName', 'King');  
    echo $snippet->parse('output', 'text');  // My name is Martin Luther King

Let's adjust the example with a more sophisticated example: define a variable 'fullName' that has embedded the individual name parts. Punctuation could be added.

    Example 2.  Basic usage, no recursion.
    The text 'My name is {fullName}'  
         $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
    echo $snippet->parse('output', 'text');  // My name is {firstName} {middleName} {lastName}   
    echo $snippet->parse('final', 'output'); // My name is Martin Luther King

So far so good. We've embedded some variables in the value of the variable 'fullName'. And in simple cases like this one, and without recursion, we can and must parse the text twice. But this is dropping a dependency into your code. A dependency on the structure of the main variable 'fullName' and the embedded variables with their respective values.

Simplifying Recursive Template Processing

With recursion, this example would reduce to:

    echo $snippet->parse('final', 'text');  // My name is Martin Luther King

And this makes sense since we rather would define

    $snippet->setVar('fullName', '{lastName}, {firstName} {middleName}';

to have an output like 'My name is King, Martin Luther'.

Advanced Usage without Recursion

This shows that SIREN replaces the variable fullName with text that embeds a few other variables, which is detected by SIREN, and results in replacing those embedded variables with their respective values. All in one go.

    Example 3.  Advanced usage, no recursion.
    The text 'I am greeting you on behalf of {someHuman}'    
        $snippet->setVar('someHuman', '{fullName}');  
        $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
    echo $snippet->parse('pass1', 'text');  // I am greeting you on behalf of {fullName}   
    echo $snippet->parse('pass2', 'pass1'); // I am greeting you on behalf of {firstName} {middleName} {lastName}   
    echo $snippet->parse('output','pass2'); // I am greeting you on behalf of Martin Luther King

In above example we need to parse the text three times. This is the case where recursion comes in very handy, and this example would reduce to

    echo $snippet->parse('output','text'); // I am greeting you on behalf of Martin Luther King

because SIREN detects that the replaced text of a variable contains embedded variables, parses them automatically, detects that ...... etc.

# 1. So, in example 2 'fullName' is replaced by '{firstName} {middleName} {lastName}' is replaced by their final values .

# 2. And, in example 3, 'someHuman' is replaced by '{fullName}', is replaced again by, using recursion, see (# 1) .

Real benefit is found when you abstract your templates with symbolic variables. Like the date needs different formats depending on the locale, the name must be written differently depending on the audience. Americans are used to 'Martin Luther King' or 'Martin L. King', and europeans merely use 'King, Martin Luther' or 'King, M.L.'.

    Example 4.  Setup for a variable format of fullName  
        $snippet->setVar('firstName', 'Martin'};  
        $snippet->setVar('middleName', 'Luther'};  
        $snippet->setVar('lastName', 'King'};  
        $snippet->setVar('initials', 'M.L.'};  
        $snippet->setVar('shortMiddleName', 'L.'};  
    if (audienceIsAmerican) {  
        $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
    } elseif(audienceIsEuropean){  
        $snippet->setVar('fullName', '{lastName}, {initials}');  
    } else {  
        $snippet->setVar('fullName', '{lastName}, {firstName}');  
    }

Than, there is also a difference in the usage of a fullName, a commonName and/or an officialName.

    Example 5.  Setup for a variable format of people's name  
    if (audienceIsAmerican) {  
        $snippet->setVar('fullName', '{firstName} {middleName} {lastName}');  
        $snippet->setVar('commonName', '{firstName} {shortMiddleName} {lastName}');  
        $snippet->setVar('officialName', '{lastName}, {firstName} {shortMiddleName} ');  
    } elseif(audienceIsEuropean){  
        $snippet->setVar('fullName', '{lastName}, {initials}');  
        $snippet->setVar('commonName', '{lastName}, {firstName} {shortMiddleName}');  
        $snippet->setVar('officialName', '{lastName}, {initials}');  
    } else {  
        $snippet->setVar('fullName', '{lastName}, {firstName}');  
        $snippet->setVar('commonName', '{firstName} {lastName} {middleName}');  
        $snippet->setVar('officialName', '{lastName}, {initials}');  
    }

In above examples, one could use the variables 'fullName', 'commonName' and 'officialName' at will in the templates, getting every time a correct spelling. It's a matter of assigning the right variables, and the design of the result is separated from your coding.

And there is more. Suppose the legal department does not allow the free usage and demands that the choice of name-format should be contained in the code.

    Example 6.  Setup for a variable format of people's name, fixed in the script  
    if (invoicePrinting) {  
        $snippet->setVar('typeOf', 'official');  
    } elseif(letterPrinting){  
        $snippet->setVar('typeOf', 'common');  
    } else {  
        $snippet->setVar('typeOf', 'full');  
    }
    The template text must now be: 'My name is {{typeOf}Name}.'

# 3. So, in example 6, the variable {typeOf}Name is first replaced by 'fullName', 'commonName' or 'officialName' and the resulting variable is recursively replaced.

Conclusion

Here ends the tutorial. We learned some recursion tricks. It is good to know that In SIREN the depth of the recursion can be set: NONE, BASIC, AUTO, and DEEP.

If you want to try the template recursion possibilities described in this article, you can download the SIREN package its code going to the download tab of the package page. Accessing its download page you can also get the details on how to install SIREN with the Composer tool, so you can integrate it well on your projects that you also install other packages using composer.