5.3. Views

5.3.1. Introduction

The Template class used by Trex is based on the Zend_View class and is template system agnostic, that means that you may use PHP as your template language, or create instances of other template systems and manipulate them within your view script.

So, why not compile templates? Please, read the following explanation from Harry Fuecks.

In Trex you have two different type of templates: Site templates and Module templates.

Site templates

Many websites have templates that need to be repeated from page to page. These templates are stored in the app/global/views/ directory which has the following structure:

Example: app/global/views/ 

views/
    frontend/
        Main/
            Main.html
        Frame/
            Frame.html
            NewsFrame.html
        Menu/
            TopNav.html
            LeftNav.html
        Pager/
            Pager.html
            NewsPager.html

Module templates

Module templates are stored in the app/modules/<module_name>/views directory which has the following structure:

Example: app/modules/news/ 

news/
    views/
        frontend/
            index.html
            latest.html
        backend/
            index.html
            edit.html

Each module stores its templates in a sub folder named frontend/ or backend/ and they are usually named after an action. For example:

http://www.domain.com/news/latest

The first segment maps to the module “news” and the second segment to the action “latest”. So, to keep your files organized, you should name your template file “latest.html”.

So, creating the latest.html templates within your module is all you need to do in order to create a custom look for your module’s content.

5.3.2. Page Layout

The page shown in Figure 5.3.2 is a valid XHTML document. The DOCTYPE definition and the <html> and <body> tags are part of the Main template. The Main and Frame templates, also called global templates, store the HTML code that is common to all pages of the application to avoid repeating it in every template. The content of the Module template is integrated into the Main template.

trex-templates-dg.png
Figure 5.3.2 - Site and Module Templates

5.3.3. Loading Module Templates

Using Trex template engine happens in two major steps:

  1. Your Action Controller script creates an instance of Template and assigns variables to that instance.
  2. The Action Controller returns the Template object to render a particular view.

To load a template, you can use the getView() method:

  • obj getView (string filename [, array options] )

Example:

class News extends Trex_Module
{
        public function actionIndex()
        {
                // get index.html template from news/templates/frontend
                $template = $this->getView("index.html");

                // assign values to the Template instance
                $template->title = "Latest news";
                $template->filename = "index.html";
                $template->items = array("One", "Two");
                $template->items[] = "Three";

                return $template;
        }
}

In the above example, the News Controller will load the index.html file:

news/views/frontend/index.html

<h1> <?php echo $this->escape($this->title); ?> </h1>

<p>Filename: <?php echo $this->filename; ?> </p>

Options array

The Template component has several options that may be set to configure the behaviour of your view scripts:

  • Module: Name of the module.
  • Type: Front-end or back-end.
  • Escape: Indicates a callback to be used by escape(). May be set via setEscape() or the escape option to the constructor.
  • Encoding: Indicates the character encoding to use with htmlentities(), htmlspecialchars(), and other operations. Defaults to ISO-8859-1 (latin1). May be set via setEncoding().
  • Path: Adds a new path to the template script.

Example:

class News extends Trex_Module
{
        public function actionIndex()
        {
                $options = array(
                        "module" => "articles",
                        "escape" => "htmlentities",
                );

                // get latest-articles.html template from articles/templates/frontend
                $template = $this->getView("latest-articles.html", $options);

                return $template;
        }
}

Or tell it to use a static class method as the callback, example:

$optionsArray = array(
        "escape" => array("MyClass", "methodName"),
);

5.3.4. Adding CSS and JS files

To add a custom JavaScript or Style Sheet file to the Main template, you can use the addJsFile() or addCssFile() method:

  • void addJsFile ( str filename [, bool public_folder [, str action_controller]] )
  • void addAjaxScript ( str method, str request_type [, str query_string [, str module_name]] )
  • void addCssFile ( str filename [, bool public_folder [, str action_controller]] )

Example:

class News extends Trex_Module
{
        public function actionIndex()
        {
                // get index.html template from news/templates/frontend
                $template = $this->getView("index.html");

                // adds a CSS file to the main template
                $template->addCssFile("example.css");

                // adds a JS file to the main template
                $template->addJsFile("example.js");

                // adds an ajax script to the main template
                $template->addAjaxScript("get", "xml", "orderby=name&display=20");

                return $template;
        }
}