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   

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

    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}');  
    }

    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

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.