Template Development
Templates in AVRO are designed to be very flexible and to make the developer's life easier like every other part of the framework. 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 knowledge of HTML could tackle these tasks.
The inclusion of "widgets" in the template makes it easy to build a page where different functions in the application each contribute a piece of the page.
This is made possible by using special tags that will be replaced at output time by the output generated by some functions in the application.
As with other AVRO 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).
We have two modes: frontend and backend. Usually frontend we use for public actions and backend use for authorized actions.
Creating Templates
Template 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, call the set_template method of the app object:
$this->app->set_template('template.name');
Editing Templates
The simplest form of template 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.
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 AVRO 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 without the need to write code. This is achieved 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.
This is achieved 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 specified by the request url, and the tag content will be replaced 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's 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 change from one page to the other are 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 AVRO template for all these pages.
As already mentioned, this is quite easily achieved 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>
...