Component.md 2.87 KB
Newer Older
Qiang Xue committed
1 2
Component is the base class that implements the *property*, *event* and *behavior* features.

Qiang Xue committed
3 4 5 6 7
Component provides the *event* and *behavior* features, in addition to the *property* feature which is implemented in
its parent class [[Object]].

Event is a way to "inject" custom code into existing code at certain places. For example, a comment object can trigger
an "add" event when the user adds a comment. We can write custom code and attach it to this event so that when the event
8
is triggered (i.e. comment will be added), our custom code will be executed.
Qiang Xue committed
9

10
An event is identified by a name that should be unique within the class it is defined at. Event names are *case-sensitive*.
Qiang Xue committed
11

Qiang Xue committed
12
One or multiple PHP callbacks, called *event handlers*, can be attached to an event. You can call [[trigger()]] to
13 14
raise an event. When an event is raised, the event handlers will be invoked automatically in the order they were
attached.
Qiang Xue committed
15

16
To attach an event handler to an event, call [[on()]]:
Qiang Xue committed
17 18

~~~
Qiang Xue committed
19
$post->on('update', function($event) {
Qiang Xue committed
20 21 22 23
    // send email notification
});
~~~

Qiang Xue committed
24 25
In the above, an anonymous function is attached to the "update" event of the post. You may attach
the following types of event handlers:
Qiang Xue committed
26 27

- anonymous function: `function($event) { ... }`
Alexander Makarov committed
28 29
- object method: `[$object, 'handleAdd']`
- static class method: `['Page', 'handleAdd']`
Qiang Xue committed
30 31 32 33 34 35 36 37 38 39
- global function: `'handleAdd'`

The signature of an event handler should be like the following:

~~~
function foo($event)
~~~

where `$event` is an [[Event]] object which includes parameters associated with the event.

Qiang Xue committed
40 41
You can also attach a handler to an event when configuring a component with a configuration array.
The syntax is like the following:
Qiang Xue committed
42 43

~~~
Alexander Makarov committed
44
[
Qiang Xue committed
45
    'on add' => function($event) { ... }
Alexander Makarov committed
46
]
Qiang Xue committed
47 48 49 50
~~~

where `on add` stands for attaching an event to the `add` event.

Qiang Xue committed
51 52
Sometimes, you may want to associate extra data with an event handler when you attach it to an event
and then access it when the handler is invoked. You may do so by
Qiang Xue committed
53 54

~~~
Qiang Xue committed
55 56 57
$post->on('update', function($event) {
    // the data can be accessed via $event->data
}, $data);
Qiang Xue committed
58 59 60 61 62 63 64 65 66 67 68 69 70 71
~~~


A behavior is an instance of [[Behavior]] or its child class. A component can be attached with one or multiple
behaviors. When a behavior is attached to a component, its public properties and methods can be accessed via the
component directly, as if the component owns those properties and methods.

To attach a behavior to a component, declare it in [[behaviors()]], or explicitly call [[attachBehavior]]. Behaviors
declared in [[behaviors()]] are automatically attached to the corresponding component.

One can also attach a behavior to a component when configuring it with a configuration array. The syntax is like the
following:

~~~
Alexander Makarov committed
72 73
[
    'as tree' => [
Qiang Xue committed
74
        'class' => 'Tree',
Alexander Makarov committed
75 76
    ],
]
Qiang Xue committed
77 78 79 80
~~~

where `as tree` stands for attaching a behavior named `tree`, and the array will be passed to [[\Yii::createObject()]]
to create the behavior object.