Helper Smarty

---

1Presentación

Este helper es útil para procesar templates Smarty dentro de una aplicación, para generar flujos (texto, HTML, XML u otro) fuera del procesamiento de vista del framework.

Al igual que la vista Smarty, este helper es compatible con las versiones 4 y 5 de la biblioteca Smarty. (Antes no era así: el helper estaba limitado a Smarty 4.)

Se instancia a través del componente de inyección de dependencias.

Su método render() recibe como parámetros la ruta del template Smarty que se debe usar (ruta absoluta o ruta relativa dentro del directorio templates/ del proyecto), y un array asociativo opcional que contiene las variables que deben quedar accesibles en el template.

Su método eval() se usa de forma similar, pero espera que el primer parámetro sea el contenido de un template Smarty, en lugar de una ruta a un archivo.

Su método templateExists() recibe como parámetro la ruta de un template, y devuelve un booleano que indica si el template existe o no.

---

2Uso

Ejemplo simple:

// definición del template
$template = 'path/to/template.tpl';

// datos del template
$data = [
	'var1' => 'value1',
	'var2' => 'value2',
];

// instanciación a través del loader
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

Ejemplo avanzado:

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

// datos del template
$data = [
	'name'   => 'Luke',
	'mentor' => 'Yoda',
];

try {
    // ruta del archivo del template
    $path = 'path/to/template.tpl';
    // procesamiento del template
    $html = $this->_loader['\Temma\Utils\Smarty']->render($path, $data);
} catch (TµIOException $e) {
    // variable que contiene código Smarty
    $smarty = "Hola {$name}, discípulo de {$mentor}";
    // procesamiento del template
    $html = $this->_loader['\Temma\Utils\Smarty']->eval($smarty, $data);
}

// comprueba la existencia de un archivo de template
if ($this->_loader['Temma\Utils\Smarty']->templateExists($path)) {
    print("El template existe.");
}

---

3Escape HTML

Al igual que en la vista Smarty, el auto-escape HTML de las variables está habilitado por defecto: las variables mostradas en los templates procesados por el helper se escapan automáticamente (los caracteres especiales <, >, &, etc. se convierten en entidades HTML). Antes no era así.

Este comportamiento se define globalmente mediante la sección de configuración x-smarty (clave autoEscape); consulta la sección de escape de la vista Smarty para más detalles.

Los métodos render() y eval() también aceptan un tercer parámetro opcional $autoEscape para forzar el comportamiento en una única llamada:

• true: fuerza el escape para esa llamada;
• false: desactiva el escape para esa llamada;
• null (valor por defecto): usa la configuración definida.

// renderización con la configuración definida (escape habilitado por defecto)
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

// renderización sin escape, solo para esta llamada
$raw = $this->_loader['\Temma\Utils\Smarty']->render($template, $data, false);

// el array de datos es opcional
$html = $this->_loader['\Temma\Utils\Smarty']->render($template);

---

4Plugins

El helper registra exactamente los mismos plugins de Smarty que la vista: los del directorio lib/smarty-plugins de tu proyecto, los de los directorios listados en la configuración x-smarty (clave pluginsDir), así como los plugins de temma-ui si está instalado.

Los modificadores y funciones personalizados que usas en tus templates están, por lo tanto, también disponibles en los templates procesados por el helper.