Working with Panels, laying out components – Sencha Touch

It has been long since I am writing something on Sencha Touch as I was busy working on HTML5 mobile apps without using Sencha Touch. Soon I will be posting a tutorial on how to build mobile apps using plain JavaScript and HTML5 and not any external library. Ok, let’s get started, in some of the previous tutorials on Sencha Touch we have seen how to work mostly with List controls and customizing the List control to give it a look that you always wanted. However, the List control is a component and to host it, rather display it correctly we need some container element such as the Panel. In this tutorial we will see how to work with Panels.

Alright, the definition, Panel is a container element that allows adding child components, with specific layout, positioning and a host of other functionalities.

Class Structure
Panel is defined by the Ext.Panel class which inherits from Ext.Container class, so it gets the layout properties from the parent class, which means you can layout your child components within your Panel container.  For all the properties and methods of the Panel class you can have a look at the API documentation.

Creating a Panel
Let’s see the syntax for creating a simple Panel. To build a Panel we create a new instance by calling the Ext.Panel class constructor,

var panel = new Ext.Panel({

});

Inside the parenthesis of Ext.Panel() constructor function comes the configuration object. This is where you initialize the configuration properties for your Panel. Below is an example of a configuration object,

{
    layout: 'fit',
    fullscreen: true,
    items: [{}, {}, ....]
}

Remember to put your object properties inside the curly braces {} since it follows the object notation, JSON. Putting it altogether this is how it looks, your first simple Panel!!

var panel = new Ext.Panel({
    layout: 'fit',
    fullscreen: true,
    items: [{}, {}, ....]
});

And of course you can add a lot many properties to your configuration object. All the properties have been well documented in the API documentation.

Some useful properties
Some of the useful properties to get you started are:

fullscreen – setting the fullscreen property to true makes the Panel occupy the whole screen of the mobile device, that is it takes 100% of the width and height. Default value is false.

layout – allows to position and size the child components correctly. The values of the layout properties that you can specify are ‘fit’, ‘vbox’, ‘hbox’, ‘card’, and ‘auto’ for the default value. Remember that these values are string values that can be assigned to the layout property. However, you can also specify the layout property as an object with additional properties. The positioning and sizing are actually managed by the Layout manager of the container. If you do not specify the layout property then the default layout value of ‘auto’ is set which positions the child components sequentially one after the other.

Eg. with string value

var panel = new Ext.Panel({
    layout: 'vbox',
    fullscreen: true
});

You can also specify layout as an object, this is how to do it,

var panel = new Ext.Panel({
    layout:{
                type:'vbox',
                align:'center'
           },
    fullscreen: true
});

As you can see the layout property is defined as an object now, the type property defines the string values now and also you can see an additional property of align which specifies the horizontal alignment of the child components, default value is center which horizontally center aligns the child components within the Panel, other values are ‘start’ for left alignment, ‘end‘ for right alignment and ‘stretch’ for stretching the child horizontally to the width of the Panel. Try out the different align values and check out the results.

dockedItems –  defines an array of child components that are docked to the Panel. You can dock the items at the top, left, right and bottom of the Panel. This property can be used to add title bars, tab bars or tool bars. We will see how to dock items, later in this tutorial.

items – one of the more important properties, allows to add child components to the Panel. It is an array of child components. The components defined inside this array are actually added to the Panel in the layout specified by the layout property. We will see how to add components later.

html – defines an HTML string that can be added to the Panel. You can specify any HTML tags within the string and also add custom CSS class to create your own styles. We will read about it later in this tutorial.

And of course there are other useful properties like width, height, and scroll e.tc.

Adding Child components
Ok, now the most important part of this tutorial, now that you have your basic Panel skeleton ready with useful properties, let’s see how to actually add child components into the Panel container. Adding child components can be categorized into two, a) adding docked items which will always dock either at the top, left, right or bottom of the panel and b) adding child components to the body of the panel using the items property. Below are some examples,

  • Adding docked items

Docking items can be useful when you want to add a toolbar, tab bar, simple title bar to your panel.

dockedItems: [
                { xtype: 'toolbar', dock: 'top', title: 'Contact List' }
             ],

Here we have added a simple toolbar with a title, docked at the top of the Panel. Remember, dockedItems is an Array, so you can add a series of items as Objects. This is how to do it,

dockedItems: [
                 { xtype: 'toolbar', dock: 'top', title: 'Contact List' },
                 { xtype: 'button', dock: 'top', text: 'Click' }
             ],

