Visão Smarty

1Apresentação

Smarty é um motor de templates popular. Ele oferece a vantagem de uma sintaxe fácil de entender para pessoas que não são da área de computação (designers gráficos, web designers).
Comece observando a apresentação feita na introdução.

Aqui vamos apresentar algumas instruções básicas. Para mais informações, visite a documentação do Smarty.

2Instalação

Essa visão é compatível com as versões 4 e 5 do Smarty.

Consulte a documentação de instalação do Temma para saber como instalar o Smarty.

3Arquivos de template e inclusão

Os arquivos de template são simples arquivos de texto, destinados a conter código HTML.

Você pode segmentar suas páginas muito facilmente fazendo inclusões de templates.
Por exemplo, suponha que você tenha duas ações, list e show, que exibem páginas diferentes usando os arquivos list.tpl e show.tpl, respectivamente. Se essas duas páginas exibem o mesmo cabeçalho de página, é melhor separá-lo para não ter que copiá-lo em cada página.
O Smarty oferece a possibilidade de incluir templates uns dentro dos outros graças à instrução include.

Assim, você poderia ter o arquivo header.tpl, que ficaria assim: 

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

Nossos dois templates de página ficariam então assim: 

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

<h1>LISTA</h1>

</body>

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

<h1>EXIBIR CONTEÚDO</h1>

</body>

4Variáveis

Uma das primeiras necessidades é poder exibir o conteúdo de uma variável.
Imagine que o controlador contenha o seguinte código: 

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

Você pode exibir de forma muito simples o valor da variável name no seu template: 

{$name}

Isso terá o efeito de exibir o seguinte texto: 

Anakin
Por padrão, todas as variáveis de template (que não começam com um underscore) são passadas ao Smarty. Também é possível definir uma variável de template @output contendo um array associativo; nesse caso, apenas os pares chave-valor desse array serão passados ao Smarty como variáveis de template.

5Listas

Digamos que seu controlador defina uma variável de template contendo uma lista: 

$this['fruits'] = [
    'laranja',
    'banana',
    'morango',
];

Você pode facilmente exibir qualquer um dos valores da lista: 

{$fruits[2]}

E você obterá: 

morango

6Arrays associativos e objetos

É possível exibir o conteúdo de um elemento de um array associativo a partir de sua chave, ou de um atributo de um objeto a partir de seu nome. Por exemplo: 

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

Para exibir uma cor, basta escrever: 

{$colors.red}

O que resultará em: 

#ff0000

7Condições

Para fazer processamento condicional, você pode usar a instrução if, que usa variáveis seguindo a sintaxe vista anteriormente.

Por exemplo, se o seu controlador definir uma variável de template contendo informações de um usuário: 

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

Você poderá então exibir um link apenas se o usuário for um administrador: 

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

8Laços

Frequentemente, você precisa aplicar um processamento a um grupo de itens. Isso geralmente toma a forma de uma lista de itens recuperados do banco de dados, que você deseja exibir um após o outro.
Para isso, o Smarty oferece a instrução foreach.

Imagine que o controlador recupere uma lista de usuários do banco de dados: 

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

É muito fácil percorrer todos os usuários para exibir seus nomes: 

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

9Escapamento

Se uma variável contiver caracteres especiais ("<", ">", "&", ...), você não deve correr o risco de escrevê-la tal como está no template, caso contrário você gerará um fluxo HTML não compatível.
Para conseguir isso, o Temma ativa por padrão a opção de auto-escape do Smarty. Isso significa que todos os caracteres especiais são convertidos automaticamente (< para &lt;, > para &gt;, & para &amp;, etc.).

Para que uma variável não seja escapada automaticamente, deve-se usar o filtro raw.

Exemplos:

{$txt = "a & b"}
{* variável escapada automaticamente: escreve "a & b" *}
{$txt}
{* variável não escapada: escreve "a & b" *}
{$name|raw}

Para desativar o auto-escape, adicione uma diretriz à configuração estendida x-smarty (arquivo etc/temma.php): 

<?php

return [
    'x-smarty' => [
        'autoEscape' => false
    ]
];
A seção x-smarty é a forma recomendada de configurar o Smarty (chaves autoEscape e pluginsDir). A antiga seção x-smarty-view ainda é aceita para compatibilidade retroativa, mas está obsoleta e será removida em uma futura versão principal. O fallback é feito por chave: para cada configuração, o Temma usa o valor definido em x-smarty se presente, ou então o de x-smarty-view. As configurações existentes, portanto, continuam funcionando sem nenhuma alteração.

O Smarty também oferece o filtro escape, que escapa caracteres especiais. Por padrão, com o auto-escape ativado, esse modificador não faz nada (não há escape duplo). Mas é possível usar esse modificador com diferentes opções ("htmlall", "url", "urlpathinfo", "quotes", "hex", "hexentity", "javascript", "mail") que terão impacto sobre a variável modificada. Também é possível usar o parâmetro "force", que resultará em um escape duplo quando o auto-escape estiver ativado.

É usado da seguinte forma: 

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

Você não pode colocar diretamente caracteres de chave ("{", "}") em um template, pois eles serão interpretados como instruções do Smarty. A instrução literal deve, portanto, ser usada, o que impede a interpretação pelo Smarty.

Por exemplo, para escrever código JavaScript em uma página, você poderia escrever: 

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

10Plugins

O Smarty tem seu próprio sistema de plugins, que permite, por exemplo, criar filtros de manipulação de dados.

Por exemplo, você poderia criar um filtro usado para substituir todas as letras "T" por um ponto (é inútil, mas é para fins de exemplo): 

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

Você o usaria assim em seus templates: 

{$variable|warp}

Para que seu plugin seja utilizável pelo Smarty, você deve colocar sua função em um arquivo chamado modifier.warp.php. Ele deve estar localizado no diretório lib/smarty-plugins do seu projeto.
Caso você tenha outro diretório contendo plugins Smarty, será necessário adicionar seu caminho na configuração do projeto (arquivo etc/temma.php): 

<?php

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

Se você tiver vários diretórios contendo plugins Smarty, pode listá-los todos: 

<?php

return [
    'x-smarty' => [
        'pluginsDir' => [
            '/path/to/the/directory1',
            '/path/to/the/directory2',
            '/path/to/the/directory3',
        ]
    ]
];
Assim como no auto-escape, a chave pluginsDir agora é definida na seção x-smarty. A antiga seção x-smarty-view ainda é aceita, mas está obsoleta (fallback por chave).