Smarty view

1Presentation

Smarty is a popular template engine. It offers the advantage of a syntax that is easy to understand for non-computer scientists (graphic designers, web designers).
Start by looking at the presentation made in the introduction.

Here we will present you some basic instructions. For more information, please visit the Smarty documentation.

2Installation

This view is compatible with Smarty versions 4 and 5.

Please refer to the Temma installation documentation to find out how to install Smarty.

3Template files and inclusion

Template files are simple text files, which are intended to contain HTML code.

You can very easily segment your pages by making template inclusions.
For example, suppose you have two actions, list and show, which display different pages using the list.tpl and show.tpl files, respectively. If these two pages display the same page header, it is better to separate it so that you do not have to copy it on each page.
Smarty offers the possibility of including templates one inside the other thanks to the include statement.

So you could have the header.tpl file, which would look like this: 

<html>
<head>
    <title>Generic page title</title>
</head>
<body>

Our two page templates would then look like this: 

<!-- file list.tpl -->
{include file="header.tpl"}

<h1>LIST</h1>

</body>

<!-- file show.tpl -->
{include file="header.tpl"}

<h1>SHOW CONTENT</h1>

</body>

4Variables

One of the first needs is to be able to display the content of a variable.
Imagine that the controller contains the following code: 

$this['name'] = 'Anakin';

You can very simply display the value of the name variable in your template: 

{$name}

This will have the effect of displaying the following text: 

Anakin

5Lists

Let's say your controller sets a template variable that contains a list: 

$this['fruits'] = [
    'orange',
    'banana',
    'strawberry',
];

You can easily display any of the values in the list: 

{$fruits[2]}

And you will get: 

strawberry

6Associative arrays and objects

It is possible to display the content of an element of an associative array from its key, or of an attribute of an object from its name. For example: 

$this['colors'] = [
    'red'   => '#ff0000',
    'green' => '#00ff00',
    'blue'  => '#0000ff',
];

To display a color, just write: 

{$colors.red}

Which will give: 

#ff0000

7Conditions

To do conditional processing, you can use the if statement, which uses variables following the syntax seen previously.

For example, if your controller sets a template variable containing information for a user: 

$user = $this->_dao->get($userId);
$this['user'] = $user;

You will then be able to display a link only if the user is an administrator: 

{if $user.roles.admin}
    <a href="/user/show/{$user.id}">Voir mon compte</a>
{/if}

8Loops

Very often, you need to apply processing to a group of items. This usually takes the form of a list of items retrieved from the database, which you want to display one after the other.
To do this, Smarty offers the foreach instruction.

Imagine the controller retrieves a list of users from the database: 

$users = $this->_dao->search();
$this['users'] = $users;

It's very easy to loop through all users to display their name: 

<ul>
    {foreach $users as $user}
        <li>{$user.name}</li>
    {/foreach}
</ul>

9Escaping

If a variable contains special characters ("<", ">", "&", ...), you must not take the risk of writing it as is in the template, otherwise you will generate a non-HTML stream. compliant.
To achieve this, Temma enables Smarty's auto-escape option by default. This means that all special characters are automatically converted (< to &lt;, > to &gt;, & to &amp;, etc.).

For a variable not to be automatically escaped, the raw filter must be used.

Examples:

{$txt = "a & b"}
{* automatically escaped variable: writes "a & b" *}
{$txt}
{* variable not escaped: writes "a & b" *}
{$name|raw}

To disable auto-escape, add a directive to the x-smarty-view extended configuration (file etc/temma.php): 

<?php

return [
    'x-smarty-view' => [
        'autoEscape' => false
    ]
];

Smarty also offers the escape filter, which escapes special characters. By default, with auto-escape enabled, this modifier does nothing (there is no double escaping). But it is possible to use this modifier with different options (“htmlall”, “url”, “urlpathinfo”, “quotes”, “hex”, “hexentity”, “javascript”, “mail”) which will have an impact on the modified variable. It is also possible to use the “force” parameter, which will result in a double escape when auto-escape is enabled.

It is used as follows: 

{$name|escape}
{$user.name|escape:'hex'}
{$user.firstname|escape:'force'}

You cannot directly place curly braces ("{", "}") characters in a template, as they will be interpreted by Smarty statements. The literal instruction must therefore be used, which prevents the Smarty interpretation.

For example, to write JavaScript code in a page, you could write: 

{literal}
    <script type="text/javascript">
        function something() {
            ...
        }
    </script>
{/literal}

10Plugins

Smarty has its own plugin system, which allows for example to create data manipulation filters.

For example, you could create a filter that is used to replace all the letters "T" by a dot (it is useless, but it is for the example): 

function smarty_modifier_warp($text) {
    return str_replace('T', '.', $text);
}

You would use it like this in your templates: 

{$variable|warp}

For your plugin to be usable by Smarty, you must place your function in a file named modifier.warp.php. This must be located in the lib/smarty-plugins directory of your project.
In case you have another directory containing Smarty plugins, you will need to add its path in the project configuration (file etc/temma.php): 

<?php

return [
    'x-smarty-view' => [
        'pluginsDir' => '/path/to/the/directory'
    ]
];

If you have multiple directories containing Smarty plugins, you can list them all: 

<?php

return [
    'x-smarty-view' => [
        'pluginsDir' => [
            '/path/to/the/directory1',
            '/path/to/the/directory2',
            '/path/to/the/directory3',
        ]
    ]
];