Zend Framework provides the following Dojo-specific view helpers:
dojo(): setup the Dojo environment for your page, including dojo configuration values, custom module paths, module require statements, theme stylesheets, CDN usage, and more.
Example 17.6. Using Dojo View Helpers
To use Dojo view helpers, you will need to tell your view object
where to find them. You can do this by calling
addHelperPath()
:
$view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');
Alternately, you can use Zend_Dojo
's
enableView()
method to do the work for you:
Zend_Dojo::enableView($view);
The dojo()
view helper is intended to simplify setting up
the Dojo environment, including the following responsibilities:
Specifying either a CDN or a local path to a Dojo install.
Specifying paths to custom Dojo modules.
Specifying dojo.require statements.
Specifying dijit stylesheet themes to use.
Specifying dojo.addOnLoad() events.
The dojo()
view helper implementation is an example of a
placeholder implementation. The data set in it persists between view
objects and may be directly echoed from your layout script.
Example 17.7. dojo() View Helper Usage Example
For this example, let's assume the developer will be using Dojo from a local path, will require several dijits, and will be utilizing the Tundra dijit theme.
On many pages, the developer may not utilize Dojo at all. So, we will first focus on a view script where Dojo is needed and then on the layout script, where we will setup some of the Dojo environment and then render it.
First, we need to tell our view object to use the Dojo view helper paths. This can be done in your bootstrap or an early-running plugin; simply grab your view object and execute the following:
$view->addHelperPath('Zend/Dojo/View/Helper/', 'Zend_Dojo_View_Helper');
Next, the view script. In this case, we're going to specify that we will be using a FilteringSelect -- which will consume a custom store based on QueryReadStore, which we'll call 'PairedStore' and store in our 'custom' module.
<?php // setup data store for FilteringSelect ?> <div dojoType="custom.PairedStore" jsId="stateStore" url="/data/autocomplete/type/state/format/ajax" requestMethod="get"></div> <?php // Input element: ?> State: <input id="state" dojoType="dijit.form.FilteringSelect" store="stateStore" pageSize="5" /> <?php // setup required dojo elements: $this->dojo()->enable() ->setDjConfigOption('parseOnLoad', true) ->registerModulePath('custom', '../custom/') ->requireModule('dijit.form.FilteringSelect') ->requireModule('custom.PairedStore'); ?>
In our layout script, we'll then check to see if Dojo is enabled, and, if so, we'll do some more general configuration and assemble it:
<?php echo $this->doctype() ?> <html> <head> <?php echo $this->headTitle() ?> <?php echo $this->headMeta() ?> <?php echo $this->headLink() ?> <?php echo $this->headStyle() ?> <?php if ($this->dojo()->isEnabled()){ $this->dojo()->setLocalPath('/js/dojo/dojo.js') ->addStyleSheetModule('dijit.themes.tundra'); echo $this->dojo(); } ?> <?php echo $this->headScript() ?> </head> <body class="tundra"> <?php echo $this->layout()->content ?> <?php echo $this->inlineScript() ?> </body> </html>
At this point, you only need to ensure that your files are in the correct locations and that you've created the end point action for your FilteringSelect!
Dojo allows both declarative and programmatic usage of many of its features. Declarative usage uses standard HTML elements with non-standard attributes that are parsed when the page is loaded. While this is a powerful and simple syntax to utilize, for many developers this can cause issues with page validation.
Programmatic usage allows the developer to decorate existing elements by pulling them by ID or CSS selectors and passing them to the appropriate object constructors in Dojo. Because no non-standard HTML attributes are used, pages continue to validate.
In practice, both use cases allow for graceful degradation when
javascript is disabled or the various Dojo script resources are
unreachable. To promote standards and document validation,
Zend Framework uses programmatic usage by default; the various view
helpers will generate javascript and push it to the
dojo()
view helper for inclusion when rendered.
Developers using this technique may also wish to explore the option of writing their own programmatic decoration of the page. One benefit would be the ability to specify handlers for dijit events.
To allow this, as well as the ability to use declarative syntax, there are a number of static methods available to set this behavior globally.
Example 17.8. Specifying Declarative and Programmatic Dojo Usage
To specify declarative usage, simply call the static
setUseDeclarative()
method:
Zend_Dojo_View_Helper_Dojo::setUseDeclarative();
If you decide instead to use programmatic usage, call the static
setUseProgrammatic()
method:
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic();
Finally, if you want to create your own programmatic rules, you should specify programmatic usage, but pass in the value '-1'; in this situation, no javascript for decorating any dijits used will be created.
Zend_Dojo_View_Helper_Dojo::setUseProgrammatic(-1);
Dojo allows the creation of themes for its dijits (widgets). You may select one by passing in a module path:
$view->dojo()->addStylesheetModule('dijit.themes.tundra');
The module path is discovered by using the character '.' as a directory separator and using the last value in the list as the name of the CSS file in that theme directory to use; in the example above, Dojo will look for the theme in 'dijit/themes/tundra/tundra.css'.
When using a theme, it is important to remember to pass the theme class to, at the least, a container surrounding any dijits you are using; the most common use case is to pass it in the body:
<body class="tundra">
By default, when you use a dojo.require statement, dojo will make a request back to the server to grab the appropriate javascript file. If you have many dijits in place, this results in many requests to the server -- which is not optimal.
Dojo's answer to this is to provide the ability to create custom builds. Builds do several things:
Groups required files into layers; a layer lumps all required files into a single JS file. (Hence the name of this section.)
"Interns" non-javascript files used by dijits (typically, template files). These are also grouped in the same JS file as the layer.
Passes the file through ShrinkSafe, which strips whitespace and comments, as well as shortens variable names.
Some files can not be layered, but the build process will create a special release directory with the layer file and all other files. This allows you to have a slimmed-down distribution customized for your site or application needs.
To use a layer, the dojo()
view helper has a
addLayer()
method for adding paths to required layers:
$view->dojo()->addLayer('/js/foo/foo.js');
For more information on creating custom builds, please refer to the Dojo build documentation.
The dojo()
view helper always returns an instance of
the dojo placeholder container. That container object has the
following methods available:
setView(Zend_View_Interface $view)
: set
a view instance in the container.
enable()
: explicitly enable Dojo
integration.
disable()
: disable Dojo
integration.
isEnabled()
: determine whether or not
Dojo integration is enabled.
requireModule($module)
: setup a
dojo.require
statement.
getModules()
: determine what modules
have been required.
registerModulePath($module, $path)
:
register a custom Dojo module path.
getModulePaths()
: get list of
registered module paths.
addLayer($path)
: add a layer (custom
build) path to use.
getLayers()
: get a list of all
registered layer paths (custom builds).
removeLayer($path)
: remove the layer
that matches $path
from the list of registered
layers (custom builds).
setCdnBase($url)
: set the base URL for
a CDN; typically, one of the
Zend_Dojo::CDN_BASE_AOL
or
Zend_Dojo::CDN_BASE_GOOGLE
, but it only needs
to be the URL string prior to the version number.
getCdnBase()
: retrieve the base CDN url
to utilize.
setCdnVersion($version = null)
: set
which version of Dojo to utilize from the CDN.
getCdnVersion()
: retrieve what
version of Dojo from the CDN will be used.
setCdnDojoPath($path)
: set the relative
path to the dojo.js or dojo.xd.js file on a CDN; typically,
one of the Zend_Dojo::CDN_DOJO_PATH_AOL
or
Zend_Dojo::CDN_DOJO_PATH_GOOGLE
, but it only
needs to be the path string following the version
number.
getCdnDojoPath()
: retrieve the last
path segment of the CDN url pointing to the dojo.js
file.
useCdn()
: tell the container to
utilize the CDN; implicitly enables integration.
setLocalPath($path)
: tell the container
the path to a local Dojo install (should be a path relative
to the server, and contain the dojo.js file itself);
implicitly enables integration.
getLocalPath()
: determine what local
path to Dojo is being used.
useLocalPath()
: is the integration
utilizing a Dojo local path?
setDjConfig(array $config)
: set
dojo/dijit configuration values (expects assoc
array).
setDjConfigOption($option, $value)
: set
a single dojo/dijit configuration value.
getDjConfig()
: get all dojo/dijit
configuration values.
getDjConfigOption($option, $default =
null)
: get a single dojo/dijit configuration
value.
addStylesheetModule($module)
: add a
stylesheet based on a module theme.
getStylesheetModules()
: get stylesheets
registered as module themes.
addStylesheet($path)
: add a local
stylesheet for use with Dojo.
getStylesheets()
: get local Dojo
stylesheets.
addOnLoad($spec, $function = null)
: add
a lambda for dojo.onLoad to call. If one argument is passed,
it is assumed to be either a function name or a javascript
closure. If two arguments are passed, the first is assumed
to be the name of an object instance variable and the second
either a method name in that object or a closure to utilize
with that object.
prependOnLoad($spec, $function = null)
:
exactly like addOnLoad()
, excepts prepends to
beginning of onLoad stack.
getOnLoadActions()
: retrieve all
dojo.onLoad actions registered with the container. This will
be an array of arrays.
onLoadCaptureStart($obj = null)
:
capture data to be used as a lambda for dojo.onLoad(). If
$obj is provided, the captured JS code will be considered a
closure to use with that Javascript object.
onLoadCaptureEnd($obj = null)
: finish
capturing data for use with dojo.onLoad().
javascriptCaptureStart()
:
capture arbitrary javascript to be included with Dojo JS
(onLoad, require, etc. statements).
javascriptCaptureEnd()
: finish
capturing javascript.
__toString()
: cast the container to a
string; renders all HTML style and script elements.
From the Dojo manual: "Dijit is a widget system layered on top of dojo." Dijit includes a variety of layout and form widgets designed to provide accessibility features, localization, and standardized (and themeable) look-and-feel.
Zend Framework ships a variety of view helpers that allow you to render and utilize dijits within your view scripts. There are three basic types:
Layout Containers: these are designed to be used within your view scripts or consumed by form decorators for forms, sub forms, and display groups. They wrap the various classes offerred in dijit.layout. Each dijit layout view helper expects the following arguments:
$id
: the container name or DOM ID.
$content
: the content to wrap in the
layout container.
$params
(optional): dijit-specific
parameters. Basically, any non-HTML attribute that can
be used to configure the dijit layout container.
$attribs
(optional): any additional HTML
attributes that should be used to render the container
div. If the key 'id' is passed in this array, it will
be used for the form element DOM id, and
$id
will be used for its name.
If you pass no arguments to a dijit layout view helper, the helper itself will be returned. This allows you to capture content, which is often an easier way to pass content to the layout container. Examples of this functionality will be shown later in this section.
Form Dijit: the dijit.form.Form dijit, while not completely necessary for use with dijit form elements, will ensure that if an attempt is made to submit a form that does not validate against client-side validations, submission will be halted and validation error messages raised. The form dijit view helper expects the following arguments:
$id
: the container name or DOM ID.
$attribs
(optional): any additional HTML
attributes that should be used to render the container
div.
$content
(optional): the content to wrap
in the form. If none is passed, an empty string will be
used.
The argument order varies from the other dijits in order to
keep compatibility with the standard form()
view
helper.
Form Elements: these are designed to be
consumed with Zend_Form
, but can be used
standalone within view scripts as well. Each dijit element view
helper expects the following arguments:
$id
: the element name or DOM ID.
$value
(optional): the current value of
the element.
$params
(optional): dijit-specific
parameters. Basically, any non-HTML attribute that can
be used to configure a dijit.
$attribs
(optional): any additional HTML
attributes that should be used to render the dijit. If
the key 'id' is passed in this array, it will be used
for the form element DOM id, and $id
will
be used for its name.
Some elements require more arguments; these will be noted with the individual element helper descriptions.
In order to utilize these view helpers, you need to register the path to the dojo view helpers with your view object.
Example 17.9. Registering the Dojo View Helper Prefix Path
$view->addHelperPath('Zend/Dojo/View/Helper', 'Zend_Dojo_View_Helper');
The dijit.layout family of elements are for creating custom, predictable layouts for your site. For any questions on general usage, read more about them in the Dojo manual.
All dijit layout elements have the
signature string ($id = null, $content = '', array $params =
array(), array $attribs = array())
. In all caess, if you
pass no arguments, the helper object itself will be returned. This
gives you access to the captureStart()
and
captureEnd()
methods, which allow you to capture
content instead of passing it to the layout container.
AccordionContainer: dijit.layout.AccordionContainer. Stack all panes together vertically; clicking on a pane titlebar will expand and display that particular pane.
<?php echo $view->accordionContainer( 'foo', $content, array( 'duration' => 200, ), array( 'style' => 'width: 200px; height: 300px;', ), ); ?>
AccordionPane: dijit.layout.AccordionPane. For use within AccordionContainer.
<?php echo $view->accordionPane( 'foo', $content, array( 'title' => 'Pane Title', ), array( 'style' => 'background-color: lightgray;', ), ); ?>
BorderContainer: dijit.layout.BorderContainer. Achieve layouts with optionally resizable panes such as you might see in a traditional application.
<?php echo $view->borderContainer( 'foo', $content, array( 'design' => 'headline', ), array( 'style' => 'width: 100%; height: 100%', ), ); ?>
ContentPane: dijit.layout.ContentPane. Use inside any container except AccordionContainer.
<?php echo $view->contentPane( 'foo', $content, array( 'title' => 'Pane Title', 'region' => 'left', ), array( 'style' => 'width: 120px; background-color: lightgray;', ), ); ?>
SplitContainer: dijit.layout.SplitContainer. Allows resizable content panes; deprecated in Dojo in favor of BorderContainer.
<?php echo $view->splitContainer( 'foo', $content, array( 'orientation' => 'horizontal', 'sizerWidth' => 7, 'activeSizing' => true, ), array( 'style' => 'width: 400px; height: 500px;', ), ); ?>
StackContainer: dijit.layout.StackContainer. All panes within a StackContainer are placed in a stack; build buttons or functionality to reveal one at a time.
<?php echo $view->stackContainer( 'foo', $content, array(), array( 'style' => 'width: 400px; height: 500px; border: 1px;', ), ); ?>
TabContainer: dijit.layout.TabContainer. All panes within a TabContainer are placed in a stack, with tabs positioned on one side for switching between them.
<?php echo $view->tabContainer( 'foo', $content, array(), array( 'style' => 'width: 400px; height: 500px; border: 1px;', ), ); ?>
The following capture methods are available for all layout containers:
captureStart($id, array $params = array(), array $attribs =
array())
: begin capturing content to include in a container.
$params
refers to the dijit params to use with
the container, while $attribs
refer to any
general HTML attributes to use.
Containers may be nested when capturing, so long as no ids are duplicated.
captureEnd($id)
:
finish capturing content to include in a container.
$id
should refer to an id previously used with
a captureStart()
call. Returns a string
representing the container and its contents, just as if
you'd simply passed content to the helper itself.
Example 17.10. BorderContainer layout dijit example
BorderContainers, particularly when coupled with the ability to capture content, are especially useful for achieving complex layout effects.
$view->borderContainer()->captureStart('masterLayout', array('design' => 'headline')); echo $view->contentPane( 'menuPane', 'This is the menu pane', array('region' => 'top'), array('style' => 'background-color: darkblue;') ); echo $view->contentPane( 'navPane', 'This is the navigation pane', array('region' => 'left'), array('style' => 'width: 200px; background-color: lightblue;') ); echo $view->contentPane( 'mainPane', 'This is the main content pane area', array('region' => 'center'), array('style' => 'background-color: white;') ); echo $view->contentPane( 'statusPane', 'Status area', array('region' => 'bottom'), array('style' => 'background-color: lightgray;') ); echo $view->borderContainer()->captureEnd('masterLayout');
Dojo's form validation and input dijits are in the dijit.form tree. For more information on general usage of these elements, as well as accepted parameters, please visit the dijit.form documentation.
The following dijit form elements are available in Zend Framework.
Except where noted, all have the signature string ($id,
$value = '', array $params = array(), array $attribs =
array())
.
Button: dijit.form.Button. Display a form button.
<?php echo $view->button( 'foo', 'Show Me!', array('iconClass' => 'myButtons'), ); ?>
CheckBox:
dijit.form.CheckBox. Display a checkbox. Accepts an
optional fifth argument, the array
$checkedOptions
, which may contain either:
an indexed array with two values, a checked value and unchecked value, in that order; or
an associative array with the keys 'checkedValue' and 'unCheckedValue'.
If $checkedOptions
is not provided, 1 and 0
are assumed.
<?php echo $view->checkBox( 'foo', 'bar', array(), array(), array('checkedValue' => 'foo', 'unCheckedValue' => 'bar') ); ?>
ComboBox:
dijit.layout.ComboBox. ComboBoxes are a hybrid between a
select and a text box with autocompletion. The key
difference is that you may type an option that is not in
the list of available options, and it will still consider
it valid input. It accepts an optional fifth argument, an
associative array $options
; if provided,
ComboBox will be rendered as a select
. Note
also that the label values of the
$options
array will be returned in the form --
not the values themselves.
Alternately, you may pass information regarding a dojo.data
datastore to use with the element. If provided, the
ComboBox will be rendered as a text input
, and
will pull its options via that datastore.
To specify a datastore, provide one of the following
$params
key combinations:
The key 'store', with an array value; the array should contain the keys:
store: the name of the javascript variable representing the datastore (this could be the name you would like for it to use).
type: the datastore type to use; e.g., 'dojo.data.ItemFileReadStore'.
params (optional): an associative array of key/value pairs to use to configure the datastore. The 'url' param is a typical example.
The keys:
store: a string indicating the datastore name to use.
storeType: a string indicating the datastore dojo.data type to use (e.g., 'dojo.data.ItemFileReadStore').
storeParams: an associative array of key/value pairs with which to configure the datastore.
// As a select element: echo $view->comboBox( 'foo', 'bar', array( 'autocomplete' => false, ), array(), array( 'foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz', ) ); // As a dojo.data-enabled element: echo $view->comboBox( 'foo', 'bar', array( 'autocomplete' => false, 'store' => 'stateStore', 'storeType' => 'dojo.data.ItemFileReadStore', 'storeParams' => array('url' => '/js/states.json'), ), );
CurrencyTextBox: dijit.form.CurrencyTextBox. Inherits from ValidationTextBox, and provides client-side validation of currency. It expects that the dijit parameter 'currency' will be provided with an appropriate 3-character currency code. You may also specify any dijit parameters valid for ValidationTextBox and TextBox.
echo $view->currencyTextBox( 'foo', '$25.00', array('currency' => 'USD'), array('maxlength' => 20) );
![]() |
Issues with Builds |
---|---|
There are currently known issues with using CurrencyTextBox with build layers. A known work-around is to ensure that your document's Content-Type http-equiv meta tag sets the character set to utf-8, which you can do by calling: $view->headMeta()->appendHttpEquiv('Content-Type', 'text/html; charset=utf-8');
This will mean, of course, that you will need to ensure
that the |
DateTextBox: dijit.form.DateTextBox. Inherits from ValidationTextBox, and provides both client-side validation of dates, as well as a dropdown calendar from which to select a date. You may specify any dijit parameters available to ValidationTextBox or TextBox.
echo $view->dateTextBox( 'foo', '2008-07-11', array('required' => true) );
Editor: dijit.Editor. Provides a
WYSIWYG editor via which users may create or edit content.
dijit.Editor
is a pluggable, extensible editor
with a variety of parameters you can utilize for customization; see the
dijit.Editor documentation for more details.
echo $view->editor('foo');
FilteringSelect: dijit.form.FilteringSelect. Similar to ComboBox, this is a select/text hybrid that can either render a provided list of options or those fetched via a dojo.data datastore. Unlike ComboBox, however, FilteringSelect does not allow typing in an option not in its list. Additionally, it operates like a standard select in that the option values, not the labels, are returned when the form is submitted.
Please see the information above on ComboBox for examples and available options for defining datastores.
HorizontalSlider and VerticalSlider: dijit.form.HorizontalSlider and dijit.form.VerticalSlider. Sliders allow are UI widgets for selecting numbers in a given range; these are horizontal and vertical variants.
At their most basic, they require the dijit parameters 'minimum', 'maximum', and 'discreteValues'. These define the range of values. Other common options are:
'intermediateChanges' can be set to indicate whether or not to fire onChange events while the handle is being dragged.
'clickSelect' can be set to allow clicking a location on the slider to set the value.
'pageIncrement' can specify the value by which to increase/decrease when pageUp and pageDown are used.
'showButtons' can be set to allow displaying buttons on either end of the slider for manipulating the value.
The Zend Framework implementation creates a hidden element to store the value of the slider.
You may optionally desire to show a rule or labels for the slider. To do so, you will assign one or more of the dijit params 'topDecoration' and/or 'bottomDecoration' (HorizontalSlider) or 'leftDecoration' and/or 'rightDecoration' (VerticalSlider). Each of these expects the following options:
container: name of the container.
labels (optional): an array of labels to utilize. Use empty strings on either end to provide labels for inner values only. Required when specifying one of the 'Labels' dijit variants.
dijit (optional): one of HorizontalRule, HorizontalRuleLabels, VerticalRule, or VerticalRuleLabels, Defaults to one of the Rule dijits.
params (optional): dijit params for configuring the Rule dijit in use. Parameters specific to these dijits include:
container (optional): array of parameters and attributes for the rule container.
labels (optional): array of parameters and attributes for the labels list container.
attribs (optional): HTML
attributes to use with the rules/labels. This should
follow the params
option format and be an
associative array with the keys 'container' and
'labels'.
echo $view->horizontalSlider( 'foo', 1, array( 'minimum' => -10, 'maximum' => 10, 'discreteValues' => 11, 'intermediateChanges' => true, 'showButtons' => true, 'topDecoration' => array( 'container' => 'topContainer' 'dijit' => 'HorizontalRuleLabels', 'labels' => array( ' ', '20%', '40%', '60%', '80%', ' ', ), 'params' => array( 'container' => array( 'style' => 'height:1.2em; font-size=75%;color:gray;', ), 'labels' => array( 'style' => 'height:1em; font-size=75%;color:gray;', ), ), ), 'bottomDecoration' => array( 'container' => 'bottomContainer' 'labels' => array( '0%', '50%', '100%', ), 'params' => array( 'container' => array( 'style' => 'height:1.2em; font-size=75%;color:gray;', ), 'labels' => array( 'style' => 'height:1em; font-size=75%;color:gray;', ), ), ), ) );
NumberSpinner: dijit.form.NumberSpinner. Text box for numeric entry, with buttons for incrementing and decrementing.
Expects either an associative array for the dijit parameter 'constraints', or simply the keys 'min', 'max', and 'places' (these would be the expected entries of the constraints parameter as well). 'places' can be used to indicate how much the number spinner will increment and decrement.
echo $view->numberSpinner( 'foo', 5, array( 'min' => -10, 'max' => 10, 'places' => 2, ), array( 'maxlenth' => 3, ) );
NumberTextBox: dijit.form.NumberTextBox. NumberTextBox provides the ability to format and display number entries in a localized fashion, as well as validate numerical entries, optionally against given constraints.
echo $view->numberTextBox( 'foo', 5, array( 'places' => 4, 'type' => 'percent', ), array( 'maxlength' => 20, ) );
PasswordTextBox: dijit.form.ValidationTextBox tied to a password input. PasswordTextBox provides the ability to create password input that adheres to the current dijit theme, as well as allow for client-side validation.
echo $view->passwordTextBox( 'foo', '', array( 'required' => true, ), array( 'maxlength' => 20, ) );
RadioButton: dijit.form.RadioButton. A set of options from which only one may be selected. This behaves in every way like a regular radio, but has a look-and-feel consistent with other dijits.
RadioButton accepts an optional fifth argument,
$options
, an associative array of value/label
pairs used as the radio options. You may also pass these as
the $attribs
key options
.
echo $view->radioButton( 'foo', 'bar', array(), array(), array( 'foo' => 'Foo', 'bar' => 'Bar', 'baz' => 'Baz', ) );
SimpleTextarea: dijit.form.SimpleTextarea.
These act like normal textareas, but are styled using the
current dijit theme. You do not need to specify either the
rows or columns attributes; use ems
or
percentages for the width and height, instead.
echo $view->simpleTextarea( 'foo', 'Start writing here...', array(), array('style' => 'width: 90%; height: 5ems;') );
SubmitButton: a dijit.form.Button tied to a submit input element. See the Button view helper for more details; the key difference is that this button can submit a form.
Textarea: dijit.form.Textarea. These act like normal textareas, except that instead of having a set number of rows, they expand as the user types. The width should be specified via a style setting.
echo $view->textarea( 'foo', 'Start writing here...', array(), array('style' => 'width: 300px;') );
TextBox: dijit.form.TextBox. This element is primarily present to provide a common look-and-feel between various dijit elements, and to provide base functionality for the other TextBox-derived classes (ValidationTextBox, NumberTextBox, CurrencyTextBox, DateTextBox, and TimeTextBox).
Common dijit parameter flags include 'lowercase' (cast to lowercase), 'uppercase' (cast to UPPERCASE), 'propercase' (cast to Proper Case), and trim (trim leading and trailing whitespace); all accept boolean values. Additionally, you may specifiy the parameters 'size' and 'maxLength'.
echo $view->textBox( 'foo', 'some text', array( 'trim' => true, 'propercase' => true, 'maxLength' => 20, ), array( 'size' => 20, ) );
TimeTextBox: dijit.form.TimeTextBox. Also in the TextBox family, TimeTextBox provides a scrollable drop down selection of times from which a user may select. Dijit parameters allow you to specify the time increments available in the select as well as the visible range of times available.
echo $view->timeTextBox( 'foo', '', array( 'am.pm' => true, 'visibleIncrement' => 'T00:05:00', // 5-minute increments 'visibleRange' => 'T02:00:00', // show 2 hours of increments ), array( 'size' => 20, ) );
ValidationTextBox: dijit.form.ValidateTextBox. Provide client-side validations for a text element. Inherits from TextBox.
Common dijit parameters include:
invalidMessage: a message to display when an invalid entry is detected.
promptMessage: a tooltip help message to use.
regExp: a regular expression to use to validate the text. Regular expression does not require boundary markers.
required: whether or not the element is required. If so, and the element is embedded in a dijit.form.Form, it will be flagged as invalid and prevent submission.
echo $view->validationTextBox( 'foo', '', array( 'required' => true, 'regExp' => '[\w]+', 'invalidMessage' => 'No spaces or non-word characters allowed', 'promptMessage' => 'Single word consisting of alphanumeric ' . 'characters and underscores only', ), array( 'maxlength' => 20, ) );
If you delve into Dojo much at all, you'll find yourself writing
custom dijits, or using experimental dijits from Dojox. While Zend
Framework cannot support every dijit directly, it does provide some
rudimentary support for arbitrary dijit types via the
CustomDijit
view helper.
The CustomDijit
view helper's API is exactly that of
any other dijit, with one major difference: the third "params"
argument must contain the attribute "dojotype".
The value of this attribute should be the Dijit class you plan to
use.
CustomDijit
extends the base
DijitContainer
view helper, which also allows it to
capture content (using the
captureStart()
/captureEnd()
pair of
methods). captureStart()
also expects that you pass the
"dojoType" attribute to its "params" argument.
Example 17.11. Using CustomDijit to render a dojox.layout.ContentPane
dojox.layout.ContentPane
is a next-generation
iteration of dijit.layout.ContentPane
, and provides
a superset of that class's capabilities. Until it's
functionality stabilizes, it will continue to live in Dojox.
However, if you want to use it in Zend Framework today, you can,
using the CustomDijit
view helper.
At its most basic, you can do the following:
<?php echo $this->customDijit( 'foo', $content, array( 'dojoType' => 'dojox.layout.ContentPane', 'title' => 'Custom pane', 'region' => 'center' ) ); ?>
If you wanted to capture content instead, simply use the
captureStart()
method, and pass the "dojoType" to
the "params" argument:
<?php $this->customDijit()->captureStart( 'foo', array( 'dojoType' => 'dojox.layout.ContentPane', 'title' => 'Custom pane', 'region' => 'center' ) ); ?> This is the content of the pane <?php echo $this->customDijit()->captureEnd('foo'); ?>
You can also extend CustomDijit
easily to create
support for your own custom dijits. As an example, if you
extended dijit.layout.ContentPane
to create your
own foo.ContentPane
class, you could create the
following helper to support it:
class My_View_Helper_FooContentPane extends Zend_Dojo_View_Helper_CustomDijit { protected $_defaultDojoType = 'foo.ContentPane'; public function fooContentPane( $id = null, $value = null, array $params = array(), array $attribs = array() ) { return $this->customDijit($id, $value, $params, $attribs); } }
As long as your custom dijit follows the same basic API as
official dijits, using or extending CustomDijit
should work correctly.