/reference/en/11-Events.markdown
Markdown | 430 lines | 337 code | 93 blank | 0 comment | 0 complexity | 3082db5dd73fb51444d32d4c9da84ee0 MD5 | raw file
- # Introduction
- One of the greatest features of Sympal is that it takes advantage of the
- wonderful event system that Symfony provides. Sympal implements dozens of events
- that are strategically placed in the core code so that you can connect to them
- and manipulate functionality without altering any core code.
- In this chapter we will describe all the different events in Sympal and how you
- can utilize them.
- # Installation
- The installation of Sympal offers two events that you can connect to. These are
- simple events and allow you to execute your own code before and after the
- installation runs. Below you will find examples for both.
- ## Pre Install
- You can easily connect to the `sympal.pre_install` event and execute some custom
- code before Sympal is installed.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.pre_install',
- array($this, 'sympalPreInstall'))
- }
- public function sympalPreInstall(sfEvent $event)
- {
- // do some custom code
- }
- }
- ## Post Install
- You can also just as easily connect to the `sympal.post_install` event and
- execute some custom code after Sympal is installed.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.post_install',
- array($this, 'sympalPostInstall'))
- }
- public function sympalPostInstall(sfEvent $event)
- {
- // do some custmo code
- }
- }
- # Models
- Sympal implements a few events in Doctrine models so that you can easily
- customize models, add methods, etc. from your own code.
- ## Setup
- When using Sympal you can alter any aspect of the a model during its setup and
- initialization. This allows Sympal plugins to add columns to models, remove
- columns, add relationships, etc. Below you will find some examples of how to
- utilize these events.
- Imagine you have a Sympal plugin name `sfSympalUserProfilePlugin` which
- introduces a new model named `Profile` and adds a foreign key `profile_id` to
- the `User` model and adds the relationship between the two. First we need to
- hook in to the set table definition for the `User` model to add the `profile_id`
- column.
- > **TIP**
- > The `model_name` is what to use if the model was named `ModelName`. The event
- > names are always lower case and underscored. Even if your model name is
- > capitalized.
- Now we can add the column and our relationship to the `User` model with the
- following code.
- [php]
- class sfSympalUserProfilePluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.user.set_table_definition',
- array($this, 'userSetTableDefinition'));
- $this->dispatcher->connect('sympal.user.set_up',
- array($this, 'userSetUp'));
- }
- public function userSetTableDefinition(sfEvent $event)
- {
- $subject = $event->getSubject();
- $subject->hasColumn('profile_id', 'integer');
- }
- public function userSetUp(sfEvent $event)
- {
- $subject = $event->getSubject();
- $subject->hasOne('Profile', array(
- 'local' => 'profile_id',
- 'foreign' => 'id'
- ));
- }
- }
- Now our `User` model has a relationship to the `Profile` object and was all done
- without actually modifying any core code.
- [php]
- $user = new User();
- $profile = $user->Profile;
- # Content Format
- Sympal offers your content automatically in several formats. If you have a new
- format you wish to add you can easily do so by connecting to the
- `sympal.content_renderer.unknown_format` event.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.content_renderer.unknown_format',
- array($this, 'listenForUnknownFormat'));
- }
- public function listenForUnknownFormat(sfEvent $event)
- {
- // Set the extension name of your format
- $event['format'] = 'encryptedJson';
- // Build the output for your format
- $content = $event['content'];
- $array = $content->toArray(true);
- $json = json_encode($array);
- $encrypted = $this->someEncryptFunction($json);
- $event->setProcessed();
- $event->setReturnValue($encrypted);
- return true;
- }
- public function someEncryptFunction($json)
- {
- // encrypt the json with some key/salt
- // so the retrieving end can decrypt it
- return $json;
- }
- }
- You can also take a look at the `sfSympalContentListPlugin` which is a core
- Sympal plugin. It adds feeds functionality to your content lists. It can be
- found in `sfSympalPlugin/lib/plugins/sfSympalContentListPlugin`.
- # Admin Menu
- The admin menu in Sympal is a central administrative navigation menu that you can
- connect to and add new menus, or alter existing menus. You can add to this admin menu by connecting to the `sympal.load_admin_menu` event.
- In this example we'll add a new child to the Administration menu.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.load_admin_menu',
- array($this, 'loadAdminMenu'));
- }
- public function loadAdminMenu(sfEvent $event)
- {
- $menu = $event->getSubject();
- $menu->getChild('Administration')
- ->addChild('New Item', '@new_item_route');
- }
- }
- This is useful if you write a Sympal plugin that offers some new modules for
- administering the functionality of your plugin. You can connect to the above
- event and add links to these modules.
- # Editor Menu
- The editor menu is the dropdown menu in the inline edit car that shows when you are editing some content. All the contents of this panel are populated via events. So even the items you see by
- default are added via these events.
- [asset:127 title=Editor menu]
- To add to menu you can simply connect to the `sympal.load_editor`
- event.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.load_editor',
- array($this, 'loadEditor'));
- }
- public function loadEditor(sfEvent $event)
- {
- $menu = $event->getSubject();
- $menu->addChild('New Item', '@new_item_route');
- }
- }
- This is useful if you add some new functionality to content and want to show
- controls for the functionality in the editor menu.
- # Actions
- You can easily add functionality to all your actions class by connecting to the
- `component.method_not_found` event. This is a event provided by the Symfony
- core.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('component.method_not_found',
- array(new myActionsExtension(), 'extend'));
- }
- }
- class myActionsExtension extends sfSympalExtendClass
- {
- public function goBack()
- {
- $this->redirect($this->getRequest()->getReferer());
- }
- }
- The above code would make available a `goBack()` method in all your actions
- class that goes back to the referer.
- > **NOTE**
- > Sympal uses this event internally and makes available several new functions to
- > your actions class. `goBack()` is in fact one of them. For demonstration
- > purposes we used this feature as an example above.
- [php]
- class my_moduleActions extends sfActions
- {
- public function executeSave_comment(sfWebRequest $request)
- {
- // save comment
- // go back to where we came from
- $this->goBack();
- }
- }
- # Configuration Form
- Sympal provides a means to edit all the configurations from a web interface. The
- default way to edit configuration values is by manually overriding the `app.yml`
- file and changing values. If you want your configurations to be editable in the
- browser then you can connect to the `sympal.load_config_form` event and add the
- settings to the form.
- ## Adding Configuration
- Imagine you had a `sfSympalTestPlugin` and you have a `config/app.yml` that
- looks like the following:
- [yml]
- all:
- sympal_config:
- test:
- my_setting: true
- Now if you want that setting to be editable from the browser you can do the
- following.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.load_config_form',
- array($this, 'loadConfig'));
- }
- public function loadConfig(sfEvent $event)
- {
- $form = $event->getSubject();
- $form->addSetting('test', 'my_setting',
- 'My Setting', 'InputCheckbox', 'Boolean');
- }
- }
- ## Pre Save
- You can hook in to the saving process of the configuration form and execute some
- custom code before it is saved.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.config_form.pre_save',
- array($this, 'configFormPreSave'));
- }
- public function configFormPreSave(sfEvent $event)
- {
- $form = $event->getSubject();
- // execute some custom code
- }
- }
- ## Post Save
- You can hook in to the saving process of the configuration form and execute some
- custom code after it is saved.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.config_form.post_save',
- array($this, 'configFormPostSave'));
- }
- public function configFormPostSave(sfEvent $event)
- {
- $form = $event->getSubject();
- // execute some custom code
- }
- }
- # Dashboard
- The contents of the dashboard you see when you login are populated by events as
- well. So if you want to add a new box or change something on the dashboard then
- you can do by connecting to some events.
- ## Boxes
- First if you want to add some new boxes to the dashboard you can do so by
- connecting to the `sympal.load_dashboard_boxes` event.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.load_dashboard_boxes',
- array($this, 'loadDashboardBoxes'));
- }
- public function loadDashboardBoxes(sfEvent $event)
- {
- $menu = $event->getSubject();
- $menu->addChild('New Box', '@new_box_route');
- }
- }
- # Content Rendering
- When a Sympal content record is rendered we notify a few events to give you an
- opportunity to change something about the rendering.
- ## Filter Slot Content
- You can filter the rendered slot value with the `sympal.content_renderer.filter_slot_content` event.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.content_renderer.filter_slot_content',
- array($this, 'filterSympalSlotContent'));
- }
- public function filterSympalContent(sfEvent $event, $content)
- {
- // Manipulate the $content string
- // Add to it
- // Change it, etc..
- return $content;
- }
- }
- ## Filter Content
- After some content has been rendered you can use a filter event to filter the
- html of the rendered content. This is a similar concept to the core Symfony
- event named `response.filter_content` which allows you to alter the response
- HTML before it is sent to the browser.
- [php]
- class sfSympalTestPluginConfiguration extends sfPluginConfiguration
- {
- public function initialize()
- {
- $this->dispatcher->connect('sympal.content_renderer.filter_content',
- array($this, 'filterSympalContent'));
- }
- public function filterSympalContent(sfEvent $event, $content)
- {
- // Manipulate the $content string
- // Add to it
- // Change it, etc..
- return $content;
- }
- }
- > **TIP**
- > The web debug toolbar is added to the HTML automatically by Symfony by
- > connecting to the `response.filter_content` event.