CWidgetFactory.php 7.38 KB
Newer Older
JULIO JARAMILLO's avatar
JULIO JARAMILLO committed
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
<?php
/**
 * CWidgetFactory class file.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link http://www.yiiframework.com/
 * @copyright 2008-2013 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */


/**
 * CWidgetFactory creates new widgets to be used in views.
 *
 * CWidgetFactory is used as the default "widgetFactory" application component.
 *
 * When calling {@link CBaseController::createWidget}, {@link CBaseController::widget}
 * or {@link CBaseController::beginWidget}, if the "widgetFactory" component is installed,
 * it will be used to create the requested widget. To install the "widgetFactory" component,
 * we should have the following application configuration:
 * <pre>
 * return array(
 *     'components'=>array(
 *         'widgetFactory'=>array(
 *             'class'=>'CWidgetFactory',
 *         ),
 *     ),
 * )
 * </pre>
 *
 * CWidgetFactory implements the "skin" feature, which allows a new widget to be created
 * and initialized with a set of predefined property values (called skin).
 *
 * When CWidgetFactory is used to create a new widget, it will first instantiate the
 * widget instance. It then checks if there is a skin available for this widget
 * according to the widget class name and the widget {@link CWidget::skin} property.
 * If a skin is found, it will be merged with the initial properties passed via
 * {@link createWidget}. Then the merged initial properties will be used to initialize
 * the newly created widget instance.
 *
 * As aforementioned, a skin is a set of initial property values for a widget.
 * It is thus represented as an associative array of name-value pairs.
 * Skins are stored in PHP scripts like other configurations. Each script file stores the skins
 * for a particular widget type and is named as the widget class name (e.g. CLinkPager.php).
 * Each widget type may have one or several skins, identified by the skin name set via
 * {@link CWidget::skin} property. If the {@link CWidget::skin} property is not set for a given
 * widget, it means the default skin would be used. The following shows the possible skins for
 * the {@link CLinkPager} widget:
 * <pre>
 * return array(
 *     'default'=>array(
 *         'nextPageLabel'=>'&gt;&gt;',
 *         'prevPageLabel'=>'&lt;&lt;',
 *     ),
 *     'short'=>array(
 *         'header'=>'',
 *         'maxButtonCount'=>5,
 *     ),
 * );
 * </pre>
 * In the above, there are two skins. The first one is the default skin which is indexed by the string "default".
 * Note that {@link CWidget::skin} defaults to "default". Therefore, this is the skin that will be applied
 * if we do not explicitly specify the {@link CWidget::skin} property.
 * The second one is named as the "short" skin which will be used only when we set {@link CWidget::skin}
 * to be "short".
 *
 * By default, CWidgetFactory looks for the skin of a widget under the "skins" directory
 * of the current application's {@link CWebApplication::viewPath} (e.g. protected/views/skins).
 * If a theme is being used, it will look for the skin under the "skins" directory of
 * the theme's {@link CTheme::viewPath} (as well as the aforementioned skin directory).
 * In case the specified skin is not found, a widget will still be created
 * normally without causing any error.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @package system.web
 * @since 1.1
 */
class CWidgetFactory extends CApplicationComponent implements IWidgetFactory
{
	/**
	 * @var boolean whether to enable widget skinning. Defaults to false.
	 * @see skinnableWidgets
	 * @since 1.1.3
	 */
	public $enableSkin=false;
	/**
	 * @var array widget initial property values. Each array key-value pair
	 * represents the initial property values for a single widget class, with
	 * the array key being the widget class name, and array value being the initial
	 * property value array. For example,
	 * <pre>
	 * array(
	 *     'CLinkPager'=>array(
	 *         'maxButtonCount'=>5,
	 *         'cssFile'=>false,
	 *     ),
	 *     'CJuiDatePicker'=>array(
	 *         'language'=>'ru',
	 *     ),
	 * )
	 * </pre>
	 *
	 * Note that the initial values specified here may be overridden by
	 * the values given in {@link CBaseController::createWidget} calls.
	 * They may also be overridden by widget skins, if {@link enableSkin} is true.
	 * @since 1.1.3
	 */
	public $widgets=array();
	/**
	 * @var array list of widget class names that can be skinned.
	 * Because skinning widgets has performance impact, you may want to specify this property
	 * to limit skinning only to specific widgets. Any widgets that are not in this list
	 * will not be skinned. Defaults to null, meaning all widgets can be skinned.
	 * @since 1.1.3
	 */
	public $skinnableWidgets;
	/**
	 * @var string the directory containing all the skin files. Defaults to null,
	 * meaning using the "skins" directory under the current application's {@link CWebApplication::viewPath}.
	 */
	public $skinPath;

	private $_skins=array();  // class name, skin name, property name => value

	/**
	 * Initializes the application component.
	 * This method overrides the parent implementation by resolving the skin path.
	 */
	public function init()
	{
		parent::init();

		if($this->enableSkin && $this->skinPath===null)
			$this->skinPath=Yii::app()->getViewPath().DIRECTORY_SEPARATOR.'skins';
	}

	/**
	 * Creates a new widget based on the given class name and initial properties.
	 * @param CBaseController $owner the owner of the new widget
	 * @param string $className the class name of the widget. This can also be a path alias (e.g. system.web.widgets.COutputCache)
	 * @param array $properties the initial property values (name=>value) of the widget.
	 * @return CWidget the newly created widget whose properties have been initialized with the given values.
	 */
	public function createWidget($owner,$className,$properties=array())
	{
		$className=Yii::import($className,true);
		$widget=new $className($owner);

		if(isset($this->widgets[$className]))
			$properties=$properties===array() ? $this->widgets[$className] : CMap::mergeArray($this->widgets[$className],$properties);
		if($this->enableSkin)
		{
			if($this->skinnableWidgets===null || in_array($className,$this->skinnableWidgets))
			{
				$skinName=isset($properties['skin']) ? $properties['skin'] : 'default';
				if($skinName!==false && ($skin=$this->getSkin($className,$skinName))!==array())
					$properties=$properties===array() ? $skin : CMap::mergeArray($skin,$properties);
			}
		}
		foreach($properties as $name=>$value)
			$widget->$name=$value;
		return $widget;
	}

	/**
	 * Returns the skin for the specified widget class and skin name.
	 * @param string $className the widget class name
	 * @param string $skinName the widget skin name
	 * @return array the skin (name=>value) for the widget
	 */
	protected function getSkin($className,$skinName)
	{
		if(!isset($this->_skins[$className][$skinName]))
		{
			$skinFile=$this->skinPath.DIRECTORY_SEPARATOR.$className.'.php';
			if(is_file($skinFile))
				$this->_skins[$className]=require($skinFile);
			else
				$this->_skins[$className]=array();

			if(($theme=Yii::app()->getTheme())!==null)
			{
				$skinFile=$theme->getSkinPath().DIRECTORY_SEPARATOR.$className.'.php';
				if(is_file($skinFile))
				{
					$skins=require($skinFile);
					foreach($skins as $name=>$skin)
						$this->_skins[$className][$name]=$skin;
				}
			}

			if(!isset($this->_skins[$className][$skinName]))
				$this->_skins[$className][$skinName]=array();
		}
		return $this->_skins[$className][$skinName];
	}
}