Ext JS Toolbars, Menus and Buttons Guide

David Feinberg Copyright 2011 Sencha, Inc. All rights reserved. Pre-Release Content All the content in this guide is based on a early pre-release version of Ext JS 4. The concepts and code examples presented in this guide may not be applicable to the final release.

Table of Contents
5. Toolbars, Buttons & Menus .......................................................................................... 1 ............................................................................................................................... 1 Overview ................................................................................................................. 1 Introduction to Ext.Toolbar ....................................................................................... 1 Introduction to Ext.Button ......................................................................................... 3 Introduction to Ext.Menu .......................................................................................... 4 Arranging Toolbar Items ........................................................................................... 7 Putting Toolbars, Buttons and Menus to Work ......................................................... 10 Links ..................................................................................................................... 13

iii

List of Figures
5.1. 5.2. 5.3. 5.4. 5.5. 5.6. 5.7. Toolbars Alone and Docked to a Panel. ..................................................................... 1 Buttons Within a Toolbar and Alone ........................................................................... 3 CSS File ................................................................................................................... 4 Menus in a Toolbar and Alone ................................................................................... 5 CSS File ................................................................................................................... 7 Toolbar arrangement and overflow ............................................................................. 8 Displaying an Alert Message Box on Menu Item Click ............................................... 11

iv

Toolbars, Buttons & Menus

All the content in this guide is based on a early pre-release version of Ext JS 4. The concepts and code examples presented in this guide may not be applicable to the final release.

Overview
This guide provides a series of examples to help you start working with Ext.Toolbar, Ext.Menu and Ext.Button components. You'll learn how these three components work individually and together to provide an integrated set of tools for user interaction.

Introduction to Ext.Toolbar
The Ext.Toolbar component is designed to make it easy to add toolbar interfaces to your Ext JS powered applications. Toolbars commonly contain different types of Ext.Button and Ext.menu.Menu components for user interaction. In addition to holding Menus and Buttons Ext.Toolbar extends Ext.Container which allows it to contain any descendant of Ext.Component one of the core framework classes. This flexibility allows you to customize Toolbars to support a wide range of user interface solutions. Let's jump right into it and see how quickly we get some toolbars displayed on-screen. An Ext.Toolbar component can be displayed anywhere in an Ext JS application although most of the time you'll be working with Toolbars that are docked inside Panels and components that subclass Ext.Panel. In this example we'll display a few empty toolbars on-screen. One is configured to display outside of the Panel and the other two are docked to the top and bottom of the Panel.

Figure 5.1. Toolbars Alone and Docked to a Panel.

Toolbars, Buttons & Menus

