Controller Templates

This page contains the description of how to work with controller templates, i.e. how to link them. The inner structure of templates is considered in the corresponding section.

Initialization

You should get the cmsTemplate class instance inside a controller to work with templates:

$template = cmsTemplate::getInstance();

or request the controller’s object property

$this->cms_template;

In other words, in this example, $template is similar to $this→cms_template.

Template Output

Templates related to the current component should be located in the /templates/default/controllers/{component title} folder and have the *.tpl.php* extension.

Let’s consider the template output using the example component as an example.

Let's create the /templates/default/controllers/example/hello.tpl.php file:

<h1>Hello world! My name is <?php html($name); ?>.</h1>

A template is a file that contains an HTML-markup and PHP-instructions to output data. In our case, the $name variable will be output in our template. This variable’s value will be passed from a controller. The html() function of the template outputs the variable’s contents (via htmlspecialchars()).

Use the render($template_name[, $data]) method of the earlier received $template object to output the created template inside the controller action.

class example extends cmsFrontend{
 
    public function actionIndex(){
 
        // we initialize the template system
        $template = cmsTemplate->getInstance();
 
        // we output the /templates/default/controllers/example/hello.tpl.php template
        $template->render('hello', array('name' => 'Vasiliy'));
 
    }
 
}

or equally, like this:

class example extends cmsFrontend{
 
    public function actionIndex(){
 
        // we output the /templates/default/controllers/example/hello.tpl.php template
        $this->cms_template->render('hello', array('name' => 'Vasiliy'));
 
    }
 
}

The render($template_name[, $data[, $request]]) method accepts three arguments:

A template’s file title (without .tpl.php) — the file will be taken from the template folder of this component
(optional) An array of data to output in the template — in the form of pairs Title ⇒ Value
(optional) The request object. If it is not specified, the request object from the controller context will be used.

Common Layout Customization

A common layout is the main template of all site pages containing the <html>, <head> and <body> tags. The templates of components and widgets are output inside it.

Each theme may include several layouts.

For example, an InstantCMS pack theme is called default and has two layouts - main and admin that are stored in the files:

/templates/default/main.tpl.php
/templates/default/admin.tpl.php

The main layout is used by all site pages by default, while the “Control panel” component uses the admin layout. The layout is switched in the component controller in the following way:

$template = cmsTemplate::getInstance();
$template->setLayout('admin');

The setLayout($layout_name) method switches the layout for the current request.

If a component uses a custom layout (or several layouts), a new theme should contain the same-name layouts when switching the theme, otherwise, the component will not be compatible with the theme.

Back to Contents