Zend Framework: Zend_Template Component Proposal

Proposed Component Name	Zend_Template
Developer Notes	http://framework.zend.com/wiki/display/ZFDEV/Zend_Template
Proposers	Ramses Paiva Sourcebits Technologies
Zend Liaison	TBD
Revision	0.1 - 1 October 2008 (wiki revision: 16)

Set a common directory for templates (views and layouts).
Set a common file suffix.
Set default template.
Change the template in use at anytime and anywhere in the application (preferencially in controllers).
Enable or disable layout at anytime.
Assign different paths for layouts and views.
Assign different suffixes for layouts and views
Assign different access rules for the views (like ':module/:controller/:action.:suffix')
Capacity to enable and disable it at anytime and anywhere on the application and when disabled, the default framework settings will be assumed.

4. Dependencies on Other Framework Components

Zend_Config
Zend_Controller_Action_Helper_ViewRenderer
Zend_Controller_Action_HelperBroker
Zend_Exception
Zend_Layout
Zend_View

5. Theory of Operation

Zend_Template is a singleton component to keep the view and layout settings in the whole application's life-cycle.
You can retrieve an instance throught its getInstance() method or through startMvc().

6. Milestones / Tasks

Milestone 1: Acceptance of Proposal.
Milestone 2: [DONE] Code basic interface.
Milestone 3: Code main class.
Milestone 4: Write unit tests.
Milestone 5: Write documentation.
Milestone 6: Working prototype checked into the incubator supporting all use cases.

7. Class Index

Zend_Template
Zend_Template_Exception
Zend_Template_Interface

8. Use Cases

UC-01

Basic usage:
In the bootstrap.php:

// The default template will be automatically set to 'default'.
// The view scripts path will be set to path/to/templates/default/scripts.
// The view scripts path specification will proxy to path/to/templates/:template/scripts/:module/:controller/:action.:suffix.
// where ':template' is == 'default'.
Zend_Template::startMvc('path/to/templates');

UC-02

Basic usage using Zend_Layout:
In the bootstrap.php:

// The default template will be automatically set to 'default'.
// The default layout path will be set to 'path/to/templates/:template/scripts/layouts'
// where ':template' is == 'default'.
Zend_Template::startMvc('path/to/templates')->enableLayout();

UC-03

Setting some specific configuration:
In the bootstrap.php:

$template = Zend_Template::startMvc('path/to/templates', 'default'); // Where the second parameter is the default template name
$template->enableLayout()
         ->setLayoutPath('path/to/layouts')
         ->setViewPath('base/path/to/views');

UC-04

Using with Smarty:
In the bootstrap.php:

$view = ZF_Smarty();

$template = Zend_Template::startMvc('path/to/templates', 'default', $view);
$template->setViewPathSpec(':module/:controller/:action.:suffix') // Already set as default
         ->setViewPathNoControllerSpec(':action.:suffix')         // Already set as default
         ->setViewSuffix('tpl');

UC-05

Using in your controllers:

class MyController extends Zend_Controller_Action
{
    public function fooAction()
    {
        $template = Zend_Template::getInstace();

        if ($template->isEnabled()) {
            // do some stuff
        }
    }


    public function barAction()
    {
        // It will look for path/to/templates/my_template and
        // will render the view scripts inside this path
        Zend_Template::getInstace()->setTemplate('my_template');
    }
}

9. Class Skeletons

interface Zend_Template_Interface
{
    /**
     * Static method for initialization.
     *
     * @return Zend_Template_Interface
     */
    public static function getInstance();

    /**
     * Static method for initialization with MVC support.
     *
     * @param Zend_Config|array|string $config The path for the templates or an array with options.
     *        Available options are:
     *             string  templatesPath           -> the base path to the templates.
     *             string  defaultTemplate         -> sets the default template.
     *             string|array|Zend_Config layout -> the layout script to be used as string or proxies to the Zend_Layout constructor.
     *             string  layoutPath              -> the path to layouts.
     *             string  viewPath                -> the base path to the views.
     *             boolean noViewRenderer          -> disable the view renderer helper.
     * @param string $defaultTemplate The default template to be used.
     * @param Zend_View_Interface $view A custom view object to be used with the templates.
     * @return Zend_Template_Interface
     */
    public static function startMvc($config = null, $defaultTemplate = 'default', Zend_View_Interface $view = null);

    /**
     * Disables the templates handler.
     *
     * @return Zend_Template_Interface
     */
    public function disable();

