Smarty helper

---

1Presentation

This helper is useful for processing Smarty templates within an application, to generate feeds (text, HTML, XML or other) outside the framework's view processing.

Like the Smarty view, this helper is compatible with versions 4 and 5 of the Smarty library. (This was not the case before: the helper was limited to Smarty 4.)

It is instantiated via the dependency injection component.

Its render() method takes as parameters the path to the Smarty template to be used (absolute path or relative path under the project's templates/ directory), and an optional associative array containing the variables to be made accessible in the template.

Its eval() method is used in a similar way, but expects the first parameter to be the content of a Smarty template, rather than a path to a file.

Its templateExists() method takes as parameter the path to a template, and returns a boolean indicating whether the template exists or not.

---

2Usage

Simple example:

// template definition
$template = 'path/to/template.tpl';

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

// instanciation through the loader
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

Advanced example:

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

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

try {
    // template file's path
    $path = 'path/to/template.tpl';
    // template processing
    $html = $this->_loader['\Temma\Utils\Smarty']->render($path, $data);
} catch (TµIOException $e) {
    // variable containing Smarty code
    $smarty = "Hi {$name}, disciple of {$mentor}";
    // template processing
    $html = $this->_loader['\Temma\Utils\Smarty']->eval($smarty, $data);
}

// check the existence of a template file
if ($this->_loader['Temma\Utils\Smarty']->templateExists($path)) {
    print("The template exists.");
}

---

3HTML escaping

As in the Smarty view, HTML auto-escaping of variables is enabled by default: variables rendered in the templates processed by the helper are automatically escaped (the special characters <, >, &, etc. are converted into HTML entities). This was not the case before.

This behavior is set globally through the x-smarty configuration section (autoEscape key); see the escaping section of the Smarty view for details.

The render() and eval() methods also accept an optional third parameter $autoEscape to force the behavior for a single call:

• true: forces escaping for that call;
• false: disables escaping for that call;
• null (default value): uses the configured setting.

// rendering with the configured setting (escaping enabled by default)
$html = $this->_loader['\Temma\Utils\Smarty']->render($template, $data);

// rendering without escaping, for that call only
$raw = $this->_loader['\Temma\Utils\Smarty']->render($template, $data, false);

// the data array is optional
$html = $this->_loader['\Temma\Utils\Smarty']->render($template);

---

4Plugins

The helper registers exactly the same Smarty plugins as the view: those from your project's lib/smarty-plugins directory, those from the directories listed in the x-smarty configuration (pluginsDir key), as well as the temma-ui plugins if it is installed.

The custom modifiers and functions you use in your templates are therefore also available in the templates processed by the helper.