Difference between #2 and #1 of Events explained

unchanged
Title
Events explained
unchanged
Category
Tutorials
unchanged
Tags
events, event handler
changed
Content
Let's see what exactly are the events in Yii!

What is an event? It is the fact that we want to **express** that in certain
points in our source code something happens!

Let's say that we are inside a function called runForestRun()
Instead of simply executing the code of this function we would like in addition
to express that forest ran.
In other words to say that this event has occured.
Why?
Because maybe others are interested that this event has
occuroccured and they would like to react!

So we want this:
~~~
[php]
function runForestRun(){ //some point in our code, either function or method
    //... arbitrary code before raising the event
    $myComponent->onForestRan(new CEvent($this));
    //... maybe some code over here after raising the event
}
~~~

In the first place the
~~~
[php]
new CEvent($this)
~~~
is just the basic object event of Yii.
The CEvent class can of course be extended in case we want to get extra
functionality. (like the CModelEvent which is used inside CActiveRecord)

Yeah ok I know, the myComponent does not have a method "onForestRan"
yet that's why we should declare it inside the component like this:
~~~
[php]
public function onForestRan($event){
    $this->raiseEvent('onForestRan', $event);
}
~~~
Typically here we simply call raise event but certainly someone could add extra
code, usually before calling raiseEvent if he wishes something extra.
The standard convention is that an event is defined with the **on** prefix and
after the name of the event with the first letter upper-case. 

Cool let's say we executed event and we yelled that forest has ran!
But who is going to listen?
The computer cannot guess by itself therefore we should tell it who is
interested!
In other words to define the handlers.

So earlier before raising the event we should have called, maybe inside the
initialization method of the component, something like this:
~~~
[php]
$myComponent->onForestRan = array(new SomeOtherClass, 'eventHandler1');
~~~
or that:
~~~
[php]
$myComponent->onForestRan = function() {};
~~~
or in general any callback function is valid in php:
[http://php.net/manual/en/language.pseudo-types.php](http://php.net/manual/en/language.pseudo-types.php
"callback")

We define one line for each one that has interest that forest ran!
In other words we could say that we prepare a list of functions or methods
(static or not) that will be executed one by one when the event is raised.

The event handlers must have a signature like this:
~~~
[php]
function eventHandler1($event) {
}
~~~
And now we can grab the sender object by $event->sender ;)


Please note that when a class (a component) yells that an event has happened
(that forest ran) then it is more sane that the event handlers (those of
interest to the event) are other entities!
To define a method inside the same class is technically possible but without
much of sense!

So let's do a resume of the events in three steps:

1) Define the event we want as a method inside the class with the prefix **on**
and typically inside it we call the raiseEvent.

2) Define all the callback functions (the handlers) which they will be called
when the event is going to be raised and we are done with the preperation of the
event.

3) Insert the statement $myComponent->onForestRan(new CEvent($this)); in
every point of the source code that is necessary in order for the event to be
raised at runtime.

Please do not hesitate to ask me if not everything is understood :)

References:
[http://www.yiiframework.com/doc/guide/1.1/en/basics.component#component-event](http://www.yiiframework.com/doc/guide/1.1/en/basics.component#component-event
"http://www.yiiframework.com/doc/guide/1.1/en/basics.component#component-event")

[http://www.yiiframework.com/wiki/44/behaviors-events](http://www.yiiframework.com/wiki/44/behaviors-events
"http://www.yiiframework.com/wiki/44/behaviors-events")

[http://www.yiiframework.com/wiki/255/using-events-with-caction-classes](http://www.yiiframework.com/wiki/255/using-events-with-caction-classes
"http://www.yiiframework.com/wiki/255/using-events-with-caction-classes")