Dojo: The Definitive Guide

Overview of Stock Dijits

Because Dojo's widget collection is incredibly extensive, it can be easy to get lost. This section presents a concise inventory of dijits so that you may be familiarized with what's available.

Form Dijits

The very naming convention for a category of "form dijits" implies that the dijits are designed to be used inside of a form. While this is certainly true, form dijits may also be used outside of forms or in a special dijit.form.Form dijit that provides some extra methods and extension points. Here's a very brief overview of what is included in each of those chapters. Recall that all dijits are a11y compatible and easily internationalized, where applicable.

Tip

Go to http://archive.dojotoolkit.org/nightly/ to view the Dijit test harnesses that contain all of these widgets. It's a great way to get a feel for just how much breadth and depth there really is.

Form

A special container for form widgets that provides handy methods and extension points for serializing to JSON, validating the entire form's contents, setting values for the form all at once, and event handling when the form is submitted.

Button variations

Drop-in replacements for ordinary buttons based on BUTTON elements as well as other button-like controls based on INPUT elements like checkboxes and radio elements. Additional button variations include menu-style buttons that have drop-down values (sort of like combo boxes) that are commonly shown in toolbars, and toggle buttons that commonly appear in toolbars such as bold and italic buttons.

ComboBox

A combination of the functionality provided by an ordinary SELECT combo box and a text field defined with an INPUT element, allowing users to choose from pre-filled selections or typing in their own values.

FilteringSelect

A drop-in replacement for an ordinary SELECT element. It may be populated dynamically, making it great for situations in which a very large number of selections may be possible.

NumberSpinner

Similar to a text box based on an INPUT element except that controls allow for making incremental adjustments to the value.

Slider

A draggable handle attached to a scale that may be laid out vertically or horizontally. This widget provides a more interactive way of adjusting a value and is commonly used in conjunction with a display that involves resizing two-dimensional objects in real time.

Textarea

A drop-in replacement for an ordinary TEXTAREA element, but resizes as necessary to fit its enclosed content so that valuable screen real estate isn't lost when the potential size of content may not be predictable or always annotated.

SimpleTextarea

A drop-in replacement for an ordinary TEXTAREA element with some additional machinery to interact with the Form dijit container and layout dijits.

MultiSelect

A drop-in replacement for an ordinary SELECT element that has the multiple=true attribute set. Like SimpleTextarea, it contains some extra machinery for interaction with the Form dijit.

TextBox variations

An entire family of feature-rich widgets based upon the INPUT element with a special emphasis for custom validation of values and formatting for common fields like date, time, currency, numbers, etc. An incredible amount of functionality is packed into this family of widgets.

Layout Dijits

Traditional techniques for complex layouts used to involve extensive CSS work. While CSS may not be rocket science, writing, maintaining, and testing it on multiple browsers requires nontrivial effort—especially if you're not a CSS guru. Layout dijits allow the layout to be constructed in markup—without resorting to nested tables—which seems to have made laying out a page a lot simpler. Layout dijits, in general, may be arbitrarily nested, which allows for extremely sophisticated designs at a fraction of the time involved with more traditional CSS-based techniques. Here's a synopsis of what Dijit provides:

ContentPane

The most basic building block for a layout and provides the actual wrapper for layout tile. Although they could be used as standalones, one or more ContentPane dijits generally exist as part of a container widget.

TabContainer

A means of providing a familiar, tabbed layout with the tabs appearing horizontally or vertically. Simple layouts with TabContainer s generally involve a TabContainer combined with a ContentPane, although arbitrary nesting is always a possibility. Content for tabs that are not initially displayed may be lazy loaded.

StackContainer

Provides a means of displaying multiple containers of information, but with only one container shown at a time. For example, multiple ContentPane s might contain individual slides for a presentation, and a StackContainer could be used to combine them all into a presentation. StackContainer s are also very handy for applications that have multiple "screens" that need to be displayed without the page ever reloading.

AccordionContainer

Displays one tile at a time, and when another tile is selected, the previously displayed tile folds up with a smooth animation. Content for tiles that are not initially displayed may be lazy-loaded.

BorderContainer

Provides a convenient way to easily achieve a typical "headline" style or "sidebar" style layout where there are multiple tiles on the screen and some of them span the entire height and width while others do not. Achieving a more complex layout "border-style" layout with up to five tiles on the screen (four tiles around the edges and a center tile that fills in the remainder) is trivial to achieve.

Application Dijits

Application dijits are the "other" category; they are all very common elements for any application that even begins to approach RIA functionality. Menus, toolbars, dialog overlays, and rich text editors are all part of the mix, and these dijits are so easy to use that you can't avoid wanting to:

Menu

Provides a contextual popup menu similar to what is commonly seen from right-clicking in a desktop application. Menu is also used to build complex buttons like ComboButton and DropDownButton to offer advanced functionality.

Toolbar

Provides a container for complex buttons such as ToggleButton that supply the controls for a toolbar, although any button dijit may be included in a toolbar.

Dialog

Simulates an ordinary desktop dialog box, complete with a translucent overlay that prevents interaction with content "below" the dialog. Dialog dijits are a fantastic, easily maintainable alternative to pop-up windows for many use cases, especially when any kind of communication or DOM manipulation would be necessary between multiple windows.^[23]

TooltipDialog

A combination of Tooltip and Dialog, which allows for delivering a dialog-style input in a tooltip. A key difference between Dialog and TooltipDialog is that the TooltipDialog may be dismissed by clicking anywhere not on the TooltipDialog, whereas a Dialog provides a translucent underlay that prevents interaction with the rest of the page until the Dialog is explicitly closed.

ProgressBar

Models ordinary progress bars as commonly seen in virtually every desktop application. ProgressBar dijits are the standard way of providing feedback on a long-running operation or an asynchronous call back to the server that takes longer than a few seconds. ProgressBar dijits may be determinate, providing a percentage complete as the indicator, or indeterminate, providing an arbitrary animation that indicates something is happening.

TitlePane

Offers functionality for displaying a pane of information with a title area on top. While the content of the pane may be closed or opened by clicking on an icon in the title area, the title area is always visible.

Tooltip

A much more flexible alternative to the ordinary title attribute for ordinary HTML controls. Timing and arbitrary HTML may be included in the tooltip text.

InlineEditBox

A sort of widget wrapper that displays the widget's value, which appears like a label; however, the widget transforms into its editable form when the text is clicked. (Very rich functionality.)

ColorPalette

By default, displays a 3 × 4 or 7 × 10 matrix of commonly used colors for users to select in a highly useful way. ColorPalette may be extended to display arbitrary color configurations.

Editor

Provides the equivalent of a minimally function rich-text editor, complete with a toolbar that is pre-configured for cut/copy/paste, undo/redo, text-alignment, basic markup such as bold/italic/strikethrough, and the ability to create bulleted lists. The toolbar may be customized as needed. A ridiculous amount of functionality is packed into this dijit, and it's much more lightweight than you might think, as Editor builds off of specific native controls such as Firefox's Midas rich text editor.

Tree

Delivers a tree with nodes that may be arbitrarily nested and closed/expanded as needed. This interface control is commonly used to deliver long, hierarchical lists of information. Content for nodes that are not expanded by default may be lazy-loaded; this dijit uses the terrific dojo.data API to deliver its content.

---

^[23] For some browsers, manipulating DOM nodes that are in another window isn't even possible because of security restrictions.