Revision as of 07:07, 8 July 2015

Smarty Templating Changes

WHMCS has gone through a number of backend changes in version 6. Included amongst them was the internal upgrade from Smarty 2 to Smarty 3.1. Most custom templates won't need any updates to be compatible with version 6, but those that used features only available in Smarty 2 will need to be migrated to ensure a smooth transition to the latest version.

{literal} Changes

Smarty 3's engine changes the way whitespace is interpreted in templates, removing the need for {literal} tags around "{" and "}" characters in CSS and Javascript blocks.

For example, the following Javascript from a Smarty template:

<script type="text/javascript">
    function example() 
    {literal}{{/literal}
        alert('example');
    {literal}}{/literal}
</script>

Converts to:

<script type="text/javascript">
    function example() 
    {
        alert('example');
    }
</script>

{php} Block Syntax

Smarty 3's backwards compatibility layer defines the {php} tag as a block plugin instead of a method native to the Smarty object. Combined with Smarty's internal rewrite in version 3, some syntax available within a Smarty 2 {php} block will need small modification.

For example, the following {php} block:

{php}

// Retrieve a single template variable. 
$myValue = $this->_tpl_vars['myVariable'];

// Loop through all template variables.
foreach ($this->_tpl_vars as $key => $value) {
   echo "{$key}: {$value}";
}

// Assign a new template variable.
$this->assign('myNewVariable', 'myNewValue');

{/php}

Converts to:

{php}

// Retrieve a single template variable. 
$myValue = $template->getVariable('myVariable')->value;

// Loop through all template variables. 
foreach ($template->getTemplateVars() as $key => $variable) {
   echo "{$key}: {$variable->value}";
}

// The assign() method works as it did before, though it must now be 
// called on the $template object instead of $this.
$template->assign('myNewVariable', 'myNewValue');

{/php}

It is also importing to note that because of these changes, PHP code blocks that close in the middle of a condition, such as the below example, are now no longer possible and result in a fatal error.

{php}
if ($foo) {
{/php}
    <div>
        Lots of HTML here...
    </div>
{/php}
}
{/php}

Migrating From {php} Tags To Hooks

It's a good practice to separate backend logic from display logic. In most cases a template's {php} block can be migrated to a hook file. Hooks are very useful for performing custom actions at specific points in WHMCS's page generation routines. See PHP Logic within Templates for more information.

For instance, one can reference existing template variables or define new template variables in a PHP file in the includes/hooks directory. Inspect and assign variables using the "ClientAreaPage" hook.

add_hook('ClientAreaPage', 1, function($templateVariables)
{
    // Look for an existing template variable.
    foreach ($templateVariables as $name => $variable) {
        doThings();
    }
    
    // Define new variables to send to the template.
    return array(
        'myCustomVariable' => 'myCustomValue',
    );
});

And then reference the newly assigned variable in the template:

<p>My custom variable value is: {$myCustomVariable}.</p>

The $client Object

All client area templates now have a $client variable that represents the currently logged in client. $client is either a WHMCS\Client\User object or null if no client is logged in. See Using Models for more information on how to work with model-based objects.

{if $client === null}
    <p>Nobody is logged in. :(</p>
{else}
    <p>Hello, {$client->firstName} {$client->lastName}!</p>
{/if}