Events

Events are the way of communicating between modules, services and applications inside the Kube.

Principles #

  • events can be generated by the Kube application, by modules, and by services;
  • events does not return data, to ensure the independence of modules;
  • the first argument in the event always contains the instance of the module or service that generated this event;
  • the Kube application sends the first argument of itself, i.e. app;
  • events can contain arguments (a good practice is the arguments are passed as an object);
  • modules can catch events of other modules and services;
  • services cannot catch events.

Type of events #

Module events are sent simultaneously of two types:

  1. common event
  2. named event from a particular module with an ID or with data-name, if it is specified as an attribute of the element.

Here is the example of capturing an event of a common type from a module.

$K.add('module', 'mymodule', {
    init: function(app)
    {
        this.app = app;
    },
    // catch event
    onmessage: {
        alert: {
            closed: function(sender)
            {
                // caught
            }
        }
    }
});

Let's see the example of a named event from a specific module with ID or data-name attribute.

// html
<div class="alert" data-name="myalert" data-kube="alert">
    ...
    <span class="close is-small" data-type="close"></span>
</div>


// module
$K.add('module', 'mymodule', {
    init: function(app)
    {
        this.app = app;
    },
    // catch event
    onmessage: {
        alert: {
            closed: function(sender)
            {
                if (sender._id === 'myalert')
                {
                    // caught
                }
            }
        }
    }
});

Service events cannot have ID of element, because they are not bound to an element on the page. But services can have the name specified in the settings.

Capturing an event of a common type from a service.

(function($K)
{
    $K.add('module', 'mymodule', {
        init: function(app, context)
        {
            this.app = app;

            // define service
            this.modal = app.modal;
        },
        onmessage: {
            modal: {
                opened: function(sender, $modal, $form)
                {
                    // caught
                }
            }
        },
        showModal: function()
        {
            this.modal.open({
                url: '/server-side/my-modal.html',
                title: 'My Modal'
            });
        }
    });
})(Kube);

The example of an event from a service with the name.

(function($K)
{
    $K.add('module', 'mymodule', {
        init: function(app, context)
        {
            this.app = app;

            // define service
            this.modal = app.modal;
        },
        onmessage: {
            modal: {
                opened: function(sender, $modal, $form)
                {
                    if (sender._id === 'mymodal')
                    {
                        // caught
                    }
                }
            }
        },
        showModal: function()
        {
            this.modal.open({
                name: 'mymodal',
                url: '/server-side/my-modal.html',
                title: 'My Modal'
            });
        }
    });
})(Kube);

Broadcasting #

In modules, an event is dispatched using the this.app.broadcast method.

this.app.broadcast('mymodule.myevent', this);

The broadcast method will automatically create the second module event in which the ID of the module element or the data-name attribute will be specified.

You must create a named event manually for services like this:

this.app.broadcast('myservice.myevent', this);
this.app.broadcast([this.params.name, 'myservice.myevent'], this);

Broadcasting with arguments #

You can add arguments sequentially:

this.app.broadcast('mymodule.myevent', this, arg1, arg2);

Receiving arguments when an event is caught.

onmessage: {
    mymodule: {
        myevent: function(sender, arg1, arg2)
        {
            // caught
        }
    }
}

A good practice is to pass arguments as an object.

var args = {
	"arg1": arg1,
	"arg2": arg2
};
this.app.broadcast('mymodule.myevent', this, args);

Getting arguments as the object.

onmessage: {
    mymodule: {
        myevent: function(sender, args)
        {
            // caught
        }
    }
}

Catch events from outside #

To catch events from the outside, you need to create a module that will respond to the event and invoke external scripts.

For example, create a module element on the page:

<div data-kube="middleware"></div>

And the module:

(function($K)
{
    $K.add('module', 'middleware', {
        init: function(app, context)
        {
            this.app = app;
        },
        onmessage: {
            alert: {
                closed: function(sender)
                {
                    // call outside app
                }
            }
        }
    });
})(Kube);