Behavior.php 2.96 KB
Newer Older
Qiang Xue committed
1
<?php
w  
Qiang Xue committed
2 3 4 5 6 7 8
/**
 * Behavior class file.
 *
 * @link http://www.yiiframework.com/
 * @copyright Copyright &copy; 2008-2012 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */
Qiang Xue committed
9 10 11

namespace yii\base;

Qiang Xue committed
12 13 14 15
/**
 * Behavior is the base class for all behavior classes.
 *
 * A behavior can be used to enhance the functionality of an existing component.
Qiang Xue committed
16
 * In particular, it can "inject" its own methods and properties into the component
Qiang Xue committed
17 18 19 20 21
 * and make them directly accessible via the component.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
22
class Behavior extends Object
Qiang Xue committed
23
{
Qiang Xue committed
24 25 26
	/**
	 * @var Component the owner component
	 */
Qiang Xue committed
27 28 29
	private $_owner;

	/**
Qiang Xue committed
30 31
	 * Declares event handlers for the [[owner]]'s events.
	 *
Qiang Xue committed
32 33 34 35
	 * Child classes may override this method to declare what PHP callbacks should
	 * be attached to the events of the [[owner]] component.
	 *
	 * The callbacks will be attached to the [[owner]]'s events when the behavior is
Qiang Xue committed
36 37 38
	 * attached to the owner; and they will be detached from the events when
	 * the behavior is detached from the component.
	 *
Qiang Xue committed
39 40 41 42 43 44 45 46
	 * The callbacks can be any of the followings:
	 *
	 * - method in this behavior: `'handleOnClick'`, equivalent to `array($this, 'handleOnClick')`
	 * - object method: `array($object, 'handleOnClick')`
	 * - static method: `array('Page', 'handleOnClick')`
	 * - anonymous function: `function($event) { ... }`
	 *
	 * The following is an example:
w  
Qiang Xue committed
47 48 49
	 *
	 * ~~~
	 * array(
Qiang Xue committed
50 51
	 *	 'onBeforeValidate' => 'myBeforeValidate',
	 *	 'onAfterValidate' => 'myAfterValidate',
w  
Qiang Xue committed
52 53
	 * )
	 * ~~~
Qiang Xue committed
54 55
	 *
	 * @return array events (keys) and the corresponding behavior method names (values).
Qiang Xue committed
56 57 58 59 60 61 62 63
	 */
	public function events()
	{
		return array();
	}

	/**
	 * Attaches the behavior object to the component.
Qiang Xue committed
64 65
	 * The default implementation will set the [[owner]] property
	 * and attach event handlers as declared in [[events]].
Qiang Xue committed
66
	 * Make sure you call the parent implementation if you override this method.
Qiang Xue committed
67
	 * @param Component $owner the component that this behavior is to be attached to.
Qiang Xue committed
68 69 70
	 */
	public function attach($owner)
	{
Qiang Xue committed
71
		$this->_owner = $owner;
Qiang Xue committed
72 73
		foreach ($this->events() as $event => $handler) {
			$owner->attachEventHandler($event, is_string($handler) ? array($this, $handler) : $handler);
Qiang Xue committed
74
		}
Qiang Xue committed
75 76 77 78
	}

	/**
	 * Detaches the behavior object from the component.
Qiang Xue committed
79 80
	 * The default implementation will unset the [[owner]] property
	 * and detach event handlers declared in [[events]].
Qiang Xue committed
81
	 * Make sure you call the parent implementation if you override this method.
Qiang Xue committed
82
	 * @param Component $owner the component that this behavior is to be detached from.
Qiang Xue committed
83 84 85
	 */
	public function detach($owner)
	{
Qiang Xue committed
86 87
		foreach ($this->events() as $event => $handler) {
			$owner->detachEventHandler($event, is_string($handler) ? array($this, $handler) : $handler);
Qiang Xue committed
88 89
		}
		$this->_owner = null;
Qiang Xue committed
90 91 92
	}

	/**
Qiang Xue committed
93 94
	 * Returns the owner component that this behavior is attached to.
	 * @return Component the owner component that this behavior is attached to.
Qiang Xue committed
95 96 97 98 99 100
	 */
	public function getOwner()
	{
		return $this->_owner;
	}
}