Framework7 comes with easy to use Plugins API that allows you to create your own Framework7 plugins.
First of all let's look at the basic plugin's JS structure:
framework7.myplugin.js:
Framework7.prototype.plugins.myPlugin = function (app, params) {
... plugin code here ...
};
Where
myPlugin
- name of your plugin, should be unique, this name is also used when user pass parameters to your pluginsapp
- first of plugin function arguments. It is an initialized App instanceparams
- your plugin parameters (not required)So how our plugin will accept its personal parameters that will be passed as params
argument to plugin prototype function? It is simple and based on your plugin name, which is myPlugin
in example above. So to pass parameters to this plugin we will need to specify its name in App's parameters on the moment of initialization:
var myApp = new Framework7({
modalTitle: 'My App',
pushState: true,
/*
Here comes your plugin parameters that will be passed to your plugin in case of parameter name is the same as plugin name:
*/
myPlugin: {
foo: 'bar'
}
});
So now in plugin:
Framework7.prototype.plugins.myPlugin = function (app, params) {
console.log(params.foo); // 'bar'
};
What's next, how to make our plugin do something what we need?
Framework7's Plugin system is very interesting and simple, it is based on so called "hooks", "prevents" (not yet in core) and "process" (not yet in core):
So plugin should return object that may contain 3 objects with methods (hooks, prevents and processes):
Framework7.prototype.plugins.myPlugin = function (app, params) {
/*
Local plugin scope
*/
// Handle app init hook
function handleAppInit() {
console.log('app initialized');
}
// Return hooks
return {
hooks: {
// App init hook
appInit: handleAppInit
}
};
};
Note, that plugin will be initialized on the first stage of app initialization and few things may be still unneaccessable here (where "local plugin scope" in example above). If you need to execute code when app is fully initialized, use 'appInit' hook
Let's look at list of all currently available hooks (this list will be expanded) and their arguments:
appInit | Will be triggered when App is fully initialized |
navbarInit (navbar, pageData) | The same as "navbarInit" event |
pageInit (pageData) | The same as "page:init" event or same page callback. Will be triggered after Framework7 initialize page's components and navbar |
pageBeforeInit (pageData) | The same as "page:beforeinit" event or same page callback. Will be triggered before Framework7 just inserts new page to DOM |
pageBeforeAnimation (pageData) | The same as "page:beforeanimation" event or same page callback. Will be triggered when everything initialized and page (and navbar) is ready to be animated |
pageAfterAnimation (pageData) | The same as "page:afteranimation" event or same page callback. Will be triggered after page (and navbar) animation |
pageBeforeRemove (pageData) | The same as "page:beforeremove" event or same page callback. Will be triggered right before Page will be removed from DOM |
addView (view) | Will be triggered when user adds new View by calling myApp.addView . As an argument it receives initialized View instance |
loadPage (view, url, content) | This hook will be triggered in the most begining of new page loading process while it wasn't added to DOM yet. |
goBack (view, url, preloadOnly) | This hook will be triggered in the most begining of go back process. |
swipePanelSetTransform (views, panel, percentage) | This hook will be triggered during swipe on swipe panel |
To install/include plugin file you just need to include it right AFTER main Framework7 JavaScript library:
<body>
...
<script src="path/to/framework7.js"></script>
<script src="path/to/framework7.myplugin.js"></script>
</body>
Let's create simple Debug demo plugin. It will do nothing, just log all hooks and their arguments
framework7.debug.js:
Framework7.prototype.plugins.debug = function (app, params) {
// exit if not enabled
if (!params) return;
return {
hooks: {
appInit: function () {
console.log ('appInit');
},
navbarInit: function (navbar, pageData) {
console.log('navbarInit', navbar, pageData);
},
pageInit: function (pageData) {
console.log('pageInit', pageData);
},
pageBeforeInit: function (pageData) {
console.log('pageBeforeInit', pageData);
},
pageBeforeAnimation: function (pageData) {
console.log('pageBeforeAnimation', pageData);
},
pageAfterAnimation: function (pageData) {
console.log('pageAfterAnimation', pageData);
},
pageBeforeRemove: function (pageData) {
console.log('pageBeforeRemove', pageData);
},
addView: function (view) {
console.log('addView', view);
},
loadPage: function (view, url, content) {
console.log('loadPage', view, url, content);
},
goBack: function (view, url, preloadOnly) {
console.log('goBack', view, url, preloadOnly);
},
swipePanelSetTransform: function (views, panel, percentage) {
console.log('swipePanelSetTransform', views, panel, percentage);
}
}
};
};
We need to include it to app:
<body>
...
<script src="path/to/framework7.js"></script>
<script src="path/to/framework7.debug.js"></script>
<script src="path/to/myapp.js"></script>
</body>
And enable it in myapp.js:
var myApp = new Framework7({
debug: true
});