Models

Since a static assignment of contents isn't what we want to achieve, there must be a way to work with datas. In a MVC environment these datas are always wrapped into model instances. You can assign models of any type to your view instance with the assign([string] $name, [mixed] $model)-method. Every model which will be assigned must get a name to access it later again.

To access the models in the _render()-method you call the getDatas([string] $name)-method. It will return the model you requested or throws a XTemplate\Exceptions\RenderException-exception.

Here's a little demonstration:

scripts/5_models/view.php
<?php
    /**
     * x:template - PHP based template engine
     * Copyright (c) 2011 - 2012 by Tobias Pohlen <tobias.pohlen@xtemplate.net>
     * 
     * Released under the GPL License.
     * 
     * @author Tobias Pohlen
     * @ignore
     */
 
    // Load the x:template engine
    require_once "../../../Engine.php";
 
    /**
     * A simple class to demonstrate how to use models.
     * 
     * @author      Tobias Pohlen
     * @version     $Id$ 
     * @package     xtemplate
     * @ignore
     */
    class View extends XTemplate\ComfortView
    {
        /**
         * Path to the template file relative to this class file.
         */
        const TEMPLATE = "template.html";
 
        protected function _render()
        {
            // Request the news datas
            $objNews = $this->getDatas("news");
 
            $this["h1"] = $objNews->title;
            $this["h4"] = $objNews->subTitle;
            $this[".date"] = date("d.m.Y", $objNews->date);
            $this[".content"] = $objNews->content;
        }
 
        /**
         * Define the model interface
         */
        protected function defineModelInterface()
        {
            $this->defModel("news", "NewsModel");
        }
    }
?>
scripts/5_models/model.php
<?php
    /**
     * x:template - PHP based template engine
     * Copyright (c) 2011 - 2012 by Tobias Pohlen <tobias.pohlen@xtemplate.net>
     * 
     * Released under the GPL License.
     * 
     * @author Tobias Pohlen
     * @ignore
     */
 
    /**
     * A simple model class
     * 
     * @author      Tobias Pohlen
     * @version     $Id$ 
     * @package     xtemplate
     * @ignore
     */
    class NewsModel
    {
        /**
         * The date when the news was created in UNIX timestamp
         * @var string
         */
        public $date = 0;
        /**
         * The title of the news
         * @var string
         */
        public $title = "";
        /**
         * The subtitle of the news
         * @var string
         */
        public $subTitle = "";
        /**
         * The content text of the news
         * @var string
         */
        public $content = "";
    }
?>
scripts/5_models/controller.php
<?php
    /**
     * x:template - PHP based template engine
     * Copyright (c) 2011 - 2012 by Tobias Pohlen <tobias.pohlen@xtemplate.net>
     * 
     * Released under the GPL License.
     * 
     * @author Tobias Pohlen
     * @ignore
     */
 
    // Load the model & view classes
    require_once "view.php";
    require_once "model.php";
 
    // Create the model
    $objModel = new NewsModel;
    $objModel->title = "Testnews";
    $objModel->subTitle = "Showing you how x:template works";
    $objModel->date = time();
    $objModel->content = "Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet.";
 
    // Create the view an assign the model
    $objView = new View;
    $objView->assign("news", $objModel);
 
    // Render the view
    echo $objView;
?>
scripts/5_models/template.html
<h1></h1>
<h4></h4>
<em class="date"></em>
<div class="content"></div>

Typesafe model assignment

As a quality addicted developer you want to be as typesafe as possible when working with models. For this reason x:template's view classes have a STRICT_MODE in which all models must be predefined and are validated when they're assigned.

To switch the STRICT_MODE on or off, add a boolean constant to your class. Since the mode is enabled by default, here is an example to disable it:

scripts/5_models/disable_strictmode.php
<?php
    /**
     * x:template - PHP based template engine
     * Copyright (c) 2011 - 2012 by Tobias Pohlen <tobias.pohlen@xtemplate.net>
     * 
     * Released under the GPL License.
     * 
     * @author Tobias Pohlen
     * @ignore
     */
 
    // Load the x:template engine
    require_once "../../../Engine.php";
 
    /**
     * A simple class to demonstrate how to disable the strict mode.
     * 
     * @author      Tobias Pohlen
     * @version     $Id$ 
     * @package     xtemplate
     * @ignore
     */
    class View extends XTemplate\ComfortView
    {
        /**
         * Disable strict mode
         */
        const STRICT_MODE = false;
 
        const TEMPLATE = "template.html";
        protected function _render() {}
    }
?>

Define the model interface

When the first instance of your view class is created, the engine wants to create the model interface for this class. This interface defines which models the view expects and which are the default values. The interface is defined in the protected defineModelInterface()-method of your class. You don't need to implement it if you're not working with models. Within this method, you define which models you expect by using the defModel([string] $name, [string] $type, [mixed] $defaultValue = null)-method.

Here is an example how to define a model interface:

scripts/5_models/model_interface.php
<?php
    /**
     * x:template - PHP based template engine
     * Copyright (c) 2011 - 2012 by Tobias Pohlen <tobias.pohlen@xtemplate.net>
     * 
     * Released under the GPL License.
     * 
     * @author Tobias Pohlen
     * @ignore
     */
 
    // Load the x:template engine
    require_once "../../../Engine.php";
 
    /**
     * A simple class to demonstrate how to use models.
     * 
     * @author      Tobias Pohlen
     * @version     $Id$ 
     * @package     xtemplate
     * @ignore
     */
    class ViewWithMI extends XTemplate\ComfortView
    {
        /**
         * Define the model interface
         */
        protected function defineModelInterface()
        {
            //             Modelname       Modeltype      Default value
            // Classname
            $this->defModel("news"       , "NewsModel");
            // String with default value
            $this->defModel("title"      , "string"      , "Default Title");
            // Integer with default value
            $this->defModel("date"       , "integer"     , time());
            // Boolean with default value
            $this->defModel("showHeader" , "boolean"     , true);
            // Array with default value
            $this->defModel("newsEntries", "array"       , array());
        }
 
        const TEMPLATE = "template.html";
        protected function _render() {}
    }
?>

As model type you can choose one of the following options:

  • string
  • integer
  • boolean
  • float
  • double
  • array
  • [class name]

If you assign a model using the assign([string] $name, [mixed] $model)-method, the types are verified.