Difference between revisions of "Template Syntax"

Revision as of 15:32, 4 August 2015

The basic template syntax can be seen by looking at the templates. Template files simply use regular HTML along with tags for where the WHMCS data is inserted into them. All pages have specific variables which you can use. To view a complete list of variables available on a given page, enter the following tag into the template file:

{debug}

When you next access the page containing that template file in your browser after adding this code, a popup window will appear showing you all the different variables which you can use on the page. Variables can be accessed using the {$variable} syntax.

Common Template Variables Available on All Pages

The following is a list of template variables available for use in all the template files of WHMCS

{$BASE_PATH_CSS} - The base URL to common CSS assets.
{$BASE_PATH_FONTS} - The base URL to common font assets.
{$BASE_PATH_IMG} - The base URL to common image assets.
{$BASE_PATH_JS} - The base URL to common Javascript assets.
{$charset} - Your configured character set.
{$client} - The currently logged in Client, or null if a client is not logged in.
{$companyname} - Your configured company name
{date_day} - The current calendar day.
{date_month} - The current calendar month.
{date_year} - The current calendar year.
{filename} - The basename of the current file requested by the web browser.
{$language} - The name of the language to display to the user.
{$loggedin} - true or false depending on whether or not a client is logged in.
{$logo} - The path to your configured logo image.
{$pagetitle} - The current page's title.
{$reCaptchaPublicKey} - Your configured reCAPTCHA site key, or an empty string if your WHMCS installation does not use Google reCAPTCHA.
{$systemNonSSLURL} - Your configured non-SSL URL.
{$systemsslurl} - Your configured SSL URL.
{$systemurl} - The URL to your WHMCS system, either the SSL or non-SSL URL depending on whether the current page is accessed via HTTPS.
{$template} - The name of the template used for display.
{$todaysdate} - The current date, presented in "l, jS F Y" format.
{$token} - A CSRF token to use on POST forms.
{$WEB_ROOT} - Your WHMCS system's base URL.

Custom Template Variables

Not all variables are available on every page, and if the variable you wish to use isn't there, then you would need to obtain this yourself.

Hooks:EmailPreSend can be used to create your own smarty variables to use on email templates.

Displaying Text to Logged In Users Only

To display something on the page only if a user is logged in, use the following syntax:

{if $loggedin}
    <p>User is logged in so display client only information</p>
{else}
    <p>User is not logged in so display this</p>
{/if}

Displaying Text if Certain Conditions Are Met

In a similar vein it can be useful to display things only if certain conditions are met. For example you might want to display card scheme logos associated with your different payment gateways, or show information based upon what is displayed on the page. This is done using if commands:

{if $gateway.name eq "PayPal"}We accept PayPal{/if}

Would display the message "We accept PayPal" if that option is available on the checkout page. This can be used for any variable.

Translating Language Strings

WHMCS provides the {lang} function for custom templates to present text in your users' configured language. Call it with the "key" parameter representing the key in the language to translate.

{** 
 * Defined as $_LANG['forgotpw'] in language files:
 *
 * Display "<strong>Forgot Password?</strong>" in English
 * or "<strong>¿Perdiste la contraseña?</strong>" in Spanish.
 *}
<strong>{lang key="forgotpw"}</strong>

Use dots (".") to concatenate nested language keys.

{** 
 * Defined as $_LANG['clientHomePanels']['unpaidInvoices'] in language files:
 *
 * Display "<strong>Unpaid Invoices</strong>" in English
 * or "<strong>Facturas Pendientes</strong>" in Spanish.
 *}
<strong>{lang key="clientHomePanels.unpaidInvoices"}</strong>

Some language strings contain variable substitution. Variables for substitution begin with a colon (":"). Declare those variables and their values as parameters to the {lang} function:

{**
 * Defined as $_LANG['clientHomePanels']['creditBalance'] in language files:
 *
 * Display "<p>You have a credit balance of $100.00.</p>" in English
 * or "<p>Usted tiene un saldo acreedor de $100.00.</p>" in Spanish.
 *}
<p>{lang key="clientHomePanels.creditBalance" creditBalance="$100"}</p>

More Information

For further documentation on template customisations, see the official Smarty 3 documentation @ http://www.smarty.net/docs/en/

@@ Line 9: / Line 9: @@
 The following is a list of template variables available for use in all the template files of WHMCS