Ext.onReady(function() { var sampleToolbar = new Ext.Toolbar({ width: 400, height: 40, renderTo: Ext.getBody(), style: { marginBottom: '20px'} }); // 1

// 2 // 3

var samplePanel = new Ext.Panel({ // 4 width: 400, height: 300, title: "Panel with Top & Bottom Toolbars", tbar: { // 5 height: 30 }, bbar: { // 6 height: 30 }, renderTo: Ext.getBody() }); });

1. The first Toolbar is created by instantiating a new Ext.Toolbar component and setting a few basic configuration options to specify height, width and rendering. 2. The first Toolbar renders directly to the document body retrieved with the utility method Ext.getBody on the global singleton Ext. 3. A 20 pixel margin is added to the bottom of the Toolbar using the style config option. This provides some space between the first Toolbar and the Panel below it. 4. We instantiate an Ext.Panel that we'll dock our Toolbars to. 5. Here we set the Panel's tbar configuration option to a Ext.Toolbar configuration object (the same one we could use to instantiate an Ext.Toolbar directly). This is a nice convenience provided by Ext.Panel which uses the configuration object we set here to automatically create an Ext.Toolbar instance for us and docks it to the top of the Panel. 6. The bbar option works just like tbar allowing us to set an Ext.Toolbar configuration object that's used to automatically create a bottom Toolbar for the Panel. By setting the tbar and bbar configuration options we were able to quickly add top and bottom Toolbars to a Panel. In this example we set these values with a Toolbar configuration object. In addition to that approach both tbar and bbar can also be set with an existing Toolbar object or directly with an array of button configuration objects and it will automatically perform the appropriate actions to create a Toolbar instance and dock it to the Panel. Now that you've seen how easy it is to work with an empty Toolbar we'll go over the most common components to add to start bringing our Toolbars to life.

Toolbars, Buttons & Menus

Introduction to Ext.Button
Ext.Button is a versatile component that can be used to add many different types of buttons to Ext JS applications. Built-in configuration options are available for creating common button types including; text buttons, icon driven buttons and menu buttons. The flexible design of Ext.Button makes it a great building block for custom button implementations. Let's get started seeing a few different types of buttons in action then we'll go over the code we used to create them. Like toolbars buttons can be used completely on their own or combined with other Ext Components.

Figure 5.2. Buttons Within a Toolbar and Alone

Ext.onReady(function() { var sampleButton = new Ext.Button({ text: 'Text Button', renderTo: Ext.getBody() }); var samplePanel = new Ext.Panel({ width: 400, height: 300, title: "Top Toolbar with Buttons", // 1

Toolbars, Buttons & Menus

tbar: { items: [{ xtype: 'button', text: 'Refresh' }, { xtype: 'button', iconCls: 'email-add-icon', text: 'New Message' }] }, renderTo: Ext.getBody(), style: { marginTop: '20px'} }); });

// 2

// 3

Figure 5.3. CSS File

.email-add-icon { background-image: url(images/email_add.png); } 1. Here we're creating an instance of the Ext.Button class just by setting two configuration options text and renderTo. This creates a button labeled "Text Button" and renders it to the document body. 2. Next we setup a top Toolbar within our Panel. The Toolbar is configured with an array of Button configuration objects. The first is a simple text button labeled "Refresh". 3. For the second Button we set the iconCls config option to "email-add-icon" which is a CSS class that sets the background image of the Button to an icon referenced in a CSS file (shown below the JavaScript). For this example we're using an 16x16px image from the FamFamFam Silk icon library. You can use any image you want and the Button object will automatically size itself to fit the image. This example demonstrated how to begin working with the Ext.Button component. We rendered a Button on its own and a couple inside a Toolbar using the convenience of xtypes. We saw some examples of common Button types and Button configuration options. We'll continue building on this example by adding menus to the Toolbar next.

Introduction to Ext.Menu
The Ext.menu.Menu component provides integrated menu capabilities for Ext JS components. The Ext.menu package includes classes for a number of common Menu Items that Ext.menu.Menu works with out-of-the-box. In addition to the built-in Menu Item classes Ext.menu.Menu can also be used to hold any component that descends from Ext.Component including all the components in the Ext.form package. Ext.menu.Menu is a flexible component for creating menu driven interfaces and can be extended to create completely custom Menu implementations. In this example we'll see how using Ext.menu.Menu by itself simply provides a specialized type of Container for holding menu items. Then we'll demonstrate how the Menu component becomes practical when combined with other Ext components. Here we'll combine it with Ext.Button to quickly create different types of Menu Buttons.

Toolbars, Buttons & Menus

Figure 5.4. Menus in a Toolbar and Alone

At the top we're displaying a Ext.menu.Menu component entirely on its own just to show what an isolated Menu looks like. This is the same way a context menu would display if a user right clicks on a Ext.GridPanel that has its contextmenu option configured. Under the floating menu the single panel from the code example is shown three times to demonstrate how each of the Menus look with different configuration options applied. new Ext.menu.Menu({ items: [{ text: "<b>Bold</b>" }, { text: "<i>Italic</i>" }, { text: "<u>Underline</u>" }], floating: false, width: 100, renderTo: Ext.getBody() });

// 1

// 2 // 3

1. A new Ext.menu.Menu object is instantiated here and Ext.menu.Item components are created just by setting the text configuration value for each item. This works without explicitly setting an xtype because the default xtype for Ext.menu.Menu is already set to Ext.menu.Item 2. The floating config option is set to false here to make sure the Menu is displayed in a viewable area. By default Menu will be rendered in a floating Ext.Layer and absolutely positioned off-screen. This is by design as in most cases you'll be using Menu with other Ext components and you'll want to control exactly where the menu appears using show, showAt or setPosition among other configuration options. 3. Here the width config is set to 100 pixels to keep the menu size appropriate for the items we're displaying.

Toolbars, Buttons & Menus

new Ext.Panel({ width: 290, height: 300, title: "Toolbar with Button Menus", tbar: { items: [{ xtype: 'button', text: 'Simple Menu', menu: { showSeparator: false, items: [{ text: 'menu item one' }, { text: 'menu item two' }] } }, // 4 // 5

4. For the first item in the Toolbar we setup a simple text Ext.Button and set the Button's menu config option with an Ext.menu.Menu configuration object. By setting the Button's menu config it will automatically create an instance of Ext.menu.Menu for us and display it when the button is clicked. You can also programmatically show and hide the Menu using the Button's showMenu and hideMenu methods. 5. The showSeparator config option is set to false here to demonstrate how you can remove the incised line along the left side of the menu which looks a bit cleaner for menus containing all text items.

{ xtype: 'button', iconCls: 'email-add-icon', text: 'Message Type', menu: [{ text: 'email message', iconCls: 'email-icon' },{ text: 'sms message', iconCls: 'email-icon' },{ text: 'push message', iconCls: 'email-icon' }] }, { xtype: 'splitbutton', text: 'Split Button', iconCls: 'user-add-icon', menu: [{ text: "<b>Bold</b>" },

// 6

// 7

Toolbars, Buttons & Menus

{ text: "<i>Italic</i>" }, { text: "<u>Underline</u>" }] }] }, renderTo: Ext.getBody(), style: { marginTop: '20px'} }); }); 6. For the second Menu Button an array Ext.menu.Item configuration objects is set for the value of menu instead of an Ext.menu.Menu configuration object to demonstrate another way of configuring a Menu Button. We also use the iconCls as we did before along with some CSS to display an icon to the left of the Menu Item's text. 7. For the last Button in the Toolbar the xtype is set to splitbutton which creates an Ext.SplitButton instead of the Ext.Button objects we used for the first two buttons in the Toolbar. Ext.SplitButton creates a built-in dropdown arrow allowing the user to trigger displaying the Menu separate from clicking the Button. This design fires two unique events which gives you the ability to execute different code depending on where the user clicks. We'll walk-through an example of how this works later in this guide.

Figure 5.5. CSS File

.email-icon { background-image: url(images/email.png); } .email-add-icon { background-image: url(images/email_add.png); } .user-add-icon { background-image: url(images/user_add.gif); } After exploring the code for this example you should have a good grasp on how to start working with Ext.menu.Menu class and integrating some basic Menus, Buttons and Toolbars together. Up until now we've been adding components to our Toolbar without paying much attention to arranging Toolbar items. In the next example we'll explore the Toolbar layout and some special Toolbar Items you can use to control the spacing and positioning of components in your Toolbars.

Arranging Toolbar Items

By default Ext.Toolbar uses Ext.layout.ToolbarLayout to arrange the items it contains. The ToolbarLayout is designed to arrange items side-by-side across the horizontal length of the Toolbar. Beyond basic layout controls ToolbarLayout also has the ability to automatically provide users with access to items that overflow the Toolbar through a dynamically generated Ext.menu.Menu that holds overflowed items as the size of Toolbar is adjusted directly or by a containing component. In addition to arranging Toolbar items with the ToolbarLayout Ext JS also provides three specialty Toolbar Items (Fill, Separator and, Spacer) that can be added to Toolbars to control spacing and separation between items. We'll go through a small example to demonstrate how you can use these tools to arrange Toolbar items.

Toolbars, Buttons & Menus

Figure 5.6. Toolbar arrangement and overflow

In this example six different Buttons are configured inside a Toolbar to demonstrate how you can use some of the built-in configuration options of classes in the Ext.Toolbar package to arrange Toolbar items directly from JavaScript without diving into the underlying CSS.

Ext.onReady(function() { new Ext.Panel({ width: 430, height: 300, title: "Arranging Toolbar Items", tbar: { enableOverflow: true, items: [{ xtype: 'button', text: 'Text Menu', menu: { plain: true, showSeparator: false, items: [{ text: 'menu item one' }, { text: 'menu item two' }, { text: 'menu item three' }] } },

// 1

Toolbars, Buttons & Menus

1. Here the enableOverflow option of the Toolbar is set to true so it automatically displays a drop down menu allowing users to access items that don't fit inside the specified width. In this example the Toolbar width has been purposely constrained to 430 pixels to demonstrate how the last two Buttons look when they automatically appear in the overflow menu.

Note
The default value for enableOverflow is false causing overflowed items to display clipped or outside the viewable area of the Toolbar.

{ xtype: 'tbspacer', width: 20 }, { xtype: 'button', iconCls: 'email-add-icon', text: 'Messages', menu: [{ text: 'email message', iconCls: 'email-icon' },{ text: 'sms message', iconCls: 'email-icon' },{ text: 'push message', iconCls: 'email-icon' }] }, // 2

2. The xtype tbspacer is used here to reference Ext.Toolbar.Separator. This provides a convenient way to specify spacing between Toolbar items simply by including a Ext.Toolbar.Separator configuration object between the items you want to separate and setting a value in pixels for its width. This is one of the three built-in subclasses of Ext.Toolbar.Item designed to make it easier to arrange items inside Toolbars.

{ xtype: 'tbfill' }, { xtype: 'button', text: 'Right Button' }, { xtype: 'tbseparator' }, { xtype: 'splitbutton', text: 'Split Button', iconCls: 'add16', 9 // 3

// 4

Toolbars, Buttons & Menus

menu: [{ text: "<b>Bold</b>" }, { text: "<i>Italic</i>" }, { text: "<u>Underline</u>" }] }, { xtype: 'button', text: 'Overflowed Text Button' }, { xtype: 'button', iconCls: 'email-icon', text: 'Overflowed Icon Button' }] }, renderTo: Ext.getBody() }); });

3. Here the tbfill xtype is used to reference Ext.Toolbar.Fill which changes the alignment of Toolbar items added from that point on to become right-justified instead of the default left-justified style. In this example tbfill is responsible for causing all the renaming buttons starting with the button labeled "Right Button" to be right-justified. 4. The tbseparator xtype is included between the buttons labeled "Right Button" and "Split Button" to display a visual separator between the two items in the form of a dotted vertical line. This is a common user interface element conveniently included in Ext JS to make it easy to visually group similar buttons together inside your Toolbars.

Note
Although it's possible to override the default ToolbarLayout it's not recommend unless you have a highly specialized use case for using another layout.

Putting Toolbars, Buttons and Menus to Work

Now that we've explored how to configure and arrange Toolbars, Buttons and Menus it's time to actually put these components to work for us by showing how you can wire up some simple JavaScript functions that will execute as you interact with these controls. Similar to the previous examples we'll display a few types of Buttons inside a Toolbar then we'll take things one step further by wiring up event handlers to respond to some of the builtin Button events. We'll also go over a couple techniques to access the components containing our Menus and Buttons to provide a glimpse at how you might use these components together in a real-world application.

10

Toolbars, Buttons & Menus

Note
The code we'll explore is designed to demonstrate specific concepts in a short block of code. The pattern shown here shouldn't be used as a model for constructing large-scale applications. We'll cover best practices for code organization and application architecture in more advanced guides.

Figure 5.7. Displaying an Alert Message Box on Menu Item Click

This example sets up a Panel with a Toolbar containing three items, a standard Button, SplitButton and, a spacer between them. Two different techniques are used to demonstrate how functions can be executed when a Button or Menu Item is clicked. Within these functions you'll see a few different ways to access the Toolbar and Panel that contain the Buttons and Menu Items. This is a common pattern in real-world applications where toolbar items usually allow users to perform actions on surrounding interface components. To keep things simple this example displays some simple messages when components are clicked. Although we could have used the standard JavaScript alert box we introduce Ext.Msg.alert which is a specialized Ext JS styled MessageBox that provides a convenient way to display messages consistent with the look and feel of your overall application. Ext.onReady(function() {

new Ext.Panel({ width: 350, height: 300, title: "Wiring Up Toolbars, Buttons & Menus", tbar: { items: [{ xtype: 'button', iconCls: 'email-icon', handler: function(buttonObj, eventObj) { // 1 var tbrItemCount = buttonObj.ownerCt.items.length; // 2 Ext.Msg.alert("Message", "I'm in a Toolbar containing " + tbrItemCount + " ite },

11

Toolbars, Buttons & Menus

text: 'View Messages' }, 1. The function set for the handler configuration option automatically executes when the Button is clicked passing in two values; the Button object itself and an instance of Ext.EventObject which wraps the native browser click event. 2. The ownerCt property of the Button object allows you to access the owner container of the Button which in this example is the Toolbar. The items property of the Toolbar contains the collection of three components (two buttons and a spacer between them) that we set for the Toolbar using the items confguration option. A local variable tbrItemCount is used to hold the number 3, the length of the Toolbar's items collection. 3. Ext.Msg.alert displays a themed alert style MessageBox when the Button is clicked. The MessageBox is passed two strings. The first string appears in the title area of the box and the second displays inside the box along with an "OK" Button that automatically closes the box when clicked just a like a regular JavaScript alert box. {

xtype: 'tbspacer', width: 5 }, { xtype: 'splitbutton', iconCls: 'email-add-icon', text: 'New Message', listeners: { // 4 'arrowclick': function(buttonObj, eventObj) { Ext.Msg.alert("Message", "You clicked the menu arrow!"); }, 'click': function(buttonObj, eventObj) { Ext.Msg.alert("Message", "You clicked the '" + buttonObj.text + "' button."); } }, 4. Here a SplitButton is being used to demonstrate how you can setup two different functions to execute depending on whether the user clicks the actual Button or the Menu arrow. The listeners configuration option is used instead of the handler option that was used for the previous Button. While the handler option is a convenient way to execute a function when a Button's click event is fired using the listeners option allows you to setup handler functions that can be configured to execute when any of the available Button events are fired. Here the first function is configured to execute when the arrowclick event fires (whenever the Menu arrow is clicked). The second function is set to execute when the Button's click event is fired (whenever the Button is clicked). The latter works the same as if you had set the function using the handler option. When executed both functions display a message inside an Ext.Msg.alert box. menu: [{ text: 'email message', iconCls: 'email-icon', listeners: {

12

Toolbars, Buttons & Menus

'click': function(menuItemObj, eventObj) { var panelTitle = menuItemObj.findParentByType('panel').title; // 5 Ext.Msg.alert("Message", "Menu Item: \"" + menuItemObj.text + "\" | Panel: \ } },{ text: 'sms message', iconCls: 'email-icon' },{ text: 'push message', iconCls: 'email-icon' }] }] }, renderTo: Ext.getBody() }); }); 5. This line demonstrates using the findParentByType method that's available to the Menu Item object passed into the function when the Menu Item is clicked. The findParentByType method is available to all classes that inherit from Ext.Component and allows you to find any component above the component you call it from (in this case Ext.menu.Item) by xtype. This example only uses a Panel with a Toolbar and a few buttons so the following components are considered above the Menu Item (Menu, SplitButton, Toolbar and Panel). By passing the "panel" string to findParentByType it returns a reference to the first Panel it encounters which in this case happens to be the only one in the application. Directly after the call to findParentByType the title property of the Panel is accessed and saved to a local variable named panelTitle. That variable is used on the next line to display the title of the Panel in an Ext.Msg.alert box. The last example brought together many of the concepts covered in this guide to show an example of Toolbars, Buttons and Menus all working together to create interactive interface controls. The code for the last example jumped right into working with events to explore how easy it is to setup custom functions that execute when different events are fired by components in your application. It also showed a few techniques for accessing Toolbars and Panels from the Buttons and Menus they contain. More in-depth examples of events and accessing related components will be covered in later guides.

Links
Ext JS Button Examples Ext JS Toolbars & Button Menus Examples Ext JS Toolbar with Menus Ext JS Toolbar Overflow Example

13