Framework7 Plugins API

Framework7 comes with easy to use Plugins API that allows you to create your own Framework7 plugins.

Plugin File Structure

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 plugins
• app - first of plugin function arguments. It is an initialized App instance
• params - your plugin parameters (not required)

Plugin parameters

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'
};        

Plugin Code

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):

• hooks - are like usual callbacks, they called by app in many different core parts. They allow to your plugin to execute code in required moments or to handle required data on different stages. Each hook receives different arguments.
• prevents allow to prevent some app's default actions, for example they may prevent default pages animation and make your own
• processes they work like preprocessors, each process method may takes data and modify it

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
        }
    };    
}; 

Available Hooks

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

Install Plugin

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>

Demo Plugin

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
});