Learning Ext JS 3.2

Build dynamic, desktop-style user interfaces for your data-driven web applications using Ext JS

• Learn to build consistent, attractive web interfaces with the framework components
• Integrate your existing data and web services with Ext JS data support
• Enhance your JavaScript skills by using Ext’s DOM and AJAX helpers
• Extend Ext JS through custom components
• An interactive tutorial packed with loads of example code and illustrative screenshots

       

What’s on the menu?

We will begin by introducing the Menu class which will be used in all following examples.

We are going to demonstrate usage of the Menu class as both a static component within a page, and as a popup. Both menus will be configured with the same options by using a technique where we define a variable called menuItems to reference an array which specifies the menu’s items, and use it in both cases.

The Menu class inherits from Container, so any menu options are child Components specified in the items config. It also inherits the usual Component config options such as renderTo, and the width option.

The static menu will be rendered to the document body, and in order for it to be rendered as a visible, static element in the document, we configure it with floating: false.

So the configuration we end up with is as follows:

new Ext.menu.Menu({
renderTo: document.body,
width: 150,
floating: false,
items: menuItems
});

The popup menu needs no extra configuring aside from its items. We do need to decide when and where to display it. In this case we will add a contextmenu (right click) event listener to the document, and show the menu at the mouse event’s position:

var contextMenu = new Ext.menu.Menu({
items: menuItems
});
Ext.getDoc().on({
contextmenu: function(eventObj) {
contextMenu.showAt(eventObj.getXY());
},
stopEvent: true
});

When we run this example, the static menu will be visible. When we right click on the document, the result should be the two menus shown below. Notice how only the second, popup menu has a shadow to indicate that it floats above the document.

The menu’s items

The menuItems variable references an array which should be familiar by now. Just like the items config of a FormPanel, it’s a list of child Components or config objects. In a menu, a config object with no xtype creates a MenuItem Component. The MenuItem class accepts the following config options in addition to those it inherits:

• icon: The URL of an image to display as an icon
• iconCls: A CSS class name which allows a stylesheet to specify a background image to use as an icon
• text: The text to display
• handler: A function to call when the item is clicked
• menu: A Menu object, or Menu configuration object or an array of menu items to display as a submenu when the item is clicked

Because a menu inherits from Container, it can accept other Components as child items. If some complex, menu option dependent input is required, a menu may be configured with a panel as a child item. The menu config of “Menu Option 2” we’re creating next contains a FormPanel as its sole child item:

{
text: ‘Menu Option 2’,
iconCls: ‘flag-green’,
menu: {
plain: true,
items: {
xtype: ‘form’,
border: false,
bodyStyle: ‘background:transparent;padding:5px’,
labelWidth: 70,
width: 300,
defaults: {
anchor: ‘100%’
},
items: [{
xtype: ‘combo’,
editable: false,
fieldLabel: ‘Select’,
triggerAction: ‘all’,
store: [ [0, ‘One or…’], [1 ,’The other’]],
value: 0,
getListParent: function() {
return this.el.up(‘div.x-menu’);
}
}, {
xtype: ‘textfield’,
fieldLabel: ‘Title’
}],
fbar: [{
text: ‘Submit’
}]
}
}
}

The configurations in the above object will mostly be familiar by now.

There is one extra config we use for the menu which contains the FormPanel.

• plain: Specify as true so that the menu does not have to show the incised line for separating icons from text

The panel within the menu has the following configs:

border: Specify as false to produce a panel with no borders.

bodyStyle: A CSS style string to apply to the document body. We want to make it transparent to allow the menu to show, and we apply padding.

The ComboBox must render its dropdown list to the menu’s element so that clicking on the list does not trigger the menu to hide:

• GetListParent: This is a function which a ComboBox may be configured with. It must return the HTML element to render the dropdown list into. By default a ComboBox renders its dropdown into the document. We call the up function of the Ext.Element class to find the ancestor node of the combo’s element which is a DIV which has the CSS class “x-menu”.

The FormPanel as a child of a menu will display like this:

