1: <?php
  2: /**
  3:  * The Horde_Core_Ui_Widget:: class provides base functionality for other
  4:  * Horde UI elements.
  5:  *
  6:  * Copyright 2003-2012 Horde LLC (http://www.horde.org/)
  7:  *
  8:  * See the enclosed file COPYING for license information (LGPL). If you
  9:  * did not receive this file, see http://www.horde.org/licenses/lgpl21.
 10:  *
 11:  * @author   Jason M. Felice <jason.m.felice@gmail.com>
 12:  * @category Horde
 13:  * @license  http://www.horde.org/licenses/lgpl21 LGPL 2.1
 14:  * @package  Core
 15:  */
 16: abstract class Horde_Core_Ui_Widget
 17: {
 18:     /**
 19:      * Any variables that should be preserved in all of the widget's
 20:      * links.
 21:      *
 22:      * @var array
 23:      */
 24:     protected $_preserve = array();
 25: 
 26:     /**
 27:      * The name of this widget.  This is used as the basename for variables
 28:      * we access and manipulate.
 29:      *
 30:      * @var string
 31:      */
 32:     protected $_name;
 33: 
 34:     /**
 35:      * A reference to a Horde_Variables:: object this widget will use and
 36:      * manipulate.
 37:      *
 38:      * @var Horde_Variables
 39:      */
 40:     protected $_vars;
 41: 
 42:     /**
 43:      * An array of name => value pairs which configure how this widget
 44:      * behaves.
 45:      *
 46:      * @var array
 47:      */
 48:     protected $_config;
 49: 
 50:     /**
 51:      * Holds the name of a callback function to call on any URLS before they
 52:      * are used/returned. If an array, it is taken as an object/method name, if
 53:      * a string, it is taken as a php function.
 54:      *
 55:      * @var callable
 56:      */
 57:     protected $_url_callback = array('Horde', 'applicationUrl');
 58: 
 59:     /**
 60:      * Construct a new UI Widget interface.
 61:      *
 62:      * @param string $name            The name of the variable which will
 63:      *                                track this UI widget's state.
 64:      * @param Horde_Variables &$vars  A Horde_Variables:: object.
 65:      * @param array $config           The widget's configuration.
 66:      */
 67:     public function __construct($name, &$vars, $config = array())
 68:     {
 69:         $this->_name = $name;
 70:         $this->_vars = &$vars;
 71: 
 72:         if (array_key_exists('url_callback', $config)) {
 73:             $this->_url_callback = $config['url_callback'];
 74:             unset($config['url_callback']);
 75:         }
 76:         $this->_config = $config;
 77:     }
 78: 
 79:     /**
 80:      * Instructs widget to preserve a variable or a set of variables.
 81:      *
 82:      * @param string|array $var  The name of the variable to preserve, or
 83:      *                           an array of variables to preserve.
 84:      * @param mixed $value       If preserving a single key, the value of the
 85:      *                           variable to preserve.
 86:      */
 87:     public function preserve($var, $value = null)
 88:     {
 89:         if (!is_array($var)) {
 90:             $var = array($var => $value);
 91:         }
 92: 
 93:         foreach ($var as $key => $value) {
 94:             $this->_preserve[$key] = $value;
 95:         }
 96:     }
 97: 
 98:     /**
 99:      * TODO
100:      */
101:     protected function _addPreserved($link)
102:     {
103:         foreach ($this->_preserve as $varName => $varValue) {
104:             $link->add($varName, $varValue);
105:         }
106: 
107:         return $link;
108:     }
109: 
110:     /**
111:      * Render the widget.
112:      *
113:      * @param mixed $data  The widget's state data.
114:      */
115:     abstract public function render($data = null);
116: 
117:     /**
118:      * TODO
119:      */
120:     protected function _link($link)
121:     {
122:         if (is_callable($this->_url_callback)) {
123:             return call_user_func($this->_url_callback, $link);
124:         }
125: 
126:         return $link;
127:     }
128: 
129: }
130: