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.net website.

2Template 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>

3Variables

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

4Lists

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

5Associative 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

6Conditions

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}

7Loops

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>

8Escaping

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.
For this, Smarty offers the escape filter, which converts the characters in question on the fly.

It is used as follows: 

{$name|escape}
{$user.name|escape}

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}

9Plugins

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 (etc/temma.php file): 

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

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

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