A toolbar for every occasion

An Ext JS Panel, and every Ext JS Component which inherits from the Panel class (This includes Window, TreePanel, and GridPanel) can be configured to render and manage a toolbar docked above, or below the panel’s body—or both if really necessary. These are referred to as the top and bottom toolbars, or tbar and bbar for short.

Panels and subclasses thereof may also be configured with a footer bar which renders buttons right at the bottom of the panel—below any bottom toolbar.

The Toolbar class is also an Ext JS Component in its own way, and may when necessary be used on its own, or as a child Component of any Container.

Our second example renders a toolbar standalone into the body of the document. We will use all the main button types to illustrate their usage before moving on to add handlers to react to user interaction. The toolbar will contain the following child components:

• A basic button
• A button configured with a menu which is displayed when the button is clicked
• A SplitButton which will display a menu only when its arrow glyph is clicked
• A CycleButton which on click, cycles between three different options
• A pair of mutually exclusive toggle buttons of which only one may be in a “pressed” state at once

Ext.onReady(function(){
new Ext.Toolbar({
renderTo: Ext.getBody(),
items: [{
xtype: ‘button’,
text: ‘Button’
},{
xtype: ‘button’,
text: ‘Menu Button’,
menu: [{
text: ‘Better’
},{
text: ‘Good’
},{
text: ‘Best’
}]
},{
xtype: ‘splitbutton’,
text: ‘Split Button’,
menu: [{
text: ‘Item One’
},{
text: ‘Item Two’
},{
text: ‘Item Three’
}]
}, {
xtype: ‘cycle’,
showText: true,
minWidth: 100,
prependText: ‘Quality: ‘,
items: [{
text: ‘High’,
checked: true
}, {
text: ‘Medium’
}, {
text: ‘Low’
}]
}, {
text: ‘Horizontal’,
toggleGroup: ‘orientation-selector’
}, {
text: ‘Vertical’,
toggleGroup: ‘orientation-selector’
}]
});
});

As usual, everything is inside our onReady event handler. The items config holds our toolbar’s entire child Components—I say child Components and not buttons because as we now know, the toolbar can accept many different types of Ext JS Components including entire forms or just form fields—which we will be implementing later on in this article.

The result of the above code looks like this:

The default xtype for each element in the items config is button. We can leave out the xtype config element if button is the type we want, but I like to include it just for clarity.

Button configuration

In addition to inherited config options, a button accepts the following configurations which we will be using in the following examples for this article:

• icon: The URL of an image to display as an icon
• iconCls: A CSS class name which allows a stylesheet to specify a background image to use as an icon
• text: The text to display
• handler: A function to call when the button is clicked
• menu: A Menu object, or Menu configuration object, or an array of menu items to display as a submenu when the button is clicked
• enableToggle: Specify as true to make a single button toggleable between pressed and unpressed state
• toggleGroup: A mnemonic string identifying a group of buttons of which only one may be in a “pressed” state at one time
• toggleHandler: A function to be called when a button’s “pressed” state is changed

A basic button

Creating a button is fairly straightforward; the main config option is the text that is displayed on the button. We can also add an icon to be used alongside the text if we want to. A handler function is called when the button is clicked.

Here is the most basic configuration of a button:

{
xtype: ‘button’,
text: ‘Button’,
handler: functionReference
}

The following screenshot shows what happens when the mouse is hovered over the Button button:

Button with a menu

A button may be configured to act as a trigger for showing a dropdown menu. If configured with a menu option, clicking the button displays a menu below the button. The alignment of the menu is configurable, but defaults to being shown below the button.

Each option within the menu may itself be configured with a menu option allowing a familiar cascading menu system to be built very easily. The following is a config for a button which displays a dropdown menu upon click:

{
xtype: ‘button’,
text: ‘Button’,
menu: [{
text: ‘Better’
},{
text: ‘Good’
},{
text: ‘Best’
}]
}

The following screenshot shows what happens when the Menu Button is clicked on, and the mouse is hovered over the Best option: