Just like the ViewHelper decorator, DijitElement expects a helper property in the element which it will then use as the view helper when rendering. Dijit parameters will typically be pulled directly from the element, but may also be passed in as options via the dijitParams key (the value of that key should be an associative array of options).

It is important that each element have a unique ID (as fetched from the element's getId() method). If duplicates are detected within the dojo() view helper, the decorator will trigger a notice, but then create a unique ID by appending the return of uniqid() to the identifier.

Standard usage is to simply associate this decorator as the first in your decorator chain, with no additional options.

The DijitForm decorator is very similar to the Form decorator; in fact, it can be used basically interchangeably with it, as it utilizes the same view helper name ('form').

Since dijit.form.Form does not require any dijit parameters for configuration, the main difference is that the dijit form view helper require that a DOM ID is passed to ensure that programmatic dijit creation can work. The decorator ensures this, by passing the form name as the identifier.

The DijitContainer decorator is actually an abstract class from which a variety of other decorators derive. It offers the same functionality of DijitElement, with the addition of title support. Many layout dijits require or can utilize a title; DijitContainer will utilize the element's legend property, if available, and can also utilize either the 'legend' or 'title' decorator option, if passed. The title will be translated if a translation adapter with a corresponding translation is present.

The following is a list of decorators that inherit from DijitContainer:

• AccordionContainer

• AccordionPane

• BorderContainer

• ContentPane

• SplitContainer

• StackContainer

• TabContainer

While not deriving from the standard Button element, it does implement the same functionality, and can be used as a drop-in replacement for it. The following functionality is exposed:

• getLabel() will utilize the element name as the button label if no name is provided. Additionally, it will translate the name if a translation adapter with a matching translation message is available.

• isChecked() determines if the value submitted matches the label; if so, it returns TRUE. This is useful for determining which button was used when a form was submitted.

Additionally, only the decorators DijitElement and DtDdWrapper are utilized for Button elements.

While not deriving from the standard Checkbox element, it does implement the same functionality. This means that the following methods are exposed:

• setCheckedValue($value): set the value to use when the element is checked.

• getCheckedValue(): get the value of the item to use when checked.

• setUncheckedValue($value): set the value of the item to use when it is unchecked.

• getUncheckedValue(): get the value of the item to use when it is unchecked.

• setChecked($flag): mark the element as checked or unchecked.

• isChecked(): determine if the element is currently checked.

As noted in the ComboBox dijit view helper documentation, ComboBoxes are a hybrid between select and text input, allowing for autocompletion and the ability to specify an alternate to the options provided. FilteringSelects are the same, but do not allow arbitrary input.

Note: ComboBoxes return the label values
ComboBoxes return the label values, and not the option values, which can lead to a disconnect in expectations. For this reason, ComboBoxes do not auto-register an InArray validator (though FilteringSelects do).

The ComboBox and FilteringSelect form elements provide accessors and mutators for examining and setting the select options as well as specifying a dojo.data datastore (if used). They extend from DijitMulti, which allows you to specify select options via the setMultiOptions() and setMultiOption() methods. In addition, the following methods are available:

• getStoreInfo(): get all datastore information currently set. Returns an empty array if no data is currently set.

• setStoreId($identifier): set the store identifier variable (usually referred to by the attribute 'jsId' in Dojo). This should be a valid javascript variable name.

• getStoreId(): retrieve the store identifier variable name.

• setStoreType($dojoType): set the datastore class to use; e.g., "dojo.data.ItemFileReadStore".

• getStoreType(): get the dojo datastore class to use.

• setStoreParams(array $params): set any parameters used to configure the datastore object. As an example, dojo.data.ItemFileReadStore datastore would expect a 'url' parameter pointing to a location that would return the dojo.data object.

• getStoreParams(): get any datastore parameters currently set; if none, an empty array is returned.

• setAutocomplete($flag): indicate whether or not the selected item will be used when the user leaves the element.

• getAutocomplete(): get the value of the autocomplete flag.

By default, if no dojo.data store is registered with the element, this element registers an InArray validator which validates against the array keys of registered options. You can disable this behavior by either calling setRegisterInArrayValidator(false), or by passing a FALSE value to the registerInArrayValidator configuration key.

The above examples could also utilize FilteringSelect instead of ComboBox.

The CurrencyTextBox is primarily for supporting currency input. The currency may be localized, and can support both fractional and non-fractional values.

Internally, CurrencyTextBox derives from NumberTextBox, ValidationTextBox, and TextBox; all methods available to those classes are available. In addition, the following constraint methods can be used:

• setCurrency($currency): set the currency type to use; should follow the » ISO-4217 specification.

• getCurrency(): retrieve the current currency type.

• setSymbol($symbol): set the 3-letter » ISO-4217 currency symbol to use.

• getSymbol(): get the current currency symbol.

• setFractional($flag): set whether or not the currency should allow for fractional values.

• getFractional(): retrieve the status of the fractional flag.

DateTextBox provides a calendar drop-down for selecting a date, as well as client-side date validation and formatting.

Internally, DateTextBox derives from ValidationTextBox and TextBox; all methods available to those classes are available. In addition, the following methods can be used to set individual constraints:

• setAmPm($flag) and getAmPm(): Whether or not to use AM or PM strings in times.

• setStrict($flag) and getStrict(): whether or not to use strict regular expression matching when validating input. If FALSE, which is the default, it will be lenient about whitespace and some abbreviations.

• setLocale($locale) and getLocale(): Set and retrieve the locale to use with this specific element.

• setDatePattern($pattern) and getDatePattern(): provide and retrieve the » unicode date format pattern for formatting the date.

• setFormatLength($formatLength) and getFormatLength(): provide and retrieve the format length type to use; should be one of "long", "short", "medium" or "full".

• setSelector($selector) and getSelector(): provide and retrieve the style of selector; should be either "date" or "time".

Editor provides a WYSIWYG editor that can be used to both create and edit rich HTML content. dijit.Editor is pluggable and may be extended with custom plugins if desired; see » the dijit.Editor documentation for more details.

The Editor form element provides a number of accessors and mutators for manipulating various dijit parameters, as follows:

• captureEvents are events that connect to the editing area itself. The following accessors and mutators are available for manipulating capture events:

  • addCaptureEvent($event)

  • addCaptureEvents(array $events)

  • setCaptureEvents(array $events)

  • getCaptureEvents()

  • hasCaptureEvent($event)

  • removeCaptureEvent($event)

  • clearCaptureEvents()

• events are standard DOM events, such as onClick, onKeyUp, etc. The following accessors and mutators are available for manipulating events:

  • addEvent($event)

  • addEvents(array $events)

  • setEvents(array $events)

  • getEvents()

  • hasEvent($event)

  • removeEvent($event)

  • clearEvents()

• plugins add functionality to the Editor -- additional tools for the toolbar, additional styles to allow, etc. The following accessors and mutators are available for manipulating plugins:

  • addPlugin($plugin)

  • addPlugins(array $plugins)

  • setPlugins(array $plugins)

  • getPlugins()

  • hasPlugin($plugin)

  • removePlugin($plugin)

  • clearPlugins()

• editActionInterval is used to group events for undo operations. By default, this value is 3 seconds. The method setEditActionInterval($interval) may be used to set the value, while getEditActionInterval() will retrieve it.

• focusOnLoad is used to determine whether this particular editor will receive focus when the page has loaded. By default, this is FALSE. The method setFocusOnLoad($flag) may be used to set the value, while getFocusOnLoad() will retrieve it.

• height specifies the height of the editor; by default, this is 300px. The method setHeight($height) may be used to set the value, while getHeight() will retrieve it.

• inheritWidth is used to determine whether the editor will use the parent container's width or simply default to 100% width. By default, this is FALSE (i.e., it will fill the width of the window). The method setInheritWidth($flag) may be used to set the value, while getInheritWidth() will retrieve it.

• minHeight indicates the minimum height of the editor; by default, this is 1em. The method setMinHeight($height) may be used to set the value, while getMinHeight() will retrieve it.

• styleSheets indicate what additional CSS stylesheets should be used to affect the display of the Editor. By default, none are registered, and it inherits the page styles. The following accessors and mutators are available for manipulating editor stylesheets:

  • addStyleSheet($styleSheet)

  • addStyleSheets(array $styleSheets)

  • setStyleSheets(array $styleSheets)

  • getStyleSheets()

  • hasStyleSheet($styleSheet)

  • removeStyleSheet($styleSheet)

  • clearStyleSheets()

Note: Editor Dijit uses div by default
The Editor dijit uses an HTML DIV by default. The dijit._editor.RichText documentation indicates that having it built on an HTML TEXTAREA can potentially have security implications.
That said, there may be times when you want an Editor widget that can gracefully degrade to a TEXTAREA. In such situations, you can do so by setting the degrade property to TRUE:

1. // At instantiation:
2. $editor = new Zend_Dojo_Form_Element_Editor('foo', array(
3.     'degrade' => true,
4. ));
5.  
6. // Construction via the form:
7. $form->addElement('editor', 'content', array(
8.     'degrade' => true,
9. ));
10.  
11. // Or after instantiation:
12. $editor->degrade = true;

HorizontalSlider provides a slider UI widget for selecting a numeric value in a range. Internally, it sets the value of a hidden element which is submitted by the form.

HorizontalSlider derives from the abstract Slider dijit element. Additionally, it has a variety of methods for setting and configuring slider rules and rule labels.

• setTopDecorationDijit($dijit) and setBottomDecorationDijit($dijit): set the name of the dijit to use for either the top or bottom of the slider. This should not include the "dijit.form." prefix, but rather only the final name -- one of "HorizontalRule" or "HorizontalRuleLabels".

• setTopDecorationContainer($container) and setBottomDecorationContainer($container): specify the name to use for the container element of the rules; e.g. 'topRule', 'topContainer', etc.

• setTopDecorationLabels(array $labels) and setBottomDecorationLabels(array $labels): set the labels to use for one of the RuleLabels dijit types. These should be an indexed array; specify a single empty space to skip a given label position (such as the beginning or end).

• setTopDecorationParams(array $params) and setBottomDecorationParams(array $params): dijit parameters to use when configuring the given Rule or RuleLabels dijit.

• setTopDecorationAttribs(array $attribs) and setBottomDecorationAttribs(array $attribs): HTML attributes to specify for the given Rule or RuleLabels HTML element container.

• getTopDecoration() and getBottomDecoration(): retrieve all metadata for a given Rule or RuleLabels definition, as provided by the above mutators.

A number spinner is a text element for entering numeric values; it also includes elements for incrementing and decrementing the value by a set amount.

The following methods are available:

• setDefaultTimeout($timeout) and getDefaultTimeout(): set and retrieve the default timeout, in milliseconds, between when the button is held pressed and the value is changed.

• setTimeoutChangeRate($rate) and getTimeoutChangeRate(): set and retrieve the rate, in milliseconds, at which changes will be made when a button is held pressed.

• setLargeDelta($delta) and getLargeDelta(): set and retrieve the amount by which the numeric value should change when a button is held pressed.

• setSmallDelta($delta) and getSmallDelta(): set and retrieve the delta by which the number should change when a button is pressed once.

• setIntermediateChanges($flag) and getIntermediateChanges(): set and retrieve the flag indicating whether or not each value change should be shown when a button is held pressed.

• setRangeMessage($message) and getRangeMessage(): set and retrieve the message indicating the range of values available.

• setMin($value) and getMin(): set and retrieve the minimum value possible.

• setMax($value) and getMax(): set and retrieve the maximum value possible.

A number text box is a text element for entering numeric values; unlike NumberSpinner, numbers are entered manually. Validations and constraints can be provided to ensure the number stays in a particular range or format.

Internally, NumberTextBox derives from ValidationTextBox and TextBox; all methods available to those classes are available. In addition, the following methods can be used to set individual constraints:

• setLocale($locale) and getLocale(): specify and retrieve a specific or alternate locale to use with this dijit.

• setPattern($pattern) and getPattern(): set and retrieve a » number pattern format to use to format the number.

• setType($type) and getType(): set and retrieve the numeric format type to use (should be one of 'decimal', 'percent', or 'currency').

• setPlaces($places) and getPlaces(): set and retrieve the number of decimal places to support.

• setStrict($flag) and getStrict(): set and retrieve the value of the strict flag, which indicates how much leniency is allowed in relation to whitespace and non-numeric characters.

PasswordTextBox is simply a ValidationTextBox that is tied to a password input; its sole purpose is to allow for a dijit-themed text entry for passwords that also provides client-side validation.

Internally, PasswordTextBox derives from ValidationTextBox and TextBox; all methods available to those classes are available.

RadioButton wraps standard radio input elements to provide a consistent look and feel with other dojo dijits.

RadioButton extends from DijitMulti, which allows you to specify select options via the setMultiOptions() and setMultiOption() methods.

By default, this element registers an InArray validator which validates against the array keys of registered options. You can disable this behavior by either calling setRegisterInArrayValidator(false), or by passing a FALSE value to the registerInArrayValidator configuration key.

SimpleTextarea acts primarily like a standard HTML textarea. However, it does not support either the rows or cols settings. Instead, the textarea width should be specified using standard CSS measurements. Unlike Textarea, it will not grow automatically

Slider is an abstract element from which HorizontalSlider and VerticalSlider both derive. It exposes a number of common methods for configuring your sliders, including:

• setClickSelect($flag) and getClickSelect(): set and retrieve the flag indicating whether or not clicking the slider changes the value.

• setIntermediateChanges($flag) and getIntermediateChanges(): set and retrieve the flag indicating whether or not the dijit will send a notification on each slider change event.

• setShowButtons($flag) and getShowButtons(): set and retrieve the flag indicating whether or not buttons on either end will be displayed; if so, the user can click on these to change the value of the slider.

• setDiscreteValues($value) and getDiscreteValues(): set and retrieve the number of discrete values represented by the slider.

• setMaximum($value) and getMaximum(): set the maximum value of the slider.

• setMinimum($value) and getMinimum(): set the minimum value of the slider.

• setPageIncrement($value) and getPageIncrement(): set the amount by which the slider will change on keyboard events.

Example usage is provided with each concrete extending class.

While there is no Dijit named SubmitButton, we include one here to provide a button dijit capable of submitting a form without requiring any additional javascript bindings. It works exactly like the Button dijit.

TextBox is included primarily to provide a text input with consistent look-and-feel to the other dijits. However, it also includes some minor filtering and validation capabilities, represented in the following methods:

• setLowercase($flag) and getLowercase(): set and retrieve the flag indicating whether or not input should be cast to lowercase.

• setPropercase($flag) and getPropercase(): set and retrieve the flag indicating whether or not the input should be cast to Proper Case.

• setUppercase($flag) and getUppercase(): set and retrieve the flag indicating whether or not the input should be cast to UPPERCASE.

• setTrim($flag) and getTrim(): set and retrieve the flag indicating whether or not leading or trailing whitespace should be stripped.

• setMaxLength($length) and getMaxLength(): set and retrieve the maximum length of input.

Textarea acts primarily like a standard HTML textarea. However, it does not support either the rows or cols settings. Instead, the textarea width should be specified using standard CSS measurements; rows should be omitted entirely. The textarea will then grow vertically as text is added to it.

TimeTextBox is a text input that provides a drop-down for selecting a time. The drop-down may be configured to show a certain window of time, with specified increments.

Internally, TimeTextBox derives from DateTextBox, ValidationTextBox and TextBox; all methods available to those classes are available. In addition, the following methods can be used to set individual constraints:

• setTimePattern($pattern) and getTimePattern(): set and retrieve the » unicode time format pattern for formatting the time.

• setClickableIncrement($format) and getClickableIncrement(): set the » ISO_8601 string representing the amount by which every clickable element in the time picker increases.

• setVisibleIncrement($format) and getVisibleIncrement(): set the increment visible in the time chooser; must follow ISO_8601 formats.

• setVisibleRange($format) and getVisibleRange(): set and retrieve the range of time visible in the time chooser at any given moment; must follow ISO_8601 formats.

ValidationTextBox provides the ability to add validations and constraints to a text input. Internally, it derives from TextBox, and adds the following accessors and mutators for manipulating dijit parameters:

• setInvalidMessage($message) and getInvalidMessage(): set and retrieve the tooltip message to display when the value does not validate.

• setPromptMessage($message) and getPromptMessage(): set and retrieve the tooltip message to display for element usage.

• setRegExp($regexp) and getRegExp(): set and retrieve the regular expression to use for validating the element. The regular expression does not need boundaries (unlike PHP's preg* family of functions).

• setConstraint($key, $value) and getConstraint($key): set and retrieve additional constraints to use when validating the element; used primarily with subclasses. Constraints are stored in the 'constraints' key of the dijit parameters.

• setConstraints(array $constraints) and getConstraints(): set and retrieve individual constraints to use when validating the element; used primarily with subclasses.

• hasConstraint($key): test whether a given constraint exists.

• removeConstraint($key) and clearConstraints(): remove an individual or all constraints for the element.

VerticalSlider is the sibling of HorizontalSlider, and operates in every way like that element. The only real difference is that the 'top*' and 'bottom*' methods are replaced by 'left*' and 'right*', and instead of using HorizontalRule and HorizontalRuleLabels, VerticalRule and VerticalRuleLabels should be used.