Behavior.php 2.74 KB
Newer Older
Qiang Xue committed
1
<?php
w  
Qiang Xue committed
2 3
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
w  
Qiang Xue committed
5 6
 * @license http://www.yiiframework.com/license/
 */
Qiang Xue committed
7 8 9

namespace yii\base;

Qiang Xue committed
10 11 12
/**
 * Behavior is the base class for all behavior classes.
 *
Qiang Xue committed
13
 * A behavior can be used to enhance the functionality of an existing component without modifying its code.
Qiang Xue committed
14
 * In particular, it can "inject" its own methods and properties into the component
Qiang Xue committed
15 16
 * and make them directly accessible via the component. It can also respond to the events triggered in the component
 * and thus intercept the normal code execution.
Qiang Xue committed
17 18 19 20
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @since 2.0
 */
Qiang Xue committed
21
class Behavior extends \yii\base\Object
Qiang Xue committed
22
{
Qiang Xue committed
23
	/**
24
	 * @var Component the owner of this behavior
Qiang Xue committed
25
	 */
26
	public $owner;
Qiang Xue committed
27 28

	/**
Qiang Xue committed
29 30
	 * Declares event handlers for the [[owner]]'s events.
	 *
Qiang Xue committed
31 32 33 34
	 * 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
35 36 37
	 * attached to the owner; and they will be detached from the events when
	 * the behavior is detached from the component.
	 *
Qiang Xue committed
38 39
	 * The callbacks can be any of the followings:
	 *
Alexander Makarov committed
40 41 42
	 * - method in this behavior: `'handleClick'`, equivalent to `[$this, 'handleClick']`
	 * - object method: `[$object, 'handleClick']`
	 * - static method: `['Page', 'handleClick']`
Qiang Xue committed
43 44 45
	 * - anonymous function: `function($event) { ... }`
	 *
	 * The following is an example:
w  
Qiang Xue committed
46 47
	 *
	 * ~~~
Alexander Makarov committed
48
	 * [
Qiang Xue committed
49 50
	 *	 'beforeValidate' => 'myBeforeValidate',
	 *	 'afterValidate' => 'myAfterValidate',
Alexander Makarov committed
51
	 * ]
w  
Qiang Xue committed
52
	 * ~~~
Qiang Xue committed
53
	 *
Qiang Xue committed
54
	 * @return array events (array keys) and the corresponding event handler methods (array values).
Qiang Xue committed
55 56 57
	 */
	public function events()
	{
Alexander Makarov committed
58
		return [];
Qiang Xue committed
59 60 61 62
	}

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

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