Latte pro vývojáře

Jak vykreslit šablonu

Jak vykreslit šablonu? Stačí spustit tento kód:

$latte = new Latte\Engine;

$latte->setTempDirectory('/path/to/tempdir');

$params = [
	'items' => ['one', 'two', 'three'],
];

// kresli na výstup
$latte->render('template.latte', $params);
// kresli do řetězce
$html = $latte->renderToString('template.latte', $params);

Latte automaticky přegenerovává cache při každé změně šablony, což můžeme v produkčním prostředí vypnout a ušetřit tím malinko výkonu:

$latte->setAutoRefresh(false);

Místo pole $params můžete také použít objekt, což přináší některé výhody. Získáte pohodlné napovídání v IDE a cestu pro registraci filtrů a funkcí:

class MyTemplate
{
	public $items = ['one', 'two', 'three'];
}

$params = new MyTemplate;
$latte->render('template.latte', $params);

Načítání šablon z řetězce

Pokud nemáme naši šablonu uloženou v souboru, ale pouze v proměnných, musíme nastavit loader na Latte\Loaders\StringLoader.

$latte->setLoader(new Latte\Loaders\StringLoader([
	'main.file' => '{include other.file}',
	'other.file' => '{if true} {$var} {/if}',
]));

$latte->render('main.file', $params);

Vlastní filtr

Jako filtr lze do šablony zaregistrovat libovolný callback:

$latte = new Latte\Engine;
$latte->addFilter('shortify', function (string $s): string {
	return mb_substr($s, 0, 10); // zkrátí text na 10 písmen
});

V tomto případě by bylo šikovnější, kdyby filtr přijímal další parametr:

$latte->addFilter('shortify', function (string $s, int $len = 10): string {
	return mb_substr($s, 0, $len);
});

V šabloně se potom volá takto:

<p>{$text|shortify}</p>
<p>{$text|shortify:100}</p>

Druhým způsobem definice filtru je třída šablony. Důležité je uvést anotaci @filter:

class MyTemplate
{
	/** @filter */
	public function shortify(string $s, int $len = 10): string
	{
		return mb_substr($s, 0, $len); // zkrátí text na 10 písmen
	}
}

$params = new MyTemplate;
...
$latte->render('template.latte', $params);

Univerzální filtr

Manuální registraci více filtrů lze nahradit registrací jednoho univerzálního:

$latte->addFilter(null, 'Filters::common');

Ten dostane jako parametr název požadovaného filtru:

class Filters
{
	public static function common($filter, $value)
	{
		if (method_exists(__CLASS__, $filter)) {
			$args = func_get_args();
			array_shift($args);
			return call_user_func_array([__CLASS__, $filter], $args);
		}
	}

	public static function shortify($s, $len = 10)
	{
		return mb_substr($s, 0, $len);
	}
}

Escapování

Řetězec, který filtr přijímá na vstupu a vrací na výstupu, je standardně plain text v UTF‑8. V případě, že filtr vrací HTML, zabalí řetězec do objektu Latte\Runtime\Html, aby nedošlo k nežádoucímu automatickému escapování v šabloně:

$latte->addFilter('money', function (int $num): string {
	return new Latte\Runtime\Html("<i>$num Kč</i");
});

Filtr musí zajistit správné escapování dat.

Blokové filtry

Filtry, které se používají na bloky (např. anonymní bloky) dostávají informaci o typu obsahu a kontextu v objektu Latte\Runtime\FilterInfo, který se předává jako první parameter. Filtr by měl nejprve ověřit, že daný content type podporuje:

use Latte\Engine;
use Latte\Runtime\FilterInfo;

$latte->addFilter('tidyHtml', function (FilterInfo $info, string $s): string {
	// ověříme, že v $s je HTML text
	if ($info->contentType !== Engine::CONTENT_HTML) {
		throw new Exception('Filter |tidyHtml used in incompatible content type.');
	}
	...
});

U těch filtrů se nepoužívá zabalení do objektu Latte\Runtime\Html, informace o typu se vrací v objektu $info. Tj. pokud vrací data v jiném typu, změní hodnotu v $info:

