Caution: The documentation you are viewing is
for an older version of Zend Framework.
You can find the documentation of the current version at:
https://docs.zendframework.com/
Dojo Form Elements and Decorators - Zend_Dojo
Building on the dijit view helpers, the Zend_Dojo_Form family of classes provides the ability to utilize Dijits natively within your forms.
There are three options for utilizing the Dojo form elements with your forms:
Use Zend_Dojo::enableForm(). This will add plugin paths for decorators and elements to all attached form items, recursively. Additionally, it will dojo-enable the view object. Note, however, that any sub forms you attach after this call will also need to be passed through Zend_Dojo::enableForm().
Use the Dojo-specific form and subform implementations, Zend_Dojo_Form and Zend_Dojo_Form_SubForm respectively. These can be used as drop-in replacements for Zend_Form and Zend_Form_SubForm, contain all the appropriate decorator and element paths, set a Dojo-specific default DisplayGroup class, and dojo-enable the view.
Last, and most tedious, you can set the appropriate decorator and element paths yourself, set the default DisplayGroup class, and dojo-enable the view. Since Zend_Dojo::enableForm() does this already, there's little reason to go this route.
Example #1 Enabling Dojo in your existing forms
"But wait," you say; "I'm already extending Zend_Form with my own custom form class! How can I Dojo-enable it?'"
First, and easiest, simply change from extending Zend_Form to extending Zend_Dojo_Form, and update any places where you instantiate Zend_Form_SubForm to instantiate Zend_Dojo_Form_SubForm.
A second approach is to call Zend_Dojo::enableForm() within your custom form's init() method; when the form definition is complete, loop through all SubForms to dojo-enable them:
Usage of the dijit-specific form decorators and elements is just like using any other form decorator or element.
Most form elements can use the DijitElement decorator, which will grab the dijit parameters from the elements, and pass these and other metadata to the view helper specified by the element. For decorating forms, sub forms, and display groups, however, there are a set of decorators corresponding to the various layout dijits.
All dijit decorators look for the dijitParams property of the given element being decorated, and push them as the $params array to the dijit view helper being used; these are then separated from any other properties so that no duplication of information occurs.
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.
Example #2 DijitElement Decorator Usage
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
Example #3 DijitContainer Decorator Usage
Each form dijit for which a view helper is provided has a corresponding Zend_Form element. All of them have the following methods available for manipulating dijit parameters:
setDijitParam($key, $value): set a single dijit parameter. If the dijit parameter already exists, it will be overwritten.
setDijitParams(array $params): set several dijit parameters at once. Any passed parameters matching those already present will overwrite.
hasDijitParam($key): If a given dijit parameter is defined and present, return TRUE, otherwise return FALSE.
getDijitParam($key): retrieve the given dijit parameter. If not available, a NULL value is returned.
getDijitParams(): retrieve all dijit parameters.
removeDijitParam($key): remove the given dijit parameter.
clearDijitParams(): clear all currently defined dijit parameters.
Dijit parameters are stored in the dijitParams public property. Thus, you can dijit-enable an existing form element simply by setting this property on the element; you simply will not have the above accessors to facilitate manipulating the parameters.
Additionally, dijit-specific elements implement a different list of decorators, corresponding to the following:
In effect, the DijitElement decorator is used in place of the standard ViewHelper decorator.
Finally, the base Dijit element ensures that the Dojo view helper path is set on the view.
A variant on DijitElement, DijitMulti, provides the functionality of the Multi abstract form element, allowing the developer to specify 'multiOptions' -- typically select options or radio options.
The following dijit elements are shipped in the standard Zend Framework distribution.
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.
Example #4 Example Button dijit element usage
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.
Example #5 Example CheckBox dijit element usage
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.
Example #6 ComboBox dijit element usage as select input
Example #7 ComboBox dijit element usage with datastore
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.
Example #8 Example CurrencyTextBox dijit element usage
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".
Example #9 Example DateTextBox dijit element usage
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()
Example #10 Example Editor dijit element usage
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:
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.
Example #11 Example HorizontalSlider dijit element usage
The following will create a horizontal slider selection with integer values ranging from -10 to 10. The top will have labels at the 20%, 40%, 60%, and 80% marks. The bottom will have rules at 0, 50%, and 100%. Each time the value is changed, the hidden element storing the value will be updated.
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.
Example #12 Example NumberSpinner dijit element usage
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.
Example #14 Example PasswordTextBox dijit element usage
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
Example #16 Example SimpleTextarea dijit element usage
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.
Example #17 Example SubmitButton dijit element usage
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.
Example #18 Example TextBox dijit element usage
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.
Example #19 Example Textarea dijit element usage
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.
Example #20 Example TimeTextBox dijit element usage
The following will create a TimeTextBox that displays 2 hours at a time, with increments of 10 minutes.
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.
Example #21 Example ValidationTextBox dijit element usage
The following will create a ValidationTextBox that requires a single string consisting solely of word characters (i.e., no spaces, most punctuation is invalid).
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.
Example #22 Example VerticalSlider dijit element usage
The following will create a vertical slider selection with integer values ranging from -10 to 10. The left will have labels at the 20%, 40%, 60%, and 80% marks. The right will have rules at 0, 50%, and 100%. Each time the value is changed, the hidden element storing the value will be updated.
Example #23 Using Zend_Dojo_Form
The easiest way to utilize Dojo with Zend_Form is to utilize Zend_Dojo_Form, either through direct usage or by extending it. This example shows extending Zend_Dojo_Form, and shows usage of all dijit elements. It creates four sub forms, and decorates the form to utilize a TabContainer, showing each sub form in its own tab.
Example #24 Modifying an existing form to utilize Dojo
Existing forms can be modified to utilize Dojo as well, by use of the Zend_Dojo::enableForm() static method.
This first example shows decorating an existing form instance:
Alternately, you can make a slight tweak to your form initialization:
Of course, if you can do that... you could and should simply alter the class to inherit from Zend_Dojo_Form, which is a drop-in replacement of Zend_Form that's already Dojo-enabled...
