Creating Sencha Touch Toolbar Buttons

Creating Sencha Touch Toolbar Buttons

15 Comments

In this tutorial you will learn how to create different types of toolbar buttons using the Sencha Touch Library. The sample application you will write consists of a panel and a couple of toolbars. You will dock the first toolbar to the top of the panel and the second toolbar to the bottom, as portrayed in the picture below.

These are the tasks you will complete to build the application:

• Create a webpage to host the application
• Write the Ext.setup function
• Create different types of toolbar buttons
• Create a tap handler for the buttons
• Create and configure the toolbars
• Create a panel and dock the toolbars

Setting up your Sencha Touch application

In order to get started you need to create an HTML page to host your application.  This page will reference the Sencha Touch library and your own scripts:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title></title>
     <link rel="stylesheet" href="ext/resources/css/ext-touch-debug.css" type="text/css"/>
     <script type="text/javascript" src="ext/ext-touch-debug-w-comments.js"> </script>
     <script type="text/javascript" src="js/toolbar-buttons-1.js"> </script>
</head>
<body>
</body>
</html>

Now, let’s focus on the toolbar-buttons-1.js file.  The first step should be configuring the application’s icons and start-up screens.  You can do this inside the Ext.setup() function:

Ext.setup({
    tabletStartupScreen: 'tablet_startup.png',
    phoneStartupScreen: 'phone_startup.png',
    icon: 'icon.png',
    glossOnIcon: false
});

Ext.setup() is a native function that takes care of configuring your page so it looks great on different mobile platforms and devices.  It also hosts the onReady() function, which is where you will configure the application’s objects.

Creating different types of Sencha Touch toolbar buttons

Inside onReady(), your first assignment is to add a couple of arrays of button configurations.  These arrays contain the buttons for the top and bottom toolbars:

var buttonsSpecTop = [
    { ui: 'back', text: 'Back' },
    { xtype: 'spacer' },
    { ui: 'forward', text: 'Forward' }
]

var buttonsSpecBottom = [
    { ui: 'normal', text: 'Normal' },
    { ui: 'round', text: 'Round' },
    { ui: 'action', text: 'Action' },
    { ui: 'confirm', text: 'Confirm' }
]

Pay attention to the ui configuration option.  This option determines the look of the button.  If you examine the ui values in the code and the buttons in the screenshot, you will notice how each ui value corresponds to a different look and feel.

To see the buttons at work you can create a simple routine that will handle tap events:

var tapHandler = function (btn, evt) {
    alert("Button '" + btn.text + "' tapped.");
}

The buttons and tap handler are now ready and it’s time to create the toolbars. You can use an array to store both toolbars:

var dockedItems = [{
    xtype: 'toolbar',
    title: 'Buttons',
    ui: 'dark',
    dock: 'top',
    items: buttonsSpecTop,
    defaults: { handler: tapHandler }
}, {
    xtype: 'toolbar',
    ui: 'dark',
    dock: 'bottom',
    items: buttonsSpecBottom,
    defaults: { handler: tapHandler }
}]

Notice how each toolbar has an array of button configurations assigned to the items option, and the buttons’ tap handler is attached through the defaults configuration option.

Putting it all together

Finally, you can go ahead and create the panel that will serve as the main container for the application:

new Ext.Panel({
    id: 'buttonsPanel',
    fullscreen: true,
    dockedItems: dockedItems
});

The docketItems configuration option is used to specify one or more components to be added as docked items to the panel.  These components, commonly tool bars and tab bars, can be docked to the top, right, bottom or left of the panel.

It is possible to manipulate docked items using a number of functions.  You can use the addDocked() and removeDocked() functions to add or remove docked items, and onDockedAdd() or onDockedRemove() to perform actions upon addition or removal of docked items.  The getDockedItems() method returns an array of the currently docked components.

Here’s the complete source code:

Ext.setup({
    tabletStartupScreen: 'tablet_startup.png',
    phoneStartupScreen: 'phone_startup.png',
    icon: 'icon.png',
    glossOnIcon: false,
    onReady: function () {

        var buttonsSpecTop = [
            { ui: 'back', text: 'Back' },
            { xtype: 'spacer' },
            { ui: 'forward', text: 'Forward' }
        ]

        var buttonsSpecBottom = [
            { ui: 'normal', text: 'Normal' },
            { ui: 'round', text: 'Round' },
            { ui: 'action', text: 'Action' },
            { ui: 'confirm', text: 'Confirm' }
        ]

        var tapHandler = function (btn, evt) {
            alert("Button '" + btn.text + "' tapped.");
        }

        var dockedItems = [{
            xtype: 'toolbar',
            title: 'Buttons',
            ui: 'dark',
            dock: 'top',
            items: buttonsSpecTop,
            defaults: { handler: tapHandler }
        }, {
            xtype: 'toolbar',
            ui: 'dark',
            dock: 'bottom',
            items: buttonsSpecBottom,
            defaults: { handler: tapHandler }
        }]

        new Ext.Panel({
            id: 'buttonsPanel',
            fullscreen: true,
            dockedItems: dockedItems
        });
    }
});

There it is. I hope this tutorial helps you with your Sencha Touch projects.

Be mindful that the information I provide here is based on Sencha Touch 0.97 Public Beta.  You should expect to see differences with the first release of the library.