Vista Smarty

1Presentación

Smarty es un motor de plantillas popular. Ofrece la ventaja de una sintaxis fácil de entender para personas sin formación informática (diseñadores gráficos, diseñadores web).
Empieza por consultar la presentación hecha en la introducción.

Aquí te presentaremos algunas instrucciones básicas. Para más información, visita la documentación de Smarty.

2Instalación

Esta vista es compatible con las versiones 4 y 5 de Smarty.

Consulta la documentación de instalación de Temma para saber cómo instalar Smarty.

3Archivos de plantilla e inclusión

Los archivos de plantilla son simples archivos de texto, destinados a contener código HTML.

Puedes segmentar tus páginas muy fácilmente haciendo inclusiones de plantillas.
Por ejemplo, supongamos que tienes dos acciones, list y show, que muestran páginas diferentes usando respectivamente los archivos list.tpl y show.tpl. Si estas dos páginas muestran la misma cabecera de página, es mejor separarla para no tener que copiarla en cada página.
Smarty ofrece la posibilidad de incluir plantillas unas dentro de otras gracias a la instrucción include.

Así, podrías tener el archivo header.tpl, que se vería así: 

<html>
<head>
    <title>Título genérico de página</title>
</head>
<body>

Nuestras dos plantillas de página se verían entonces así: 

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

<h1>LISTA</h1>

</body>

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

<h1>MOSTRAR CONTENIDO</h1>

</body>

4Variables

Una de las primeras necesidades es poder mostrar el contenido de una variable.
Imagina que el controlador contiene el siguiente código: 

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

Puedes mostrar muy fácilmente el valor de la variable name en tu plantilla: 

{$name}

Esto tendrá el efecto de mostrar el siguiente texto: 

Anakin
Por defecto, todas las variables de plantilla (que no empiecen con un guion bajo) se pasan a Smarty. También es posible definir una variable de plantilla @output que contenga un array asociativo; en ese caso, solo los pares clave-valor de ese array se pasarán a Smarty como variables de plantilla.

5Listas

Supongamos que tu controlador define una variable de plantilla que contiene una lista: 

$this['fruits'] = [
    'naranja',
    'plátano',
    'fresa',
];

Puedes mostrar fácilmente cualquiera de los valores de la lista: 

{$fruits[2]}

Y obtendrás: 

fresa

6Arrays asociativos y objetos

Es posible mostrar el contenido de un elemento de un array asociativo a partir de su clave, o de un atributo de un objeto a partir de su nombre. Por ejemplo: 

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

Para mostrar un color, basta con escribir: 

{$colors.red}

Lo que dará: 

#ff0000

7Condiciones

Para hacer un tratamiento condicional, puedes usar la instrucción if, que usa variables siguiendo la sintaxis vista anteriormente.

Por ejemplo, si tu controlador define una variable de plantilla que contiene información de un usuario: 

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

Entonces podrás mostrar un enlace solo si el usuario es administrador: 

{if $user.roles.admin}
    <a href="/user/show/{$user.id}">Ver mi cuenta</a>
{/if}

8Bucles

Muy a menudo, necesitas aplicar un tratamiento a un grupo de elementos. Esto suele tomar la forma de una lista de elementos obtenidos de la base de datos, que quieres mostrar uno tras otro.
Para hacerlo, Smarty ofrece la instrucción foreach.

Imagina que el controlador obtiene una lista de usuarios de la base de datos: 

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

Es muy fácil recorrer todos los usuarios para mostrar su nombre: 

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

9Escape

Si una variable contiene caracteres especiales ("<", ">", "&", ...), no debes arriesgarte a escribirla tal cual en la plantilla, ya que de lo contrario generarás un flujo HTML no conforme.
Para lograrlo, Temma activa por defecto la opción de auto-escape de Smarty. Esto significa que todos los caracteres especiales se convierten automáticamente (< en &lt;, > en &gt;, & en &amp;, etc.).

Para que una variable no se escape automáticamente, debe usarse el filtro raw.

Ejemplos:

{$txt = "a & b"}
{* variable escapada automáticamente: escribe "a & b" *}
{$txt}
{* variable no escapada: escribe "a & b" *}
{$name|raw}

Para desactivar el auto-escape, añade una directiva a la configuración extendida x-smarty (archivo etc/temma.php): 

<?php

return [
    'x-smarty' => [
        'autoEscape' => false
    ]
];
La sección x-smarty es la forma recomendada de configurar Smarty (claves autoEscape y pluginsDir). La antigua sección x-smarty-view todavía se acepta por compatibilidad retroactiva, pero está obsoleta y se eliminará en una futura versión mayor. El mecanismo de respaldo es por clave: para cada parámetro, Temma usa el valor definido en x-smarty si está presente, o si no el de x-smarty-view. Las configuraciones existentes, por tanto, siguen funcionando sin ningún cambio.

Smarty también ofrece el filtro escape, que escapa los caracteres especiales. Por defecto, con el auto-escape activado, este modificador no hace nada (no hay doble escape). Pero es posible usar este modificador con diferentes opciones (“htmlall”, “url”, “urlpathinfo”, “quotes”, “hex”, “hexentity”, “javascript”, “mail”) que tendrán un impacto en la variable modificada. También es posible usar el parámetro “force”, que provocará un doble escape cuando el auto-escape esté activado.

Se usa de la siguiente manera: 

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

No puedes colocar directamente caracteres de llave ("{", "}") en una plantilla, ya que serán interpretados por las instrucciones de Smarty. Por tanto, debe usarse la instrucción literal, que impide la interpretación por parte de Smarty.

Por ejemplo, para escribir código JavaScript en una página, podrías escribir: 

{literal}
    <script>
        function something() {
            ...
        }
    </script>
{/literal}

10Plugins

Smarty tiene su propio sistema de plugins, que permite por ejemplo crear filtros de manipulación de datos.

Por ejemplo, podrías crear un filtro que se use para reemplazar todas las letras "T" por un punto (no sirve de nada, pero es para el ejemplo): 

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

Lo usarías así en tus plantillas: 

{$variable|warp}

Para que tu plugin sea utilizable por Smarty, debes colocar tu función en un archivo llamado modifier.warp.php. Este debe ubicarse en el directorio lib/smarty-plugins de tu proyecto.
Si tienes otro directorio que contenga plugins de Smarty, deberás añadir su ruta en la configuración del proyecto (archivo etc/temma.php): 

<?php

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

Si tienes varios directorios que contienen plugins de Smarty, puedes listarlos todos: 

<?php

return [
    'x-smarty' => [
        'pluginsDir' => [
            '/path/to/the/directory1',
            '/path/to/the/directory2',
            '/path/to/the/directory3',
        ]
    ]
];
Al igual que con el auto-escape, la clave pluginsDir se define ahora en la sección x-smarty. La antigua sección x-smarty-view todavía se acepta pero está obsoleta (respaldo por clave).