Loading...

Smarty basics

We no longer maintain the Knowledge Base since version 4.3.x. All the latest user and developer documentation for 4.3.x and newer versions is now available at docs.cs-cart.com.

  • This article applies to CS-Cart versions:
  • 3.0.x

Smarty is a template engine for PHP. It allows to separate application logic from its presentation. It is right for the situation when the programmer and the template designer of the project are not the same person.

Smarty has many key features; one of them is fast templates compiling. Smarty compiles *.tpl template files and then substitute variables and functions for specific values into the HTML document. So it provides more functionality to standard HTML.

For example:

before compiling

1
2
3
4
5
6
7
8
<html>
<head>
         <title>{$title_variable}</title>
</head>
<body>
         <h1>{$welcome_variable}<h1>
</body>
</html>

after compiling

1
2
3
4
5
6
7
8
<html>
<head>
         <title>This is the example page</title>
</head>
<body>
         <h1>Welcome<h1>
</body>
</html>

Smarty basic syntax

Tags
All Smarty template tags are enclosed in delimiters. By default, these delimiters are braces { and }.

Comments
Template comments are surrounded by asterisks and enclosed in braces as shown in the example below:

1
{* An example comment *}
Comments are used for making internal notes in the templates. Smarty does not support nested comments.

Functions
Each Smarty tag either prints a variable or invokes some sort of function. Functions are processed and displayed by enclosing the function and its attributes in the delimiters:

1
{funcname attribute1="value1" attribute2="value2"}

For example:

1
{include file="top.tpl"}
Both built-in functions and custom functions have the same syntax in the templates. Built-in functions are the inner workings of Smarty, such as section and strip. They cannot be modified. Custom functions are additional functions implemented via plug-ins. They can be modified to your liking, or you can add new ones.

Variables
Smarty has several different types of variables. The type of the variable depends on what symbol it is prefixed (or enclosed in). Variables in Smarty can be either displayed directly or used as arguments for function attributes and modifiers, inside conditional expressions, etc.

Variables that are assigned from PHP are referenced by preceding them with a dollar sign $. Variables assigned from within the template with the assign function are also displayed this way.

For example,

1
{$Name}
You can also specify the associative array that was assigned from PHP:
1
{$Contacts[row].Phone}

The reserved {$smarty} variable can be used to access several special template variables. For example {$smarty.config}, {$smarty.section}, {$smarty.template}, etc.

Associative arrays
You can also reference associative array variables that are assigned from PHP by specifying the key after the ’.’ (period) symbol.

For example:

.php file:

1
2
3
4
5
6
7
$view = new Smarty;
$view->assign(’Contacts’,
                 array(’fax’ => ’555-222-9876’,
                           'email’ => ’zaphod@slartibartfast.com’,
                           ’phone’ => array(’home’ => ’555-444-3333’,
                           ’cell’ => ’555-111-1234’)));
$view->display(’index.tpl’);

 

.tpl file:

1
2
3
4
5
{$Contacts.fax}<br>
{$Contacts.email}<br>
{* you can print arrays of arrays as well *}
{$Contacts.phone.home}<br>
{$Contacts.phone.cell}<br>

 

OUTPUT:

1
2
3
4
555-222-9876<br/>
zaphod@slartibartfast.com<br/>
555-444-3333<br/>
555-111-1234<br/>

 

Variable Modifiers
Variable modifiers can be applied to variables, custom functions or strings. To apply a modifier, specify the value followed by | (pipe) and the modifier name. A modifier may accept additional parameters that affect its behavior. These parameters follow the modifier name and are separated by : (colon).

For example,

1
2
3
4
5
6
7
8
9
10
11
{* Uppercase the title *}
<h2> {$title|upper} </h2>
 
{* Truncate the topic to 40 characters use ... at the end *}
Topic: {$topic|truncate:40:"..."}
 
{* format a literal string *}
{"now"|date_format:"%Y/%m/%d"}
 
{* apply modifier to a custom function *}
{mailto|upper address="me@domain.dom"}

Built-in functions

Capture
Capture is used to collect the output of the template into a variable instead of displaying it. Any content between {capture name="foo"} and {/capture} is collected into the variable specified by the name attribute. The captured content can be used in the template from the special variable smarty.capture.foo where foo is the value passed in the name attribute. If you do not supply a name attribute, then "default" will be used. All {capture} commands must be paired with {/capture}. You can nest capture commands.
1
2
3
4
5
6
7
8
9
10
11
{* we don’t want to print a table row unless content is displayed *}
{capture name=banner}
{include file="get_banner.tpl"}
{/capture}
{if $smarty.capture.banner ne ""}
 <tr>
     <td>
     {$smarty.capture.banner}
     </td>
 </tr>
{/if}

 

Foreach
Foreach is used to loop over a single associative array. Foreach tags must be paired with /foreach tags. Required parameters are from and item. The name of the foreach loop can be anything you like, made up of letters, numbers and underscores. Foreach loops can be nested, and the nested foreach names must be unique from each other. The from variable (usually an array of values) determines the number of times foreach will loop.
1
2
3
4
{* this example will print out all the values of the $custid array *}
{foreach from=$custid item=curr_id}
id: {$curr_id}<br>
{/foreach}

OUTPUT:
1
2
3
id: 1000<br/>
id: 1001<br/>
id: 1002<br/>

 

Include
Include tags are used for including other templates in the current template. Any variables available in the current template are also available within the included template. The include tag must have the attribute "file", which contains the template resource path.
1
2
{include file="blocks/products.tpl"}
{include file="blocks/shippings.tpl"}

 

If, elseif, else
Every if must be paired with an /if. Else and elseif are also permitted. "eq", "ne","neq", "gt", "lt", "lte", "le", "gte" "ge", "is even", "is odd", "is not even", "is not odd", "not", "mod", "div by", "even by", "odd by", "==", "!=", ">", "<", "<=", ">=" are all valid conditional qualifiers, and must be separated from surrounding elements by spaces.
1
2
3
{if $content == "news"}
      {include file="addons/news_and_emails/blocks/news.tpl"}
{/if}

For more information and extending your knowledge about Smarty you can use the following references:

http://smarty.net

http://smarty.net/download-docs.php - Smarty manuals.

 

<< Read previous Read next >>