mirror of
https://github.com/yiisoft/yii.git
synced 2026-03-08 00:56:52 +01:00
111 lines
3.6 KiB
Plaintext
111 lines
3.6 KiB
Plaintext
Component
|
|
=========
|
|
|
|
Yii applications are built upon components which are objects
|
|
written to a specification. A component is an instance of
|
|
[CComponent] or its derived class. Using a component mainly involves
|
|
accessing its properties and raising/handling its events. The base class
|
|
[CComponent] specifies how to define properties and events.
|
|
|
|
Component Property
|
|
------------------
|
|
|
|
A component property is like an object's public member variable. We can
|
|
read its value or assign a value to it. For example,
|
|
|
|
~~~
|
|
[php]
|
|
$width=$component->textWidth; // get the textWidth property
|
|
$component->enableCaching=true; // set the enableCaching property
|
|
~~~
|
|
|
|
To define a component property, we can simply declare a public member
|
|
variable in the component class. A more flexible way, however, is by
|
|
defining getter and setter methods like the following:
|
|
|
|
~~~
|
|
[php]
|
|
public function getTextWidth()
|
|
{
|
|
return $this->_textWidth;
|
|
}
|
|
|
|
public function setTextWidth($value)
|
|
{
|
|
$this->_textWidth=$value;
|
|
}
|
|
~~~
|
|
|
|
The above code defines a writable property named `textWidth` (the name is
|
|
case-insensitive). When reading the property, `getTextWidth()` is invoked
|
|
and its returned value becomes the property value; Similarly, when writing
|
|
the property, `setTextWidth()` is invoked. If the setter method is not
|
|
defined, the property would be read-only and writing it would throw an
|
|
exception. Using getter and setter methods to define a property has the
|
|
benefit that additional logic (e.g. performing validation, raising events)
|
|
can be executed when reading and writing the property.
|
|
|
|
>Note: There is a slight difference between a property defined via getter/setter
|
|
methods and a class member variable. The name of the former
|
|
is case-insensitive while the latter is case-sensitive.
|
|
|
|
Component Event
|
|
---------------
|
|
|
|
Component events are special properties that take methods (called `event
|
|
handlers`) as their values. Attaching (assigning) a method to an event will
|
|
cause the method to be invoked automatically at the places where the event
|
|
is raised. Therefore, the behavior of a component can be modified in a way
|
|
that may not be foreseen during the development of the component.
|
|
|
|
A component event is defined by defining a method whose name starts with
|
|
`on`. Like property names defined via getter/setter methods, event names are
|
|
case-insensitive. The following code defines an `onClicked` event:
|
|
|
|
~~~
|
|
[php]
|
|
public function onClicked($event)
|
|
{
|
|
$this->raiseEvent('onClicked', $event);
|
|
}
|
|
~~~
|
|
|
|
where `$event` is an instance of [CEvent] or its child class representing
|
|
the event parameter.
|
|
|
|
We can attach a method to this event as follows:
|
|
|
|
~~~
|
|
[php]
|
|
$component->onClicked=$callback;
|
|
~~~
|
|
|
|
where `$callback` refers to a valid PHP callback. It can be a global
|
|
function or a class method. If the latter, the callback must be given as an
|
|
array: `array($object,'methodName')`.
|
|
|
|
The signature of an event handler must be as follows:
|
|
|
|
~~~
|
|
[php]
|
|
function methodName($event)
|
|
{
|
|
......
|
|
}
|
|
~~~
|
|
|
|
where `$event` is the parameter describing the event (it originates from
|
|
the `raiseEvent()` call). The `$event` parameter is an instance of [CEvent] or
|
|
its derived class. At the minimum, it contains the information about who
|
|
raises the event.
|
|
|
|
If we call `onClicked()` now, the `onClicked` event will be raised (inside
|
|
`onClicked()`), and the attached event handler will be invoked
|
|
automatically.
|
|
|
|
An event can be attached with multiple handlers. When the event is raised,
|
|
the handlers will be invoked in the order that they are attached to the event.
|
|
If a handler decides to prevent the rest handlers from being invoked, it can set
|
|
[$event->handled|CEvent::handled] to be true.
|
|
|
|
<div class="revision">$Id$</div> |