Command Control
| Button, ComboButton, DropDownButton | [inline:button.png] |
| Menu | [inline:menu.png] |
| Toolbar | [inline:toolbar.png] |
Button, ComboButton, DropDownButton
Buttons are very popular UI elements, and Dijit has a bunch of them, from a simple click and go button to a DropDownButton, and much more.
Examples
Creating a Click and Go Button
A normal click-and-go button is simple to make and can be enhanced by using image icons, for example. The following markup creates a normal click-and-go button that calls a single JavaScript function:
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Click and Go Button Demo</title>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.form.Button");
function call_function() {
console.debug("Button was clicked.");
}
</script>
</head>
<body class="tundra">
<button dojoType="dijit.form.Button" onclick="call_function">
Hi I am the One !!
</button>
</body></html>
You can set text on a button by using the label attribute. To display an image on the button, you use the iconClass attribute, then set up a CSS class which uses that icon as a background-image. See Toolbar for a description of sprites, a technique which can make multiple icons load faster.
Programatically Creating a Button
The following code creates a button programatically:
/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #b1b100;} .geshifilter .kw2 {color: #000000; font-weight: bold;} .geshifilter .kw3 {color: #000066;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #cc66cc;} .geshifilter .sc0 {color: #00bbdd;} .geshifilter .sc1 {color: #ddbb00;} .geshifilter .sc2 {color: #009900;}"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Click and Go Button Demo</title>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/0.9.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/0.9.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.form.Button");
function call_function() {
console.debug("Button was clicked.");
}
function create_button()
{
var params = {
label: "Hi I am the Second one",
// Note here, when creating programmatically, this is a function, not a string
onClick: call_function
};
var button_dynamic = new dijit.form.Button(
params,dojo.byId("button-placeholder")
);
}
dojo.addOnLoad(create_button);
</script>
</head>
<body class="tundra">
<div id="button-placeholder"> </div>
</body></html>
The created button will take the place of the provided DIV node; in the example, this is the DIV with the ID "button-placeholder". Alternatively, you can use the DOM's createElement() call to create the DIV programmatically, then pass it to the dijit.form.Button constructor.
Creating DropDownButtons
There are, of course, fancier buttons that can be used to make a Web application more like a desktop application, thus providing the power of web 2.0 UI. DropDownButtons provide a drop-down menu when clicked, which is rendered using the dijit.Menu widget of the dijit system and follows the Menu rules. A PopupMenuItem always has two child nodes: a tag with the displayed label (usually in a SPAN tag), and a widget to be popped up, typically a dijit.Menu widget. For example:
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>DropDownButton Demo</title>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.form.Button");
dojo.require("dijit.Menu");
function call_function(choice) {
console.debug(choice+" was clicked.");
}
</script>
</head>
<body class="tundra">
<div dojoType="dijit.form.DropDownButton">
<span>Edit</span>
<div dojoType="dijit.Menu" id="Edit">
<div dojoType="dijit.MenuItem" label="Copy"
onclick="call_function('copy');"></div>
<div dojoType="dijit.MenuItem" label="Cut"
onclick="call_function('cut');"></div>
<div dojoType="dijit.MenuItem" label="Paste"
onclick="call_function('paste');"></div>
</div>
</div>
</body></html>
In the preceding example, you need to require dijit.Menu alone to source dijit.Menu and dijit.MenuItem. DropDownButtons are used in Web applications like the rich text editor where you need a menu.
Creating ComboButtons
ComboButtons are one step ahead of DropDownButtons as they can be clicked and also offer present menu options like a DropDownButton. The following example shows a ComboButton being created:
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>ComboButton Demo</title>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.form.Button");
dojo.require("dijit.Menu");
function save_function() {
console.debug("Save was clicked.");
}
function save_as_function(choice) {
console.debug("Save As was clicked. Dialog box should go here.");
}
</script>
</head>
<body class="tundra">
<div dojoType="dijit.form.ComboButton" onclick="save_function">
<span>Save</span>
<div dojoType="dijit.Menu" id="saveMenu" toggle="fade" style="display: none;">
<div dojoType="dijit.MenuItem"
iconClass="dijitEditorIcon dijitEditorIconSave" onclick="save_function">
Save
</div>
<div dojoType="dijit.MenuItem" onclick="save_as_function">
Save As
</div>
</div>
</div>
</body></html>
The ComboButton class is declared in the Button.js file, so you only need to require the Button and Menu Classes.
|
dijit.form.Button, dijit.form.DropDownButton,
dijit.form.ComboButton,
Basically the same thing as a normal HTML button, but with special styling.
|
||
|
Attributes
|
||
| iconClass | String | class to apply to div in button to make it display an icon |
| label | String | text to display in button. Use setLabel() to change after creation time. |
| optionsTitle | String | text that describes the options menu (accessibility) |
| showLabel | Boolean | whether or not to display the text label in button |
|
Methods
|
||
| addChild | Process the given child widget, inserting it's dom node as a child of our dom node | |
| getChildren | returns array of children widgets | |
| setLabel | reset the label (text) of the button; takes an HTML string | |
| hasChildren | returns true if widget has children | |
| removeChild | removes the passed widget instance from this widget but does not destroy it | |
|
Extension Points
|
||
| onClick | callback for when button is clicked; user can override this function for some reason type=submit buttons don't automatically submit the form; do it manually | |
Accessibility
Keyboard
| Action | Key |
|---|---|
| Navigate to a button | tab - all buttons are in the tab order |
| Activate the button | enter or space key |
| Close an open drop down | escape key - focus returns to button |
| With drop down open, navigate to the next element on page | tab will close drop down and set focus back to the button, tab again to navigate to next element |
| Navigate to a checkbox | tab - all checkboxes are in the tab order |
| toggle a checkbox | space |
| Navigate to a radio button or group of radio buttons | tab - see below for browser differences |
| select a radio in a group | tab to the radio group, up down arrow to the desired radio item |
Checkboxes and Radio buttons are implemented using the standard input type=checkbox and type=radio elements respectively. CSS is used to overlay the unique theme over the actual input elements. Thus, the keyboard behavior of checkboxes and radio buttons mimics the behavior in the browser.
Radio buttons in Firefox 2: When radio buttons are grouped the selected radio button is in the tab order. If no radio is selected, each radio button in the group is in the tab order until one of the radios is selected by navigating to it using an arrow key or navigating to it using the tab key and pressing space.
Radio buttons in Internet Explorer 6 & 7: When radio buttons are grouped the selected radio button is in the tab order. If no radio is selected only one radio in the group is in the tab order. The first radio in the group is in the tab order when navigating forward to the radio group. The last radio in the group is in the tab order when navigating backward to the radio group. Once focus is in the radio group, use the arrow keys to select one of the radio buttons.
High Contrast Mode
All buttons should include a label parameter with text for the button even if the showLabel parameter is set to false. The label parameter is used to identify the button in high contrast mode when the icon for the button will no longer be displayed and is also used to identify the button to a screen reader.
Screen Reader
In order to identify the button description to the screen reader, all buttons should include a label parameter even if the showLabel parameter is set to false.
All Combo Buttons should include a optionsTitle parameter to identify the function of the drop down button. The optionsTitle parameter is used by the screen reader to speak the information about the drop down portion of the button. Note that the Window-Eyes screen reader will speak "question" and then the optionsTitle text when the drop down portion of the Combo button receives focus. The "question" is spoken because Window-Eyes does not recognize the html entity character that is used to provide the visual drop down arrow in the button.
Even though the dropdown and combo buttons are marked with the ARIA haspopup property, the screen readers do not indicate this to the user in Firefox 2. In Firefox 3 the dropdown and combo buttons will be announced as "menu button".
Updates for 1.0
Accessibility - Keyboard
Accessibility - Keyboard
When navigating to a ComboButton using the keyboard the focus is not visible using Firefox 2. The current versions of Firefox 3, however, do show a visible focus rectangle for the pieces of the ComboButton so the focus problem in Firefox 2 was not addressed within the dijit button code.
Menu
The Menu widget models a context menu, otherwise known as a right-click or popup menu, and they also appear in ComboButton and DropDownButton widgets.
MenuItem widgets are the actual items in the menu. The PopupMenuItem is like a MenuItem, but displays a submenu or other widget to the right . A PopupMenuItem always has two child nodes: a tag with the displayed label (usually in a SPAN tag), and a widget to be popped up, typically a dijit.Menu widget.
Example
Right click anywhere in Grey Area
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Menu Demo</title>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.Menu");
</script>
</head>
<body class="tundra">
<style>
.myIcon {
/* Note: Drupal may add an anchor tag here. Don't include it in your code */
background-image:
url(http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/images/checkmark.gif);
background-position: -16px 0px;
width: 16px;
height: 16px;
}
</style>
<div dojoType="dijit.Menu" id="submenu1"
contextMenuForWindow="true" style="display: none;">
<div dojoType="dijit.MenuItem" iconClass="myIcon"
onClick="alert('Hello world');">Enabled Item</div>
<div dojoType="dijit.PopupMenuItem" id="submenu2">
<span>Submenu</span>
<div dojoType="dijit.Menu">
<div dojoType="dijit.MenuItem"
onClick="alert('Submenu 1!')">Submenu Item One</div>
<div dojoType="dijit.MenuItem"
onClick="alert('Submenu 2!')">Submenu Item Two</div>
</div>
</div>
</div>
</body></html>
|
dijit.Menu
Define a drop down or context (right-click) menu.
|
||
|
Attributes
|
||
| contextMenuForWindow | Boolean false |
if true, right clicking anywhere on the window will cause this context menu to open; if false, must specify targetNodeIds |
| popupDelay | Integer 500 |
number of milliseconds before hovering (without clicking) causes the popup to automatically open |
| targetNodeIds | String[] | Array of dom node ids of nodes to attach to. Fill this with nodeIds upon widget creation and it becomes context menu for those nodes. |
|
Methods
|
||
|
Methods
|
||
| addChild(/*Widget*/ child, /*Integer?*/ insertIndex) | Process the given child widget, inserting its dom node as a child of our dom node | |
| bindDomNode(/*String|DomNode*/ node) | attach menu to given node | |
| Widget[] getChildren() | returns array of children widgets | |
| removeChild(/*Widget*/ page) | removes the passed widget instance from this widget but does not destroy it | |
| unBindDomNode(/*String|DomNode*/ nodeName) | detach menu from given node | |
|
Extension Points
|
||
| onClose() | callback when this menu is closed | |
| onOpen(/*Event*/ e) | Open menu relative to the mouse | |
|
dijit.MenuItem
One menu item, usable in a Menu
|
||
|
Attributes
|
||
| disabled | Boolean false |
if true, the menu item is disabled if false, the menu item is enabled. Use setDisabled() to change after creation time. |
| iconClass | String | class to apply to div in button to make it display an icon |
| label | String | Menu text. Typically specified as innerHTML when declaring a Menu programmatically. |
|
Methods
|
||
| setDisabled(/*Boolean*/ value) | enable or disable this menu item | |
|
Extension Points
|
||
| getParent() | returns the parent widget of this widget, assuming the parent implements dijit._Container | |
| onClick() | User defined function to handle clicks | |
|
dijit.MenuSeparator
A line between two menu items
|
Accessibility
Keyboard
| Action | Key |
|---|---|
| Open a context menu | On Windows: shift-f10 or the Windows context menu key On Firefox on the Macintosh: ctrl-space |
| Navigate menu items | Up and down arrow keys |
| Activate a menu item | Spacebar or enter |
| Open a submenu | Spacebar, enter, or right arrow |
| Close a context menu or submenu | Esc or left arrow |
| Close a context menu and all open submenus | Tab |
Known Issues
When reading a menu item on Firefox 2, JAWS 8 may say "submenu" for an item that does not have a submenu. This will be fixed in Firefox 3.
Toolbar
Just as dijit.Menu is a container for dijit.MenuItem's, so dijit.Toolbar is a container for buttons. Any button-based Dijit component can be placed on the toolbar, including ComboButtons and DropdownButtons.
Example
In this example, we borrow some of the toolbar buttons from the Editor
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<head>
<style type="text/css">
@import "http://o.aolcdn.com/dojo/1.0.0/dijit/themes/tundra/tundra.css";
@import "http://o.aolcdn.com/dojo/1.0.0/dojo/resources/dojo.css"
</style>
<script type="text/javascript" src="http://o.aolcdn.com/dojo/1.0.0/dojo/dojo.xd.js"
djConfig="parseOnLoad: true"></script>
<script type="text/javascript">
dojo.require("dojo.parser");
dojo.require("dijit.form.Button");
dojo.require("dijit.Toolbar");
function bold() { console.debug("Bold!"); }
function cut() { console.debug("Cut!"); }
function copy() { console.debug("Copy!"); }
function paste() { console.debug("Paste!"); }
dojo.addOnLoad(function() {
dojo.connect(dojo.byId("toolbar1.bold"),"onclick",bold);
dojo.connect(dojo.byId("toolbar1.cut"),"onclick",cut);
dojo.connect(dojo.byId("toolbar1.copy"),"onclick",copy);
dojo.connect(dojo.byId("toolbar1.paste"),"onclick",paste);
});
</script>
</head>
<body class="tundra">
<!-- Tags end on line afterwards to eliminate any whitespace -->
<div id="toolbar1" dojoType="dijit.Toolbar"
><div dojoType="dijit.form.Button" id="toolbar1.cut" iconClass="dijitEditorIcon dijitEditorIconCut"
showLabel="false">Cut</div
><div dojoType="dijit.form.Button" id="toolbar1.copy" iconClass="dijitEditorIcon dijitEditorIconCopy"
showLabel="false">Copy</div
><div dojoType="dijit.form.Button" id="toolbar1.paste" iconClass="dijitEditorIcon dijitEditorIconPaste"
showLabel="false">Paste</div
><!-- The following adds a line between toolbar sections
--><span dojoType="dijit.ToolbarSeparator"></span
><div dojoType="dijit.form.ToggleButton" id="toolbar1.bold"
iconClass="dijitEditorIcon dijitEditorIconBold" showLabel="false">Bold</div>
</div>
</body></html>
Where do the icons come from? The theme defines one large image with all the buttons. Tundra's editor button image looks like the following:
[inline:editor.gif]The particular icon is selected using the attribute "iconClass". The Cut button with class "dijitEditorIconCut" has the following definition in Tundra.css:
/* GeSHi (C) 2004 - 2007 Nigel McNie (http://qbnz.com/highlighter) */ .geshifilter {font-family: monospace;} .geshifilter .imp {font-weight: bold; color: red;} .geshifilter .kw1 {color: #000000; font-weight: bold;} .geshifilter .kw2 {color: #993333;} .geshifilter .co1 {color: #a1a100;} .geshifilter .coMULTI {color: #808080; font-style: italic;} .geshifilter .es0 {color: #000099; font-weight: bold;} .geshifilter .br0 {color: #66cc66;} .geshifilter .st0 {color: #ff0000;} .geshifilter .nu0 {color: #933;} .geshifilter .re0 {color: #cc00cc;} .geshifilter .re1 {color: #6666ff;} .geshifilter .re2 {color: #3333ff;} .geshifilter .re3 {color: #933;} .geshifilter .re4 {color: #933;}/* All of the selectors for the icons go here */
{
background-image: url('images/editor.gif'); /* mega-image */
background-repeat: no-repeat;
width: 18px;
height: 18px;
text-align: center;
}
.tundra .dijitEditorIconCut { background-position: -108px; }
The Cut icon starts 108 px from the right edge, and measures 18px by 18px. 108 equals 6 * 18, so it's the 6th image from the right. You can define your own buttons by setting up CSS selectors using code similar to the follwing, and wire up the iconClass.
|
dijit.Toolbar
Toolbar, which can be filled with ComboButton and DropDownButton instances
|
||
|
Methods
|
||
|
Methods
|
||
| addChild(/*Widget*/ child, /*Integer?*/ insertIndex) | Process the given child widget, inserting its dom node as a child of our dom node | |
| Widget[] getChildren() | returns array of children widgets | |
| removeChild(/*Widget*/ page) | removes the passed widget instance from this widget but does not destroy it | |
Accessibility (applies to version 1.0 of Toolbar)
Keyboard
| Action | Key |
|---|---|
| Move focus between widgets in the toolbar | Left and right arrow keys |
Known Issues (updatd for 1.0 - toggle buttons did not display in high contrst mode in 0.9)
In hign contrast mode when a toggle button is checked an html entity charcter (✓) is displayed since the CSS background image icon for the checked state is no longer visible. When the toggle button is part of a toolbar the checkmark character does not display properly in IE6. In IE6 with high contrast mode turned on, a checked toggle button in a toolbar displays as two vertical bars rather than the checkmark character.