-*{$companyname} - Company Name
+*{$BASE_PATH_CSS} - The base URL to common CSS assets.
-*{$pagetitle} - Current Pages Title
+*{$BASE_PATH_FONTS} - The base URL to common font assets.
-*{$template} - Template Name
+*{$BASE_PATH_IMG} - The base URL to common image assets.
-*{$charset} - Current Charset Setting
+*{$BASE_PATH_JS} - The base URL to common Javascript assets.
-*{$todaysdate} - Formatted Date
+*{$charset} - Your configured character set.
-*{$systemurl} - URL to WHMCS System
+*{$client} - The currently logged in [http://docs.whmcs.com/classes/classes/WHMCS.User.Client.html Client], or ''null'' if a client is not logged in.
-*{$loggedin} - True if logged in
+*{$companyname} - Your configured company name
+*{date_day} - The current calendar day.
-*{$clientsdetails.id} - Currently Logged in Users Details
+*{date_month} - The current calendar month.
-*{$clientsdetails.firstname}
+*{date_year} - The current calendar year.
-*{$clientsdetails.lastname}
+*{filename} - The basename of the current file requested by the web browser.
+*{$language} - The name of the language to display to the user.
+*{$loggedin} - ''true'' or ''false'' depending on whether or not a client is logged in.
+*{$logo} - The path to your configured logo image.
+*{$pagetitle} - The current page's title.
+*{$reCaptchaPublicKey} - Your configured [https://www.google.com/recaptcha/intro/index.html reCAPTCHA] site key, or an empty string if your WHMCS installation does not use Google reCAPTCHA.
+*{$systemNonSSLURL} - Your configured non-SSL URL.
+*{$systemsslurl} - Your configured SSL URL.
+*{$systemurl} - The URL to your WHMCS system, either the SSL or non-SSL URL depending on whether the current page is accessed via HTTPS.
+*{$template} - The name of the template used for display.
+*{$todaysdate} - The current date, presented in "l, jS F Y" format.
+*{$token} - A [https://en.wikipedia.org/wiki/Cross-site_request_forgery CSRF] token to use on POST forms.
+*{$WEB_ROOT} - Your WHMCS system's base URL.
 ===Custom Template Variables===
@@ Line 25: / Line 37: @@
 [[Hooks:EmailPreSend]] can be used to create your own smarty variables to use on email templates.
-==Using curly braces for literal statements==
-If you end up using (for example) JS in your templates in-line (instead of using src="#"), you may not get the results that you'd expect. Your smarty template will fail and you will either receive a blank page or an error page (depending on your configuration). To prevent this from happening, you can execute code by using the {literal} tag.
-Example:
-<source lang="php">
-  {literal}
-  <script type="text/javascript">
-  function myFunc(args) {
-    alert('Hello, world');
-  }
-  </script>
-  {/literal}
-</source>
-Everything within the {literal} {/literal} tags will not be parsed (such as the template variables above). However, you would be able to accomplish adding the template variables by using multiple literal statements, such as this:
-<source lang="php">
-  {literal}
-  <script type="text/javascript">
-  function myFunc(args) {
-    alert('Hello, {/literal}{$clientsdetails.firstname} {$clientsdetails.lastname}{literal}')
-  }
-  {/literal}
-</source>
 ==Displaying Text to Logged In Users Only==
 To display something on the page only if a user is logged in, use the following syntax:
-<source lang="php">
+<syntaxhighlight lang="smarty">
- {if $loggedin}
+{if $loggedin}
- User is logged in so display client only information
+    <p>User is logged in so display client only information</p>
- {else}
+{else}
- User is not logged in so display this
+    <p>User is not logged in so display this</p>
- {/if}
+{/if}
-</source>
+</syntaxhighlight>
 ==Displaying Text if Certain Conditions Are Met==
@@ Line 68: / Line 53: @@
 In a similar vein it can be useful to display things only if certain conditions are met. For example you might want to display card scheme logos associated with your different payment gateways, or show information based upon what is displayed on the page. This is done using if commands:
-<source lang="php">{if $gateway.name eq "PayPal"}We accept PayPal{/if}</source>
+<syntaxhighlight lang="smarty">{if $gateway.name eq "PayPal"}We accept PayPal{/if}</syntaxhighlight>
 Would display the message "We accept PayPal" if that option is available on the checkout page. This can be used for any variable.
-==Using PHP Code within Templates==
+==Translating Language Strings==
+WHMCS provides the '''{lang}''' function for custom templates to present text in your users' configured language. Call it with the "key" parameter representing the key in the language to translate.
+<syntaxhighlight lang="smarty">
+{**
+ * Defined as $_LANG['forgotpw'] in language files:
+ *
+ * Display "<strong>Forgot Password?</strong>" in English
+ * or "<strong>¿Perdiste la contraseña?</strong>" in Spanish.
+ *}
+<strong>{lang key="forgotpw"}</strong>
+</syntaxhighlight>
-With the powerful templating system included in WHMCS, it is possible to execute your own PHP code within the templates.  This can be used to include other files, run custom functions, integrate with remote systems, etc...  To do this you simply use {php}...{/php} tags around a section of PHP code in place of the normal <?php ?> tags.
+Use dots (".") to concatenate nested language keys.
-One of the most common reasons for using PHP code in the templates is to query the database for additional information.  An example of how this can be done is below.
+<syntaxhighlight lang="smarty">
+{**
+ * Defined as $_LANG['clientHomePanels']['unpaidInvoices'] in language files:
+ *
+ * Display "<strong>Unpaid Invoices</strong>" in English
+ * or "<strong>Facturas Pendientes</strong>" in Spanish.
+  *}
+<strong>{lang key="clientHomePanels.unpaidInvoices"}</strong>
+</syntaxhighlight>
-<source lang="php">
+Some language strings contain variable substitution. Variables for substitution begin with a colon (":"). Declare those variables and their values as parameters to the '''{lang}''' function:
- {php}
- $userid = $this->_tpl_vars['clientsdetails']['userid'];
- $result = mysql_query("SELECT firstname FROM tblclients WHERE id=$userid");
- $data = mysql_fetch_array($result);
- $firstname = $data["firstname"];
- echo $firstname;
- {/php}
-</source>
-The first line in the above code is also demonstrating how you can retrieve and use template variables within your custom PHP code.
+<syntaxhighlight lang="smarty">
+{**
+ * Defined as $_LANG['clientHomePanels']['creditBalance'] in language files:
+ *
+ * Display "<p>You have a credit balance of $100.00.</p>" in English
+ * or "<p>Usted tiene un saldo acreedor de $100.00.</p>" in Spanish.
+ *}
+<p>{lang key="clientHomePanels.creditBalance" creditBalance="$100"}</p>
+</syntaxhighlight>
 ==More Information==
-For further documentation on template customisations, see the official Smarty documentation @ http://smarty.net/docs.php
+For further documentation on template customisations, see the official Smarty 3 documentation @ http://www.smarty.net/docs/en/
 {{Developer_Links}}

Documentation