Extending with events

Plugins are primarily extended using the Event service to inject or modify the functionality of core classes and other plugins.

Subscribing to events

The most common place to subscribe to an event is the boot() method of a Plugin registration file. For example, when a user is first registered you might want to add them to a third party mailing list, this could be achieved by subscribing to a rainlab.user.register global event.

public function boot()
{
    Event::listen('rainlab.user.register', function($user) {
        // Code to register $user->email to mailing list
    });
}

The same can be achieved by extending the model's constructor and using a local event.

User::extend(function($model) {
    $model->bindEvent('user.register', function() use ($model) {
        // Code to register $model->email to mailing list
    });
});

Declaring events

You can declare events globally or locally, below is an example of declaring a global event:

Event::fire('acme.blog.beforePost', ['first parameter', 'second parameter']);

The local equivalent requires the code be in context of the calling object.

$this->fireEvent('blog.beforePost', ['first parameter', 'second parameter']);

Note: It is good practice to put the local event before the global event, so local events take priority.

Once this event has been subscribed to, the parameters are available in the handler method. For example:

// Global
Event::listen('acme.blog.beforePost', function($param1, $param2) {
    echo 'Parameters: ' . $param1 . ' ' . $param2;
});

// Local
$this->bindEvent('blog.beforePost', function($param1, $param2) {
    echo 'Parameters: ' . $param1 . ' ' . $param2;
});

Extending back-end views

Sometimes you may wish to allow a back-end view file or partial to be extended, such as a toolbar. This is possible using the fireViewEvent() method found in all back-end controllers.

Place this code in your view file:

<div class="footer-area-extension">
    <?= $this->fireViewEvent('backend.auth.extendSigninView') ?>
</div>

This will allow other plugins to inject HTML to this area by hooking the event and returning the desired markup.

Event::listen('backend.auth.extendSigninView', function($controller) {
    return '<a href="#">Sign in with Google!</a>';
});

Note: The first parameter in the event handler will always be the calling object (the controller).

The above example would output the following markup:

<div class="footer-area-extension">
    <a href="#">Sign in with Google!</a>
</div>

Usage examples

These are some practical examples of how events can be used.

Extending a User model

This example will modify the model.getAttribute event of the User model by binding to its local event. This is carried out inside the boot() method of the Plugin registration file. In both cases when the $model->foo attribute is accessed, it will return the value bar.

class Plugin extends PluginBase
{
    [...]

    public function boot()
    {
        // Local event hook that affects all users
        User::extend(function($model) {
            $model->bindEvent('model.getAttribute', function($attribute, $value) {
                if ($attribute == 'foo') {
                    return 'bar';
                }
            });
        });

        // Double event hook that affects user #2 only
        User::extend(function($model) {
            $model->bindEvent('model.afterFetch', function() use ($model) {
                if ($model->id != 2) {
                    return;
                }

                $model->bindEvent('model.getAttribute', function($attribute, $value) {
                    if ($attribute == 'foo') {
                        return 'bar';
                    }
                });
            });
        });
    }
}

Extending a backend form

This example will modify the backend.form.extendFields global event of the Backend\Widget\Form class and inject some extra fields values under the conditions that the form is being used to modify a user. This event is also subscribed inside the boot() method of the Plugin registration file.

class Plugin extends PluginBase
{
    [...]

    public function boot()
    {
        // Extend all backend form usage
        Event::listen('backend.form.extendFields', function($widget) {

            // Only for the User controller
            if (!$widget->getController() instanceof \RainLab\User\Controllers\Users) {
                return;
            }

            // Only for the User model
            if (!$widget->model instanceof \RainLab\User\Models\User) {
                return;
            }

            // Add an extra birthday field
            $widget->addFields([
                'birthday' => [
                    'label'   => 'Birthday',
                    'comment' => 'Select the users birthday',
                    'type'    => 'datepicker'
                ]
            ]);

            // Remove a Surname field
            $widget->removeField('surname');
        });
    }
}

Remember to add use Event to the top of your class file to use global events.

Extending a backend list

This example will modify the backend.list.extendColumns global event of the Backend\Widget\Lists class and inject some extra columns values under the conditions that the list is being used to modify a user. This event is also subscribed inside the boot() method of the Plugin registration file.

class Plugin extends PluginBase
{
    [...]

    public function boot()
    {
        // Extend all backend list usage
        Event::listen('backend.list.extendColumns', function($widget) {

            // Only for the User controller
            if (!$widget->getController() instanceof \RainLab\User\Controllers\Users) {
                return;
            }

            // Only for the User model
            if (!$widget->model instanceof \RainLab\User\Models\User) {
                return;
            }

            // Add an extra birthday column
            $widget->addColumns([
                'birthday' => [
                    'label' => 'Birthday'
                ]
            ]);

            // Remove a Surname column
            $widget->removeColumn('surname');
        });
    }
}

Remember to add use Event to the top of your class file to use global events.

Extending a component

This example will declare a new global event rainlab.forum.topic.post and local event called topic.post inside a Topic component. This is carried out in the Component class definition.

class Topic extends ComponentBase
{
    public function onPost()
    {
        [...]

        /*
         * Extensibility
         */
        Event::fire('rainlab.forum.topic.post', [$this, $post, $postUrl]);
        $this->fireEvent('topic.post', [$post, $postUrl]);
    }
}

Next this will demonstrate how to hook to this new event from inside the page execution life cycle. This will write to the trace log when the onPost() event handler is called inside the Topic component (above).

[topic]
slug = "{{ :slug }}"
==
function onInit()
{
    $this['topic']->bindEvent('topic.post', function($post, $postUrl) {
        trace_log('A post has been submitted at '.$postUrl);
    });
}

Extending the backend menu

This example will replace the label for CMS and Pages in the backend with ....

class Plugin extends PluginBase
{
    [...]

    public function boot()
    {
        Event::listen('backend.menu.extendItems', function($manager) {

            $manager->addMainMenuItems('October.Cms', [
                'cms' => [
                    'label' => '...'
                ]
            ]);

            $manager->addSideMenuItems('October.Cms', 'cms', [
                'pages' => [
                    'label' => '...'
                ]
            ]);

        });
    }
}

Similarly we can remove the menu items with the same event:

Event::listen('backend.menu.extendItems', function($manager) {

    $manager->removeMainMenuItem('October.Cms', 'cms');
    $manager->removeSideMenuItem('October.Cms', 'cms', 'pages');

});