Templates in Known
Known splits templating into templates and template types.
Templates
Templates are the styling information for each individual page element.
These have names of the form foo
, or foo/bar
, and may be split up with an indefinite number of forward-slashes. They are structured like relative folder paths; whatever works in a UNIX-style relative folder path, works in a Known template name.
By convention, Known uses lower-case template names.
Examples:
shell
is always the name of the page shell.page/navigation
might be the name of an app navigation menu.page/navigation/item
might be the name of an item in the aforementioned app navigation menu.
Template types
The template type is the kind or category of template we're dealing with.
By default, Known assumes we're talking HTML5 (referred to internally as the default
template type).
However, if you want to build an RSS feed, for example, your template type might be rss
.
Each template type contains its own set of templates. However, templates always fall back to the "default" template type, so that if you try to draw, for example, page/navigation
in the rss
template type, and it doesn't exist, page/navigation
in the default
template type will be called instead (if it exists).
Template locations
All template files are PHP scripts with the extension .tpl.php
. These script filenames correspond to the template name, such that:
page/navigation
would sit intemplates/default/page/navigation.tpl.php
for thedefault
template typepage/navigation
would sit intemplates/rss/page/navigation.tpl.php
for therss
template typepage/navigation
would sit intemplates/comicsans/page/navigation.tpl.php
for thecomicsans
template type (hey, you never know)
You can have multiple top-level templates
folders; Known will search them in the order they were added using Bon::additionalPath($path)
, falling back to the main Known folder at the end.
Template variables
Variables are accessible in a template file through the $vars
array. The BonTemp
template object is accessible in template files through a variable called $t
.
Examples:
<?=$vars['title']?>
echoes a passed variable calledtitle
.<?=$t->draw('page/navigation')?>
inserts thepage/navigation
template using the same variables that this template was called with.
Calling a template
Templates are called by accessing the current site template::
$t = \Idno\Core\Idno::site()->template();
You can add variables to pass to the templates by simply adding them as properties to the template object::
$t->title = 'Example title';
$t->foo = $bar;
If you want to set a template type other than default
, you call it using setTemplateType($templateType)
::
$t->setTemplateType('comicsans'); // See?
Finally, to draw a particular template, you call $t->draw($templateName)
, which returns the rendered template as a string::
$renderedContent = $t->draw('foo/bar');
Or to echo it directly::
echo $t->draw('foo/bar');
The template object also contains a special function to draw the page. This echoes the shell
template, and assumes you have (at a bare minimum) set the title
and body
variables::
$t->drawPage();
Example
For example, to display a stream of items stored in an array called $items
, using a template called example/items
you might call the templating engine as follows::
$t = \Idno\Core\Idno::site()->template();
$t->title = 'Stream';
$t->items = $items;
$t->body = $t->draw('example/items');
$t->drawPage();
The example/items
template file itself needs to be stored in templates/default/example/items.tpl.php
, and might look something like this::
<?php
if (!empty($vars['items'])) {
foreach($vars['items'] as $item) {
echo $this->__(['item' => $item])->draw('example/item');
}
}
The template file could also contain raw HTML.