Events

Most of Framework7 components that is built with classes/constructors (including Framework7 class itself) have event emitter API.

It allows us easily to emit and handle all kind of events, including events between components.

Events Handlers in Parameters

When you create app instance or any other component using API, you can pass event handler on app/component initialization in **on** parameter:

  1. var app = new Framework7({
  2. ...
  3. on: {
  4. // each object key means same name event handler
  5. pageInit: function (page) {
  6. // do something on page init
  7. },
  8. popupOpen: function (popup) {
  9. // do something on popup open
  10. },
  11. },
  12. });
  13. var popup = app.popup.create({
  14. ...
  15. on: {
  16. open: function (popup) {
  17. // do something on popup open
  18. }
  19. }
  20. })

Events Methods

It also possible to add/remove event handlers using the following instance methods:

[instance].on(event, handler)Add event handler
[instance].once(event, handler)Add event handler that will be removed after it was fired
[instance].off(event, handler)Remove event handler for specified event
[instance].off(event)Remove all handlers for specified event
[instance].emit(event, …args)Fire event on instance

Add Event Handlers

  1. var app = new Framework7({/*...*/});
  2. var popup = app.popup.create({/*...*/});
  3. app.on('pageInit', function (page) {
  4. // do something on page init
  5. });
  6. app.on('popupClose', function (popup) {
  7. // do something on popup open
  8. });
  9. popup.on('open', function (popup) {
  10. // do something on popup open
  11. });
  12. // Once handler, will work only once
  13. popup.once('close', function (popup) {
  14. // do something on popup close
  15. });

Add Multiple Handlers

We can pass multiple events in first parameters separated with space:

  1. app.on('popupOpen popupClose', function (popup) {
  2. // do something on popupOpen and popupClose
  3. });

Remove Event Handlers

Named function handler can be removed:

  1. function onTabShow() {
  2. // do something on tab show
  3. }
  4. // add handler
  5. app.on('tabShow', onTabShow);
  6. // later remove tabShow handler:
  7. app.off('tabShow', onTabShow);

Remove All Handlers

If we don’t pass second handler argument to .off method then we will remove all handlers assigned for this event:

  1. // Remove all tabShow handlers
  2. app.off('tabShow');

Emit Events

And of course we can emit events and any kind of custom events we may need:

  1. app.on('myCustomEvent', function (a, b) {
  2. console.log(a); // -> 'foo'
  3. console.log(b); // -> 'bar'
  4. });
  5. app.emit('myCustomEvent', 'foo', 'bar');

Events Delegating

Events which emitted on components will delegate to app instance as well:

  1. app.on('something', function () {/*...*/});
  2. popup.on('something', function () {/*...*/});
  3. popup.emit('something'); // will trigger "something" event assigned to both app and popup instances

If this is not what you want, it is possible to emit so called local events on components. In this case we need to prefix event name with **local::**

  1. app.on('something', function () {/*...*/});
  2. popup.on('something', function () {/*...*/});
  3. popup.emit('local::something'); // will only trigger "something" event assigned to popup instance above

Event Handler Context

Event handler context (this) will always point to instance where it was assigned:

  1. app.on('popupOpen', function () {
  2. console.log(this); // -> app instance
  3. });
  4. popup.on('popupOpen', function () {
  5. console.log(this); // -> popup instance
  6. });

Events Bus

Current events emitter API on Framework7 classes is also very useful to create custom events for communication between app components and modules.

And there is an additional helper class that is designed to be used like event bus only and not to flood main app or some components instances.

To create new events bus we need to call new Framework7.Events():

  1. // Create custom events bus
  2. var myEvents = new Framework7.Events();
  3. // handle event
  4. myEvents.on('some-event', function () {
  5. // do something when 'some-event' fired
  6. })
  7. // emit event
  8. myEvents.emit('some-event');
  9. // Create another event bus
  10. const notificationEvents = new Framework7.Events();
  11. notificationEvents.on('notificationReceived', function (notification) {
  12. // do something with notification
  13. })
  14. // somewhere in the app send notification
  15. notificationEvents.emit('notificationReceived', {
  16. title: 'New message',
  17. from: 'John Doe',
  18. });