Framework7 Plugins API

Framework7 comes with simple plugins/extensions API that allows you to create your own Framework7 plugins and extensions.

It is based on expandable Classes. Every JavaScript class (component) that is used in Framework7 is expandable.

Plugin Structure

First of all let’s look at the basic plugin’s JS structure. It is basically an object:

  1. var myPlugin = {
  2.   // Module Name
  3.   name: 'demo-module',
  4.   /* Install callback
  5.   It will be executed right after component is installed
  6.   Context of this callback points to Class where it was installed
  7.   */
  8.   install() {
  9.     const Class = this;
  10.     console.log(Class);
  11.   },
  12.   /* Create callback
  13.   It will be executed in the very beginning of class initilization (when we create new instance of the class)
  14.   */
  15.   create(instance) {
  16.     console.log('init', instance);
  17.   },
  18.   /*
  19.   Object with default class/plugin parameters
  20.   */
  21.   params: {
  22.     myPlugin: {
  23.       a: 1,
  24.       b: 2,
  25.       c: 3,
  26.     }
  27.   },
  28.   /* proto object extends Class prototype */
  29.   proto: {
  30.     demo() {
  31.       return 'demo-module-proto-method';
  32.     },
  33.     demoStatic: 'demo-module-proto-static',
  34.   },
  35.   // Extend Class with static props and methods, e.g. Class.myMethod
  36.   static: {
  37.     demo() {
  38.       return 'demo-module-class-method';
  39.     },
  40.     demoStatic: 'demo-module-class-static',
  41.   },
  42.   /* Initialized instance Props & Methods */
  43.   instance: {
  44.     demoProp: true,
  45.     demoMethod() {
  46.       return 'demo-method';
  47.     },
  48.   },
  49.   /* Event handlers */
  50.   on: {
  51.     demoEvent(a, b) {
  52.       console.log('demo-event', a, b);
  53.     },
  54.   },
  55.   /* Handle clicks */
  56.   clicks: {
  57.     // prop name means CSS selector of element to add click handler
  58.     'p': function ($clickedEl, data) {
  59.       // $clickedEl: Dom7 instance of clicked element
  60.       // data: element data set (data- attributes)
  61.     },
  62.   }
  63. };

Install Plugin

After we have our plugin, we need to install it on required Class. To install plugin we must call `.use()` method on class. For example, if this is an common Framework7 plugin:

  1. Framework7.use(myPlugin);

Plugin must be installed before class initialization (before calling new Framework7())

Demo Plugin

Let’s create simple Debug demo plugin. It will do nothing, just log some events:

  1. /* framework7.debug.js */
  3. var debugEnabled = false;
  5. window.debugPlugin = {
  6.   name: 'debugger',
  7.   // extend app params with debugger params
  8.   params: {
  9.     debugger: false,
  10.   },
  11.   create: function () {
  12.     var app = this;
  13.     // extend app methods with debugger methods when app instance just created
  14.     app.debugger = {
  15.       enable: function () {
  16.         debugEnabled = true;
  17.       },
  18.       disable: function () {
  19.         debugEnabled = false;
  20.       },
  21.     }
  22.   },
  23.   on: {
  24.     init: function () {
  25.       var app = this;
  26.       if (app.params.debugger) debugEnabled = true;
  27.       if(debugEnabled) console.log('app init');
  28.     },
  29.     pageBeforeIn: function (page) {
  30.       if(debugEnabled) console.log('pageBeforeIn', page);
  31.     },
  32.     pageAfterIn: function (page) {
  33.       if(debugEnabled) console.log('pageAfterIn', page);
  34.     },
  35.     pageBeforeOut: function (page) {
  36.       if(debugEnabled) console.log('pageBeforeOut', page);
  37.     },
  38.     pageAfterOut: function (page) {
  39.       if(debugEnabled) console.log('pageAfterOut', page);
  40.     },
  41.     pageInit: function (page) {
  42.       if(debugEnabled) console.log('pageInit', page);
  43.     },
  44.     pageBeforeRemove: function (page) {
  45.       if(debugEnabled) console.log('pageBeforeRemove', page);
  46.     },
  47.   }
  48. }

We need to include it to app:

  1. <body>
  2.     ...
  3.     <script src="path/to/framework7.js"></script>
  4.     <script src="path/to/framework7.debug.js"></script>
  5.     <script src="path/to/myapp.js"></script>
  6. </body>
  1. /* myapp.js */
  3. // install plugin first
  4. Framework7.use(debugPlugin);
  6. // init app
  7. var app = new Framework7({
  8.   //enable debugger
  9.   debugger: true,
  10. });
  12. /*
  13.   we can later disable it by calling
  14.   app.debugger.disable();
  15. */