Changeset 19857

Timestamp:

07/03/09 19:25:25 (4 years ago)

Author:

fabien

Message:

[event_dispatcher] splitted the first chapter to create a new Recipes chapter with one new recipe (refs #6744)

Files:

• components/event_dispatcher/trunk/doc/01-Event-Dispatcher.markdown (modified) (1 diff)
• components/event_dispatcher/trunk/doc/02-Recipes.markdown (added)

components/event_dispatcher/trunk/doc/01-Event-Dispatcher.markdown

@@ -208 +208 @@
-    [php]
-    $ret = $event->getReturnValue();
-
-Recipes
--------
-
-This section lists some common usage of the event dispatcher.
-
-### Doing something before or after a Method Call
-
-If you want to do something just before, or just after a method is
-called, you can notify respectively an event at the beginning or at
-the end of the method:
-
-    [php]
-    class Foo
-    {
-      // ...
-
-      public function send($foo, $bar)
-      {
-        // do something before the method
-        $event = new sfEvent($this, 'foo.do_before_send', array('foo' => $foo, 'bar' => $bar));
-        $this->dispatcher->notify($event);
-
-        // the real method implementation is here
-        // $ret = ...;
-
-        // do something after the method
-        $event = new sfEvent($this, 'foo.do_after_send', array('ret' => $ret));
-        $this->dispatcher->notify($event);
-
-        return $ret;
-      }
-    }
-
-### Adding Methods to a Class
-
-To allow multiple classes to add methods to another one, you can
-define the magic `__call()` method in the class you want to be
-extended like this:
-
-    [php]
-    class Foo
-    {
-      // ...
-
-      public function __call($method, $arguments)
-      {
-        // create an event named 'foo.method_is_not_found'
-        // and pass the method name and the arguments passed to this method
-        $event = new sfEvent($this, 'foo.method_is_not_found', array('method' => $method, 'arguments' => $arguments));
-
-        // calls all listeners until one is able implements the $method
-        $this->dispatcher->notifyUntil($event);
-
-        // no listener was able to proces the event? The method does not exist
-        if (!$event->isProcessed())
-        {
-          throw new sfException(sprintf('Call to undefined method %s::%s.', get_class($this), $method));
-        }
-
-        // return the listener returned value
-        return $event->getReturnValue();
-      }
-    }
-
-Then, create a class that will host the listener:
-
-    [php]
-    class Bar
-    {
-      public function addBarMethodToFoo(sfEvent $event)
-      {
-        // we only want to respond to the calls to the 'bar' method
-        if ('bar' != $event['method'])
-        {
-          // let the opportunity to another listener to take care of this unknown method
-          return false;
-        }
-
-        // the subject object (the foo instance)
-        $foo = $event->getSubject();
-
-        // the bar method arguments
-        $arguments = $event['parameters'];
-
-        // do something
-        // ...
-
-        // set the return value
-        $event->setReturnValue($someValue);
-
-        // tell the world that you have processed the event
-        return true;
-      }
-    }
-
-Eventually, add the new `bar` method to the `Foo` class:
-
-    [php]
-    $dispatcher->connect('foo.method_is_not_found', array($bar, 'addBarMethodToFoo'));
-
-### Modifying Arguments
-
-If you want to allow third party classes to modify arguments passed
-to a method just before that method is executed, add a `filter`
-event at the beginning of the method:
-
-    [php]
-    class Foo
-    {
-      // ...
-
-      public function render($template, $arguments = array())
-      {
-        // filter the arguments
-        $event = new sfEvent($this, 'foo.filter_arguments');
-        $this->dispatcher->filter($event, $arguments);
-
-        // get the filtered arguments
-        $arguments = $event->getReturnValue();
-
-        // the method starts here
-      }
-    }
-
-And here is an example of a filter:
-
-    [php]
-    class Bar
-    {
-      public function filterFooArguments(sfEvent $event, $arguments)
-      {
-        $arguments['processed'] = true;
-
-        return $arguments;
-      }
-    }