HOW TO: Create a Sencha Touch Plugin – Part 1

What is a Plugin and why create one?

A plugin is a class that adds functionality/features to a parent component by adding or modifying its behaviour and/or look after its instatiation. By creating a plugin you can reuse it and apply its behaviour to any number of components without duplicating code and effort. To use a plugin in a component you simple instantiate it in the component’s ‘plugin‘ config option. An example of a plugin might be one which adds a help icon after each form field providing the user with help text on how to fill it in. If you didn’t create a plugin for it you would be required to manually code it for each form field which would be cumbersome and time consuming. So, hopefully I’ve convinced you of the merits of creating plugins to allow maximum code reuse and to make your lift a whole lot easier! Now how do we actually create one…?

The Code Structure

A plugin generally extends JavaScripts base Object class but can extend any class you like.

Your class extension only requires one method (or function), the init method which is executed when the parent component is instantiated but before it is rendered. This method has one parameter which is a reference to the parent component that the plugin is being applied to. See the code snippet below for the basic code structure.

Ext.ux.MyNewPlugin = Ext.extend(Object, {

    init: function(parent){
        // do your plugin code here
    }

});

And that’s us done. Seriously, that’s it – we’ve created our first plugin. All we have to do now is add some functionality ‘cos right now as you’ve probably noticed it doesn’t do anything…

A Simple Example

In this first part we are going to create a very simple and fairly useless example. We are going to create a plugin that alerts the user when they are closing a panel. In this example the parent component is going to be an Ext.Panel (remember the parameter that is passed to the init method? that will refer to our Panel) and will simply attach a listener to the Panel’s hide event and show an alert to the user. If you don’t have one already, first create an HTML page with references to the Sencha Touch library files or download the Tutorial Package by clicking the link below which will get you up and running with each step straight away.

Step 1 – Create Plugin Structure

First thing’s first we create our structure like above (you can put this code straight into your HTML page). Have a look at the “Step 1 – Create Plugin Structure.html” file for the full code and to see it in action or just click the Steps’ headings for a live demo.

Ext.ux.CloseAlertPlugin = Ext.extend(Object, {

    init: function(parent){

        console.log('Plugin Initialised');

    }

});

We’ve named it Ext.ux.CloseAlertPlugin and that is the name we will use when we add it to our Panel.

Step 2 – Create a Test Harness

We will use the code below as our test harness to see it in action. See the “Step 2 – Create Test Harness.html” file in the tutorial package.

var testHarnessPanel = new Ext.Panel({
    floating: true,
    width: 350,
    height: 370,
    centered: true,
    modal: true,
    hideOnMaskTap: false,
    plugins: [new Ext.ux.CloseAlertPlugin()],
    listeners: {
        afterrender: function(){
            console.log('Panel - After Render');
        }
    },
    items: [{
        xtype: 'button',
        text: 'Close',
        ui: 'confirm',
        handler: function(){
            testHarnessPanel.hide();
        }
    }]
});

testHarnessPanel.show();

If you run your page in Safari of Chrome you should, in the Console of the Developer Tools, see a log entry saying “Plugin Initialised” and “Panel – After Render”. This is because when our Plugin is created on line XX it fires the init method and then following this the Panel is rendered.

Step 3 – Add Listeners to our Plugin

Now we add our event handler. Check out the “Step 3 – Add Listeners to Plugin.html” file for the full code so far and this final step.

Ext.ux.CloseAlertPlugin = Ext.extend(Object, {

    init: function(parent){

        console.log('Plugin Initialised');

        parent.on('hide', function(){

            Ext.Msg.alert('Closed!', 'You just closed the Panel');

        }, parent);

    }

});

In the init method we attach an listener to the hide event of the Parent Panel which will run whenever the Parent Panel is hidden. In this case all we are doing is displaying an alert, but it could do anything that you like. And there you have it, a complete plugin. Who knew it was so simple to create a plugin? Admittedly this example is a little trivial but you should be able to see the benefits even with this case. If your application required an alert box to pop up when a Panel was hidden then you’ve just saved yourself 3 lines of code for every Panel that needs this functionality which means saved bytes and less maintenance! In the second part of this series I’m going to look at creating a more useful Plugin based on our Ext.ux.PanelAction plugin that was recently posted on the blog. So check back soon and feel free to comment with questions and suggestions.