    /**
     * Enables the Zend_Layout component.
     *
     * Accepts either:
     * - A string path to layouts
     * - An array of options
     * - A Zend_Config object with options
     *
     * If Zend_Layout mvcEnabled flag is false from options, simply sets layout script path.
     * Otherwise, also instantiates and registers action helper and controller
     * plugin for Zend_Layout.
     *
     * @param  string|array|Zend_Config $options
     * @return Zend_Template_Interface
     */
    public function enableLayout($options = null);

    /**
     * Disables Zend_Layout component.
     *
     * @return Zend_Template_Interface
     */
    public function disableLayout();

    /**
     * If the view renderer action helper is disabled, enables it.
     * It's not necessary to use this method if the view renderer helper
     * was not disabled, once it's enabled as default.
     *
     * @return Zend_Template_Interface
     */
    public function enableViewRenderer();

    /**
     * Disables the view renderer action helper.
     *
     * @return Zend_Template_Interface
     */
    public function disableViewRenderer();

    /**
     * Sets the available options for this interface.
     *
     * @param Zend_Config|array $options
     * @return Zend_Template_Interface
     * @throws Zend_Template_Exception
     */
    public function setOptions($options);

    /**
     * Sets the default template to be used in the application.
     *
     * @return Zend_Template_Interface
     * @throws Zend_Template_Exception If the template does not exist.
     */
    public function setDefaultTemplate($template = 'default');

    /**
     * Sets the template to be temporary used.
     *
     * @return Zend_Template_Interface
     * @throws Zend_Template_Exception If the template does not exist.
     */
    public function setTemplate($template = 'default');

    /**
     * Sets the templates path to be used.
     *
     * @return Zend_Template_Interface
     * @throws Zend_Template_Exception If the path is not a valid path on the system.
     */
    public function setTemplatesPath($path);

    /**
     * Sets a global templates suffix that will be
     * applied to both layouts and views instances.
     *
     * @return Zend_Template_Interface
     */
    public function setTemplatesSuffix($suffix = 'phtml');

    /**
     * Sets a custom Zend_View object to be used with the templates.
     *
     * @param Zend_View_Interface $view
     * @return Zend_Template_Interface
     */
    public function setView(Zend_View_Interface $view);

    /**
     * Sets the view base path.
     *
     * @return Zend_Template_Interface
     * @throws Zend_Template_Exception If the path is not a valid path on the system.
     */
    public function setViewPath($path);

    /**
     * Sets the view scripts suffix.
     *
     * @return Zend_Template_Interface
     */
    public function setViewSuffix($suffix = 'phtml');

    /**
     * Sets the rule specifications to the view renderer
     * action helper to locate the view script in the
     * current system layout.
     *
     * @return Zend_Template_Interface
     */
    public function setViewPathSpec($path = ':module/:controller/:action.:suffix');

    /**
     * Sets the rule specifications to the view renderer
     * action helper to locate the view script in the
     * current system layout when the controller is not
     * specified.
     *
     * @return Zend_Template_Interface
     */
    public function setViewPathNoControllerSpec($path = ':action.:suffix');

    /**
     * Sets the layout script to be used by the Zend_Layout component.
     *
     * @param string $layout
     */
    public function setLayout($layout = 'layout');

    /**
     * Sets the layout path to be used by the Zend_Layout component.
     *
     * @return Zend_Template_Interface
     * @throws Zend_Template_Exception If the path is not a valid path on the system.
     */
    public function setLayoutPath($path);

    /**
     * Sets the scripts suffix to be used by the Zend_Layout component
     *
     * @return Zend_Template_Interface
     */
    public function setLayoutSuffix($suffix = 'phtml');

    /**
     * @return Zend_Layout
     */
    public function getLayout();

    /**
     * @return Zend_View_Interface
     */
    public function getView();

    /**
     * @return Zend_Controller_Action_Helper_ViewRenderer
     */
    public function getViewRenderer();

    /**
     * Checks if the templates handler is enabled
     *
     * @return boolean
     */
    public function isEnabled();

    /**
     * Checks if the Zend_Layout component is enabled
     *
     * @return boolean
     */
    public function isLayoutEnabled();

    /**
     * Checks if the view renderer action helper is enabled
     *
     * @return boolean
     */
    public function isViewRendererEnabled();
}

class Zend_Template implements Zend_Template_Interface
{}

class Zend_Template_Exception extends Zend_Exception
{}

Page Operations

Browse Space

Zend_Template - Ramses Paiva

Labels

Zend Framework: Zend_Template Component Proposal

Table of Contents

1. Overview

2. References

3. Component Requirements, Constraints, and Acceptance Criteria