Helper Smarty

---

1Apresentação

Este helper é útil para processar templates Smarty dentro de uma aplicação, para gerar fluxos (texto, HTML, XML ou outro) fora do processamento de visão do framework.

Assim como a visão Smarty, este helper é compatível com as versões 4 e 5 da biblioteca Smarty. (Isso não acontecia antes: o helper era limitado ao Smarty 4.)

Ele é instanciado através do componente de injeção de dependências.

Seu método render() recebe como parâmetros o caminho para o template Smarty a ser usado (caminho absoluto ou caminho relativo dentro do diretório templates/ do projeto), e um array associativo opcional contendo as variáveis que devem ficar acessíveis no template.

Seu método eval() é usado de forma similar, mas espera que o primeiro parâmetro seja o conteúdo de um template Smarty, em vez de um caminho para um arquivo.

Seu método templateExists() recebe como parâmetro o caminho para um template, e retorna um booleano indicando se o template existe ou não.

---

2Uso

Exemplo simples:

// definição do template
$template = 'path/to/template.tpl';

// dados do template
$data = [
	'var1' => 'value1',
	'var2' => 'value2',
];

// instanciação através do loader
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

Exemplo avançado:

use \Temma\Exceptions\IO as TµIOException;

// dados do template
$data = [
	'name'   => 'Luke',
	'mentor' => 'Yoda',
];

try {
    // caminho do arquivo do template
    $path = 'path/to/template.tpl';
    // processamento do template
    $html = $this->_loader['\Temma\Utils\Smarty']->render($path, $data);
} catch (TµIOException $e) {
    // variável contendo código Smarty
    $smarty = "Hi {$name}, disciple of {$mentor}";
    // processamento do template
    $html = $this->_loader['\Temma\Utils\Smarty']->eval($smarty, $data);
}

// verifica a existência de um arquivo de template
if ($this->_loader['Temma\Utils\Smarty']->templateExists($path)) {
    print("O template existe.");
}

---

3Escape HTML

Assim como na visão Smarty, o auto-escape HTML das variáveis está habilitado por padrão: as variáveis renderizadas nos templates processados pelo helper são automaticamente escapadas (os caracteres especiais <, >, &, etc. são convertidos em entidades HTML). Isso não acontecia antes.

Esse comportamento é definido globalmente através da seção de configuração x-smarty (chave autoEscape); veja a seção de escape da visão Smarty para mais detalhes.

Os métodos render() e eval() também aceitam um terceiro parâmetro opcional $autoEscape para forçar o comportamento em uma única chamada:

• true: força o escape para essa chamada;
• false: desabilita o escape para essa chamada;
• null (valor padrão): utiliza a configuração definida.

// renderização com a configuração definida (escape habilitado por padrão)
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

// renderização sem escape, apenas para essa chamada
$raw = $this->_loader['\Temma\Utils\Smarty']->render($template, $data, false);

// o array de dados é opcional
$html = $this->_loader['\Temma\Utils\Smarty']->render($template);

---

4Plugins

O helper registra exatamente os mesmos plugins Smarty que a visão: os do diretório lib/smarty-plugins do seu projeto, os dos diretórios listados na configuração x-smarty (chave pluginsDir), além dos plugins do temma-ui, caso esteja instalado.

Os modificadores e funções personalizados que você usa em seus templates ficam, portanto, também disponíveis nos templates processados pelo helper.