1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 

<?php
namespace Nethgui\View;

/*
 * Copyright (C) 2011 Nethesis S.r.l.
 * 
 * This script is part of NethServer.
 * 
 * NethServer is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * NethServer is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with NethServer.  If not, see <http://www.gnu.org/licenses/>.
 */

/**
 * Each module receives a view object in prepareView() operation. A view
 * contains three types of elements:
 *
 * - primitive types (int, string, array, boolean..)
 *
 * - ViewInterface objects
 *
 * - Traversable objects
 *
 * @author Davide Principi <davide.principi@nethesis.it>
 * @since 1.0
 * @api
 */
interface ViewInterface extends \ArrayAccess, \IteratorAggregate
{
    /**
     * @deprecated since 1.6
     */
    const TARGET_XHTML = 'xhtml';

    /**
     * @deprecated since 1.6
     */
    const TARGET_JSON = 'json';

    /**
     * Set the template to be applied to the view
     *
     * - If a string is given, it identifies a PHP Template script
     *   (ie. Nethgui\Template\Main);
     *
     * - If a callback function is given, it is invoked with an array
     *   representing the view state as argument and is expected to return
     *   a string representing the view;
     *
     * - If a boolean FALSE, is given the view is rendered as an empty string.
     *
     * @param string|callback|boolean $template The template converting the view state to a string
     * @return ViewInterface
     * @api
     */
    public function setTemplate($template);

    /**
     * TODO
     *
     * @see setTemplate()
     * @return string|callback|boolean
     * @api
     */
    public function getTemplate();

    /**
     * Assign data to the View state.
     *
     * @param Traversable $data
     * @return ViewInterface
     * @api
     */
    public function copyFrom($data);

    /**
     * Create a new view object associated to $module
     *
     * @api
     * @param \Nethgui\Module\ModuleInterface $module The associated $module
     * @param boolean Optional If TRUE the returned view is added to the current object with key equal to the module identifier
     * @return \Nethgui\View\ViewInterface The new view object, of the same type of the actual.
     */
    public function spawnView(\Nethgui\Module\ModuleInterface $module, $register = FALSE);

    /**
     * The module associated to this view.
     *
     * @api
     * @return \Nethgui\Module\ModuleInterface
     */
    public function getModule();

    /**
     * Gets the array of the current module identifier plus all identifiers of
     * the ancestor modules, starting from the root.   
     *
     * @see ModuleInterface::getParent()
     * @see ModuleInterface::getIdentifier()
     * @return array
     * @api
     */
    public function getModulePath();

    /**
     * Obtain the complete path list, starting from root.
     *
     * An heading '/' character treat the $path as absolute, otherwise the
     * $path is considered relative to the current module and a '..' substring
     * goes one level up.
     *
     * @see getModulePath()
     * @see getModule()
     *
     * @param string $path The path
     * @return array The path parts, starting from root
     * @api
     */
    public function resolvePath($path);

    /**
     * Return an absolute url path.
     *
     * @see resolvePath()
     * @param string $path Relative to the current module
     * @return string
     * @api
     */
    public function getModuleUrl($path = '');

    /**
     * The web site URL without trailing slash
     * 
     * @example http://www.example.org:8080
     * @return string
     * @api
     */
    public function getSiteUrl();

    /**
     * The path component of an URL with a leading slash and trailing
     * 
     * @example /my/path/to/the/app/
     * @return string
     * @api
     */
    public function getPathUrl();

    /**
     * Generate a unique identifier for the given $path. If no parts are given
     * the identifier refers the the module referenced by the view.
     *
     * @param string $path Relative to the current module
     * @return string
     * @api
     */
    public function getUniqueId($path = '');

    /**
     * Get the target control identifier for the given view member
     * 
     * @see #358
     * @param string $name
     * @return string
     * @api
     */
    public function getClientEventTarget($name);

    /**
     * A method to translate a message according to the user language preferences.
     *
     * @param string $value
     * @param array $args
     * @return string
     * @see TranslatorInterface::translate()
     * @see getTranslator()
     * @api
     */
    public function translate($message, $args = array());

    /**
     * Access to the object performing string translations
     *
     * @api
     * @see translate()
     * @return \Nethgui\View\TranslatorInterface
     */
    public function getTranslator();

    /**
     * Get a command list for the given selector
     *
     * The returned command list is ready to execute().
     *
     * NOTE: only view objects correctly deliver commands to the client-side.
     * Widget commands are delivered to widget objects and executed server-side
     * only.
     *
     * @api
     * @param string $selector Routes the command list to the receiver appointed by this parameter.
     * @return \Nethgui\View\LegacyCommandBag
     * @deprecated since version 1.6
     */
    public function getCommandList($selector = '');

    /**
     * Check if one or more commands has been added to the selected command list
     *
     * @api
     * @return boolean TRUE, if some command has been added to the list
     * @deprecated since version 1.6
     */
    public function hasCommandList($selector = '');

    /**
     * Get the requested resource format
     *
     * @api
     * @deprecated since 1.6
     * @return string
     */
    public function getTargetFormat();
}