$info->contentType = Engine::CONTENT_TEXT;

Rozlišují se následující typy a jejich kontexty:

use Latte\Engine;
use Latte\Compiler;

Engine::CONTENT_TEXT
Engine::CONTENT_HTML . Compiler::CONTEXT_HTML_TEXT
Engine::CONTENT_HTML . Compiler::CONTEXT_HTML_TAG
Engine::CONTENT_HTML . Compiler::CONTEXT_HTML_ATTRIBUTE
Engine::CONTENT_HTML . Compiler::CONTEXT_HTML_COMMENT
Engine::CONTENT_HTML . Compiler::CONTEXT_HTML_CSS
Engine::CONTENT_HTML . Compiler::CONTEXT_HTML_JS
Engine::CONTENT_XHTML
Engine::CONTENT_XML
Engine::CONTENT_JS
Engine::CONTENT_CSS
Engine::CONTENT_ICAL

Funkce

V Latte můžete používat všechny funkce PHP a zároveň si definovat své vlastní:

$latte = new Latte\Engine;
$latte->addFunction('random', function (...$args) {
	return array_rand($args);
});

Použití je pak stejné, jako když voláte PHP funkci:

{random(jablko, pomeranč, citron)} // vypíše například: jablko

Druhým způsobem definice funkce je třída šablony. Důležité je uvést anotaci @function:

class MyTemplate
{
	/** @function */
	public function random(...$args)
	{
		return array_rand($args);
	}
}

$params = new MyTemplate;
...
$latte->render('template.latte', $params);

Vlastní tagy

Latte poskytuje API pro tvorbu vlastních tagů. Není to nic složitého. Značky přidáváme v sadách, přičemž sadu může tvořit i jediná značka.

$latte = new Latte\Engine;

// vytvoříme si sadu
$set = new Latte\Macros\MacroSet($latte->getCompiler());

// do sady přidáme párové tagy {try} ... {/try}
$set->addMacro(
	'try', // název tagu
	'try {',  // PHP kód nahrazující otevírací tag
	'} catch (\Exception $e) {}' // kód nahrazující uzavírací tag
);

Pokud značka není párová, třetí parametr metody addMacro() vynecháme.

PHP kód uváděný ve druhém a třetím parametru může obsahovat zástupné symboly:

• %node.word – vloží první argument tagu
• %node.array – vloží argumenty tagu naformátované jako PHP pole
• %node.args – vloží argumenty tagu naformátované jako PHP kód
• %escape(...) – nahradí za aktuální escapovací funkci
• %modify(...) – nahradí sérií filtrovacích funkcí

Příklad:

$set->addMacro('if', 'if (%node.args):', 'endif');

Pokud je logika značek ještě složitější, můžeme místo řetězců uvést callbacky či lambda funkce. Jako první parametr dostanou objekt MacroNode reprezentující aktuální uzel, druhým parametrem je objekt PhpWriter, který usnadňuje generování výstupního kódu.

$set->addMacro('if', function ($node, $writer) {
	return $writer->write('if (%node.args):');
}, 'endif');

Exception handler

Můžete si definovat vlastní obslužný handler pro očekávané výjimky. Předají se mu výjimky vzniklé uvnitř {try} a v sandboxu.

$loggingHandler = function (Throwable $e, Latte\Runtime\Template $template) use ($logger) {
	$logger->log($e);
};

$latte = new Latte\Engine;
$latte->setExceptionHandler($loggingHandler);

Dohledávání layoutu

Rozhraní API můžete použít k výběru šablony layout, která se má použít, když podřízená šablona neobsahuje značku {layout}. To zjednoduší psaní šablon nebo umožní automatické dohledávání layoutů.

Toho se dosáhne následujícím způsobem:

$finder = function (Latte\Runtime\Template $template) {
	if (!$template->getReferenceType()) {
		// vrací cestu k souboru s layoutem
		return 'automatic.layout.latte';
	}
});

$latte = new Latte\Engine;
$latte->addProvider('coreParentFinder', $finder);