Here we have a title bar and a button with a label Click, docked at the top one after the other as in the image below. Similarly, if you go on adding items to the dockedItems array, the items will be added sequentially, with the first item of the array being at the topmost in the stack, shown in the image below,

And then you can dock at the top and the bottom this way, see the image below,

dockedItems: [
                 { xtype: 'toolbar', dock: 'top', title: 'Contact List' },
                 { xtype: 'button', dock: 'bottom', text: 'Click' }
             ],

Try docking both the items to the bottom and also left and right, find out what happens.

  • Adding items to the body

Use the items array property to add items (child components) to the Panel container’s body. Also define a layout type to position the child components inside the Panel. Basic syntax of adding child components is,

 // specifying a single item
 items: [{...}],
 layout: 'fit',    // specify a layout!

 // specifying multiple items
 items: [{...}, {...}],
 layout: 'vbox', // specify a layout!

An example of adding a button component is shown below,

items: [
           { xtype:'button', text:'Button2'}
       ],
layout: { type: 'vbox', align: 'center' },

We have added a single Button component to the Panel by defining an object literal with an xtype declaration. Since items property is an array, so you can go on to add multiple child components to your Panel, like this

items: [     
           { xtype:'button', text:'Button1'}
           { xtype:'button', text:'Button2', ui:'round'}
       ],
layout: { type: 'vbox', align: 'center' },

Here the two buttons will be added to the Panel in a vertical layout and horizontally aligned to the center. Check out the image below,

This is one way of adding child components using xtype which is kind of a shortcut for declaring a component. There is another way as well, that is to explicitly create the child component object and then add to the Panel, like this

 var button = new Ext.Button({
                    text: 'Button1'
                });

First create the component such as the Button using the new keyword and then add it to the Panel,

 items: [
            button,
            { xtype:'button', text:'Button2', ui:'round'}
        ],
layout: { type: 'vbox', align: 'center' },

As seen above, we have both the ways of adding child components.
You can add a whole lot of different child components to the Panel, such as List, Audio, Video, Carousels, and other Panels etc. An example of adding a List control to a panel is shown below,

var contactList = new Ext.List({
                                    store: store,
                                    itemTpl: itemTemplate,
                                    height:"100%"
                               });
new Ext.Panel({
                   fullscreen:true,
                   layout:'fit',
                   items:[contactList]
             });

If you have not worked with List component before, please see my earlier tutorials which explains it in details.

Adding HTML content
You can also add plain HTML content directly to the Panel body by using the html property. This is how to do it,

html:'This is HTML text'

You can define any HTML tag and create an HTML string. You can also style the HTML content by using custom CSS class. This is how to do it,

new Ext.Panel({
                    fullscreen: true,
                    styleHtmlContent:true,
                    layout: 'fit',
                    html:'<div id="box">This is HTML text</div>'
                });

First create the HTML content and then style it using CSS as I have done below,

<style type="text/css">
        #box
        {
            -webkit-border-radius:5px;
            background-color:#fff;
            border:1px solid #ccc;
            width:100%;
            height:100px;
            padding:10px;
        }
    </style>

The image below shows the end result.

Note that you can add child components using the items array property and HTML content simultaneously to the Panel body.

Complete Example
Putting it altogether, here is a complete example of all the things discussed above,

<!DOCTYPE html>
<html>
<head>
    <title>Sencha Touch Panel Tutorial</title>
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
    <link href="css/sencha-touch.css" rel="Stylesheet"/>
    <style type="text/css">
        #box
        {
            -webkit-border-radius:5px;
            background-color:#fff;
            border:1px solid #ccc;
            width:100%;
            height:100px;
            padding:10px;
        }
    </style>
    <script type="text/javascript" src="js/sencha-touch-debug.js"></script>
    <script type="text/javascript">
        Ext.setup({
        onReady: function() {
                var button = new Ext.Button({
                    text: 'Button1'
                });
                new Ext.Panel({
                    fullscreen: true,
                    styleHtmlContent:true,
                    dockedItems: [
                        { xtype: 'toolbar', dock: 'top', title: 'Contact List' },
                        { xtype: 'button', dock: 'bottom', text: 'Click' }
                    ],
                    items: [
                         button,
                        { xtype:'button', text:'Button2'}
                    ],
                    layout: { type: 'vbox', align: 'center' },
                    html: '<div id="box">This is HTML text</div>'
                });
            }
        });    

    </script>
</head>
<body>
</body>
</html>

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s