Version 6 Template Migration Guide - Revision history

SarahK at 21:49, 26 January 2023

2023-01-26T21:49:34Z

Show changes

Kevin at 07:07, 8 July 2015

2015-07-08T07:07:02Z

Matt: /* {php} Block Syntax */

2015-07-07T10:43:17Z

‎{php} Block Syntax

Matt: /* {php} Block Syntax */

2015-07-07T10:41:11Z

‎{php} Block Syntax

Matt: /* Smarty Templating Changes */

2015-06-17T07:54:47Z

‎Smarty Templating Changes

Matt: Created page with "=Smarty Templating Changes= WHMCS has gone through a number of backend changes in version 6. Included amongst them was internal upgrade from Smarty 2 to Smarty 3.1. Most cust..."

2015-06-15T17:15:33Z

Created page with "=Smarty Templating Changes= WHMCS has gone through a number of backend changes in version 6. Included amongst them was internal upgrade from Smarty 2 to Smarty 3.1. Most cust..."

New page

=Smarty Templating Changes=

WHMCS has gone through a number of backend changes in version 6. Included amongst them was 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.

<div class="docs-alert-info">The inverse of this change is also true. Custom templates made for WHMCS 6 that use Smarty 3 specific syntax are not compatible with previous versions of WHMCS.</div>

=={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:

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

Converts to:

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

=={php} Block Syntax==

<div class="docs-alert-info">An option was added to WHMCS 6 to enable or disable use of the potentially dangerous {php} tag in custom templates. This option is enabled by default but may become disabled by default in a future version. We recommend using hook functions over custom templates for backend interaction.</div>

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

{| class="wikitable" |
|-
! Original syntax
! New syntax
! Notes
|-
| <tt>$this</tt>
| <tt>$template</tt>
| All Smarty 3 block plugins have a <tt>$template</tt> parameter containing the current Smarty instance.
|-
| style="white-space: nowrap" | <tt>$this->_tpl_vars</tt>
| <tt>$template->getVariable('variableName')</tt> or <tt>$template->getTemplateVars()</tt>
| Template variables are represented by <tt>Smarty_Variable</tt> objects in Smarty 3, which have a value property.
|-
|}

For example, the following {php} block:

<syntaxhighlight lang="php">
{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}
</syntaxhighlight>

Converts to:

<syntaxhighlight lang="php">
{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}
</syntaxhighlight>

===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 [[Action Hooks]] for more information.

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

<syntaxhighlight lang="php">
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',
);
});
</syntaxhighlight>

And then reference the newly assigned variable in the template:

<syntaxhighlight lang="smarty">
<p>My custom variable value is: {$myCustomVariable}.</p>
</syntaxhighlight>

=The $client Object=

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

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

@@ Line 99: / Line 99: @@
 {/php}
      <div>
-         Lot's of HTML here...
+         Lots of HTML here...
      </div>
 {/php}

@@ Line 92: / Line 92: @@
 </syntaxhighlight>
-It is also work noting 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 condition.
+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.
 <syntaxhighlight lang="php">

@@ Line 33: / Line 33: @@
 =={php} Block Syntax==
-<div class="docs-alert-info">An option was added to WHMCS 6 to enable or disable use of the potentially dangerous {php} tag in custom templates. This option is enabled by default but may become disabled by default in a future version. We recommend using hook functions over custom templates for backend interaction.</div>
+<div class="docs-alert-info">An option was added to WHMCS 6 to enable use of the potentially dangerous {php} tag in custom templates. This option is disabled by default but can be enabled if required in '''Setup > General Settings > Security'''. We strongly encourage using hook functions over php code blocks inside of templates for backend interaction.</div>
-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
+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.
 {| class="wikitable" |
@@ Line 89: / Line 89: @@
 $template->assign('myNewVariable', 'myNewValue');
 {/php}
 </syntaxhighlight>
@@ Line 94: / Line 108: @@
 ===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 [[Action Hooks]] for more information.
+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 <tt>includes/hooks</tt> directory. Inspect and assign variables using the "ClientAreaPage" hook.

@@ Line 1: / Line 1: @@
 =Smarty Templating Changes=
-WHMCS has gone through a number of backend changes in version 6. Included amongst them was 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.
+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.
 <div class="docs-alert-info">The inverse of this change is also true. Custom templates made for WHMCS 6 that use Smarty 3 specific syntax are not compatible with previous versions of WHMCS.</div>