Documentation

Smarty view

Table of Contents ▼

Presentation

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.

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

Variables

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

Lists

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

Associative 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

Conditions

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}

Loops

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>

Escaping

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}

Plugins

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.json 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"
        ]
    }
}
Previous: Views
Next: JSON view

Table of Contents

  1. Migration : How to upgrade from Temma 1.x to version 2
  2. Installation : Download Temma and install it to start your web project
  3. Configuration : All the configuration directives of the etc/temma.json file and the optional environment variables
  4. External libraries : How to use external function libraries
  5. Routing : Temma's default routing system, and advanced routing
  6. Log : Use of the log system, management by criticality levels
  7. Controllers : Essential parts of your web application
  8. Views : Smarty templates or JSON/CSV/RSS/iCal/INI exports
    1. Smarty : Default view, based on Smarty templates
    2. JSON : JSON export, with or without data validation
    3. CSV : CSV export
    4. RSS : RSS stream export
    5. INI : INI-format export
    6. iCal : iCal calendar export
  9. Dependency injection : The backbone of your application developments
  10. Sessions : Extension of user sessions managed by PHP
  11. Data sources : Unified data access management
  12. Model : How to use DAOs to access databases
  13. Execution flow : How to manage the execution flow, between plugins and the controller
  14. Plugins : How to use plugins, and create your own plugins to modularize your code
  15. Attributes : How to filter access to controllers and actions
  16. Tests : To write automated integration tests.
  17. Command-line interface : To create executable scripts on the command line, automatically initialized by Temma
  18. Helpers : Items offered by Temma to help you in various circumstances