Documentation

Working with application

Template development

Templates in toKernel are designed to be very flexible and to make the developer's life easier like every other part of the framwrok. Since it can entirely avoid PHP snippets of code, templates need not be created and managed by developers. Actually any designer or site administrator with a knowledge of html could tackle these tasks.

Inclusion of "widgets" in the template makes it easy to build a page where different functions in the application each contribute for a piece of the page.

This is made possible by using special tags that will be replaced at output time by the output generated byt some functions in the application.

As for other toKernel components templates may be defined at the application level (with files located in .../application/templates) or at the framework level (files located in .../framework/templates)

Creating templates

Templates names are normally created on the model "addon_name.action_name.tpl.php". This is actually the template that will be loaded by default by every action.
Example:

If we have an 'articles' addon with a 'show_article' action, it will use the default template "articles.show_article.tpl.php"

It is still possible to use another template as long as its name ends with the ".tpl.php" extension.

To load another template, just call the set_template method of the app object.

$this->app->set_template('template.name');

Editing templates

The simplest form of tmeplate is a template that simply displays the view attached to the action.

<html> <head> ... </head> <body> <!-- widget addon="__THIS__" --> </body> </html>

Each http request handled by the application has always a main addon and action, as parsed from the url. (See running toKernel in HTTP mode)

Normally, the action will produce some output after executing some code and echoing the result of the view->run() method. This output is buffered by toKernel until the moment the whole page is displayed by rendering the current template.

The tag '<!-- widget addon="__THIS__" -->' is a placeholder that will be replaced by the output of the main action.
Example of result:

<html> <head> ... </head> <body> <h1>Article Subject</h1> <p>Article content...</p> </body> </html>

Additional widgets in template

Where templates bring a major advantage over simple views is the possibility to combine several outputs together without the need to write code.

This is achieve by including named widgets in the template. These widgets are named after the name of some addon's method that will generate the output that will replace the widget placeholder.

For example, let's assume we have a template where you would like to have a piece of the page display a login dialog box. We have already written a 'show_login_box' method in the 'users' addon, that will display the login form. One point of attention is important here: the show_login_box action is NOT an HTTP callable action as described in the 'Addons, Modules, View'. It is just a regular method of the addon and therefore its name must not be prefixed.

public function show_login_box() { $view = $this->load_view('login_box'); echo $view->run(); }

In the template, this method can be called as follows:

<html> <head> ... </head> <body> <article class="main"> <!-- widget addon="__THIS__" --> </article> <section class="form"> <!-- widget addon="users" action="show_login_box" --> </section> </body> </html>

When the page is rendered, the

tag content will be replaced by the output produced by the main action as psecified by the request url and the
tag content will be replace by the output produced by the show_login_box method.

Widgets can also pass parameters to the called action.

For example, let's assume we want to display another box on our page with the title of the latest published articles.

We add another method to our articles addon which we call 'show_latest_articles', but to make it flexible, we want it to accept the number of articles to display as a parameter.

public function show_latest_articles($params = array()) { $limit = $params['limit']; $view = $this->load_view('show_latest articles'); /* Load $articles from db with $limit */ $view->articles = $articles; echo $view->run(); }

In the template file this method can be called as:

<html> <head> ... </head> <body> <article class="main"> <!-- widget addon="__THIS__" --> </article> <section class="form"> <!-- widget addon="users" action="show_login_box" --> </section> <section class="list"> <!-- widget addon="articles" action="show_latest_articles" params="limit/5" --> </section> </body> </html>

Since the template is quite simple, the website administrator or designer can change the value of params with any good text editor without the developer help.

Using a non default template

Very often, you'll find that many of your application pages are using the same visual template over and over again. The only things that changes from one page to the other is the main content provided by the main callable action.

In this case, to remain true to our principle of avoiding code duplication, we should use the same toKernel template for all these pages.

As already mentioned, this is quite easilty achived by using the app->set_template() method.

For example, if we want to reuse the template defined for the 'home' action in the 'user' addon, we can write:

$this->app->set_template('user.home');

Error file templates

A number of templates are provided at the framework level for error pages. They will be used by default by the standard error reporting methods of the framework.

debug.tpl.php error.tpl.php error_404.tpl.php warning.tpl.php

Of course, you can provide your own error reporting methods and adapt the templates to your liking.

Setting html <head> contents using templates.

Typically, templates are where you are likely to put the <head> tag contents of your application pages while the views are simply providing the contents for the pages <body> tag.

This brings the issue of properly setting a different page title, meta keywords and css or javascript files link especially if you reuse the same template for several pages.

The html class library has been designed to handle the issue (see the html class library page)
In your addon action you would call:

$this->lib->html->attach_file('my_js_or_css_url'); $this->lib->html->set_title('My webpage title'); $this->lib->html->set_meta('keywords', 'fee, bar');

and in the template file

... <head> <?php $this->lib->html->print_title(); $this->lib->html->print_meta(); $this->lib->html->print_attached_files(); // generate link to css and js files ?> </head> ...

See also HTML class library.