Difference between revisions of "Templates and Custom PHP Logic"

Revision as of 10:58, 7 July 2015

We recommend that all custom PHP logic be performed via hooks. Hooks are the only future-proof way of performing your own PHP logic at the time of page rendering.

Historically, Smarty has allowed you to define custom PHP logic directly within template files. This has often been used by users and third party developers as a quick and convenient way of performing additional logic and defining additional template output.

However, as of Smarty 3, support for the {php} block has been removed, and we are only providing legacy support to ease the transition for developers and users who work with our platform and rely on this functionality.

In WHMCS 6.0 and later, a backwards compatibility Security setting "Allow Smarty PHP Tags" has been introduced in Setup > General Settings > Security which must be checked to enable the use of PHP tags. This setting defaults to Off, and may be removed in a future versions.

Example Hook File

The below example demonstrates how a hook can be used to perform additional PHP logic and define template variables for use in client area template files.

This example below executes on the View Ticket page within the client area. There are hook points available for every page of the WHMCS client area that allow you to defined template variables in this way. For a full list, please refer to the Client Area Interface Hooks Index Listing

<?php
/**
 * Hook sample for defining additional template variables
 *
 * @param array $vars Existing defined template variables
 *
 * @return array
 */
function hook_template_variables_example($vars)
{
    $extraTemplateVariables = array();

    // set a fixed value
    $extraTemplateVariables['fixedValue'] = 'abc';

    // fetch clients data if available
    $clientsData = isset($vars['clientsdetails']) ? $vars['clientsdetails'] : null;

    // determine if client is logged in
    if (is_array($clientsData) && isset($clientsData['id'])) {
        $userId = $clientsData['id'];
        // perform calculation here
        $extraTemplateVariables['userSpecificValue'] = '123';
        $extraTemplateVariables['anotherUserOnlyValue'] = '456';
    }

    // return array of template variables to define
    return $extraTemplateVariables;
}

add_hook('ClientAreaPageViewTicket', 1, 'hook_template_variables_example');

The above hook defines the additional template variables {$fixedValue} - and, in the case of a logged in user, {$userSpecificValue} and {$anotherUserOnlyValue}. These can then be used inside the associated template file (in this case, viewticket.tpl) in the regular way.

<p>The fixed value is {$fixedValue}.</p>

{if $userSpecificValue && $anotherUserOnlyValue}
    <p>I also have this {$userSpecificValue} and {$anotherUserOnlyValue} to show you.</p>
{/if}

@@ Line 1: / Line 1: @@
-We strongly recommend that all custom PHP logic be performed via hooks.  Hooks are the only future-proof way of performing your own PHP logic at the time of page rendering.
+We recommend that all custom PHP logic be performed via hooks.  Hooks are the only future-proof way of performing your own PHP logic at the time of page rendering.
-Historically, Smarty has always allowed you to define custom PHP logic directly within template files.  This has often been used by users and third party developers as a quick and convenient way of performing additional logic and defining additional template output.
+Historically, Smarty has allowed you to define custom PHP logic directly within template files.  This has often been used by users and third party developers as a quick and convenient way of performing additional logic and defining additional template output.
 However, as of Smarty 3, support for the {php} block has been removed, and we are only providing legacy support to ease the transition for developers and users who work with our platform and rely on this functionality.
-<div class="docs-alert-info">
+<div class="docs-alert-warning">
-In WHMCS 6.0 and later, a Security setting "Allow Smarty PHP Tags" has been introduced in '''Setup > General Settings > Security''' which must be checked to enable the use of PHP tags.  At the time of writing, this setting defaults to On.  In the future, this setting will be defaulted to '''Off'''.
+In WHMCS 6.0 and later, a backwards compatibility Security setting "Allow Smarty PHP Tags" has been introduced in '''Setup > General Settings > Security''' which must be checked to enable the use of PHP tags.  This setting defaults to '''Off''', and may be removed in a future versions.
 </div>
-Below is an example of how a hook can be used to perform additional logic and define template variables for use in client area template files.
+==Example Hook File==
+The below example demonstrates how a hook can be used to perform additional PHP logic and define template variables for use in client area template files.
+<div class="docs-alert-info">This example below executes on the View Ticket page within the client area. There are hook points available for every page of the WHMCS client area that allow you to defined template variables in this way.  For a full list, please refer to the [[Hooks:Index#Client_Area_Interface|Client Area Interface Hooks Index Listing]]</div>
 <source lang="php">
@@ Line 42: / Line 46: @@
 }
-add_hook('ClientAreaPage', 1, 'hook_template_variables_example');
+add_hook('ClientAreaPageViewTicket', 1, 'hook_template_variables_example');
+</source>
+The above hook defines the additional template variables {$fixedValue} - and, in the case of a logged in user, {$userSpecificValue} and {$anotherUserOnlyValue}.  These can then be used inside the associated template file (in this case, viewticket.tpl) in the regular way.
+<source lang="php">
+<p>The fixed value is {$fixedValue}.</p>
+{if $userSpecificValue && $anotherUserOnlyValue}
+    <p>I also have this {$userSpecificValue} and {$anotherUserOnlyValue} to show you.</p>
+{/if}
 </source>

Documentation

Difference between revisions of "Templates and Custom PHP Logic"

Revision as of 10:58, 7 July 2015

Example Hook File