| blob | 5e2c4bf8fcd46c24d45e9458c7a7069ed56bbcbb |
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect2 id="zend.dojo.form.elements">
4 <title>Dijit-Specific Form Elements</title>
6 <para>
7 Each form dijit for which a view helper is provided has a corresponding
8 <classname>Zend_Form</classname> element. All of them have the following methods
9 available for manipulating dijit parameters:
10 </para>
12 <itemizedlist>
13 <listitem>
14 <para>
15 <methodname>setDijitParam($key, $value)</methodname>: set a single dijit
16 parameter. If the dijit parameter already exists, it will be
17 overwritten.
18 </para>
19 </listitem>
21 <listitem>
22 <para>
23 <methodname>setDijitParams(array $params)</methodname>: set several dijit
24 parameters at once. Any passed parameters matching those
25 already present will overwrite.
26 </para>
27 </listitem>
29 <listitem>
30 <para>
31 <methodname>hasDijitParam($key)</methodname>: If a given dijit parameter
32 is defined and present, return <constant>TRUE</constant>, otherwise return
33 <constant>FALSE</constant>.
34 </para>
35 </listitem>
37 <listitem>
38 <para>
39 <methodname>getDijitParam($key)</methodname>: retrieve the given dijit
40 parameter. If not available, a <constant>NULL</constant> value is returned.
41 </para>
42 </listitem>
44 <listitem>
45 <para>
46 <methodname>getDijitParams()</methodname>: retrieve all dijit parameters.
47 </para>
48 </listitem>
50 <listitem>
51 <para>
52 <methodname>removeDijitParam($key)</methodname>: remove the given dijit parameter.
53 </para>
54 </listitem>
56 <listitem>
57 <para>
58 <methodname>clearDijitParams()</methodname>: clear all currently defined
59 dijit parameters.
60 </para>
61 </listitem>
62 </itemizedlist>
64 <para>
65 Dijit parameters are stored in the <property>dijitParams</property> public
66 property. Thus, you can dijit-enable an existing form element simply by
67 setting this property on the element; you simply will not have the
68 above accessors to facilitate manipulating the parameters.
69 </para>
71 <para>
72 Additionally, dijit-specific elements implement a different list of
73 decorators, corresponding to the following:
74 </para>
76 <programlisting language="php"><![CDATA[
77 $element->addDecorator('DijitElement')
78 ->addDecorator('Errors')
79 ->addDecorator('HtmlTag', array('tag' => 'dd'))
80 ->addDecorator('Label', array('tag' => 'dt'));
81 ]]></programlisting>
83 <para>
84 In effect, the DijitElement decorator is used in place of the standard
85 ViewHelper decorator.
86 </para>
88 <para>
89 Finally, the base Dijit element ensures that the Dojo view helper path
90 is set on the view.
91 </para>
93 <para>
94 A variant on DijitElement, DijitMulti, provides the functionality of
95 the <classname>Multi</classname> abstract form element, allowing the developer to
96 specify 'multiOptions' -- typically select options or radio options.
97 </para>
99 <para>
100 The following dijit elements are shipped in the standard Zend
101 Framework distribution.
102 </para>
104 <sect3 id="zend.dojo.form.elements.button">
105 <title>Button</title>
107 <para>
108 While not deriving from <link
109 linkend="zend.form.standardElements.button">the standard Button
110 element</link>, it does implement the same functionality, and
111 can be used as a drop-in replacement for it. The following
112 functionality is exposed:
113 </para>
115 <itemizedlist>
116 <listitem>
117 <para>
118 <methodname>getLabel()</methodname> will utilize the element name as the
119 button label if no name is provided. Additionally, it will
120 translate the name if a translation adapter with a matching
121 translation message is available.
122 </para>
123 </listitem>
125 <listitem>
126 <para>
127 <methodname>isChecked()</methodname> determines if the value submitted
128 matches the label; if so, it returns <constant>TRUE</constant>. This is useful
129 for determining which button was used when a form was submitted.
130 </para>
131 </listitem>
132 </itemizedlist>
134 <para>
135 Additionally, only the decorators <classname>DijitElement</classname> and
136 <classname>DtDdWrapper</classname> are utilized for Button elements.
137 </para>
139 <example id="zend.dojo.form.elements.button.example">
140 <title>Example Button dijit element usage</title>
142 <programlisting language="php"><![CDATA[
143 $form->addElement(
144 'Button',
145 'foo',
146 array(
147 'label' => 'Button Label',
148 )
149 );
150 ]]></programlisting>
151 </example>
152 </sect3>
154 <sect3 id="zend.dojo.form.elements.checkBox">
155 <title>CheckBox</title>
157 <para>
158 While not deriving from <link
159 linkend="zend.form.standardElements.checkbox">the standard
160 Checkbox element</link>, it does implement the same
161 functionality. This means that the following methods are exposed:
162 </para>
164 <itemizedlist>
165 <listitem>
166 <para>
167 <methodname>setCheckedValue($value)</methodname>: set the value to use when
168 the element is checked.
169 </para>
170 </listitem>
172 <listitem>
173 <para>
174 <methodname>getCheckedValue()</methodname>: get the value of the item to
175 use when checked.
176 </para>
177 </listitem>
179 <listitem>
180 <para>
181 <methodname>setUncheckedValue($value)</methodname>: set the value of the
182 item to use when it is unchecked.
183 </para>
184 </listitem>
186 <listitem>
187 <para>
188 <methodname>getUncheckedValue()</methodname>: get the value of the item to
189 use when it is unchecked.
190 </para>
191 </listitem>
193 <listitem>
194 <para>
195 <methodname>setChecked($flag)</methodname>: mark the element as checked or
196 unchecked.
197 </para>
198 </listitem>
200 <listitem>
201 <para>
202 <methodname>isChecked()</methodname>: determine if the element is currently
203 checked.
204 </para>
205 </listitem>
206 </itemizedlist>
208 <example id="zend.dojo.form.elements.checkBox.example">
209 <title>Example CheckBox dijit element usage</title>
211 <programlisting language="php"><![CDATA[
212 $form->addElement(
213 'CheckBox',
214 'foo',
215 array(
216 'label' => 'A check box',
217 'checkedValue' => 'foo',
218 'uncheckedValue' => 'bar',
219 'checked' => true,
220 )
221 );
222 ]]></programlisting>
223 </example>
224 </sect3>
226 <sect3 id="zend.dojo.form.elements.comboBox">
227 <title>ComboBox and FilteringSelect</title>
229 <para>
230 As noted in the ComboBox <link
231 linkend="zend.dojo.view.dijit.form">dijit view helper
232 documentation</link>, ComboBoxes are a hybrid between select
233 and text input, allowing for autocompletion and the ability to
234 specify an alternate to the options provided. FilteringSelects are
235 the same, but do not allow arbitrary input.
236 </para>
238 <note>
239 <title>ComboBoxes return the label values</title>
241 <para>
242 ComboBoxes return the label values, and not the option values,
243 which can lead to a disconnect in expectations. For this reason,
244 ComboBoxes do not auto-register an <classname>InArray</classname>
245 validator (though FilteringSelects do).
246 </para>
247 </note>
249 <para>
250 The ComboBox and FilteringSelect form elements provide accessors and mutators for
251 examining and setting the select options as well as specifying a
252 <command>dojo.data</command> datastore (if used). They extend from DijitMulti, which
253 allows you to specify select options via the
254 <methodname>setMultiOptions()</methodname> and <methodname>setMultiOption()</methodname>
255 methods. In addition, the following methods are available:
256 </para>
258 <itemizedlist>
259 <listitem>
260 <para>
261 <methodname>getStoreInfo()</methodname>: get all datastore information
262 currently set. Returns an empty array if no data is currently set.
263 </para>
264 </listitem>
266 <listitem>
267 <para>
268 <methodname>setStoreId($identifier)</methodname>: set the store identifier
269 variable (usually referred to by the attribute 'jsId' in Dojo).
270 This should be a valid javascript variable name.
271 </para>
272 </listitem>
274 <listitem>
275 <para>
276 <methodname>getStoreId()</methodname>: retrieve the store identifier
277 variable name.
278 </para>
279 </listitem>
281 <listitem>
282 <para>
283 <methodname>setStoreType($dojoType)</methodname>: set the datastore class
284 to use; e.g., "<command>dojo.data.ItemFileReadStore</command>".
285 </para>
286 </listitem>
288 <listitem>
289 <para>
290 <methodname>getStoreType()</methodname>: get the dojo datastore class to use.
291 </para>
292 </listitem>
294 <listitem>
295 <para>
296 <methodname>setStoreParams(array $params)</methodname>: set any parameters
297 used to configure the datastore object. As an example,
298 <command>dojo.data.ItemFileReadStore</command> datastore would expect a 'url'
299 parameter pointing to a location that would return the
300 <command>dojo.data</command> object.
301 </para>
302 </listitem>
304 <listitem>
305 <para>
306 <methodname>getStoreParams()</methodname>: get any datastore parameters
307 currently set; if none, an empty array is returned.
308 </para>
309 </listitem>
311 <listitem>
312 <para>
313 <methodname>setAutocomplete($flag)</methodname>: indicate whether or not
314 the selected item will be used when the user leaves the element.
315 </para>
316 </listitem>
318 <listitem>
319 <para>
320 <methodname>getAutocomplete()</methodname>: get the value of the
321 autocomplete flag.
322 </para>
323 </listitem>
324 </itemizedlist>
326 <para>
327 By default, if no <command>dojo.data</command> store is registered with the element,
328 this element registers an <classname>InArray</classname> validator which
329 validates against the array keys of registered options. You can
330 disable this behavior by either calling
331 <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
332 <constant>FALSE</constant> value to the <property>registerInArrayValidator</property>
333 configuration key.
334 </para>
336 <example id="zend.dojo.form.elements.comboBox.selectExample">
337 <title>ComboBox dijit element usage as select input</title>
339 <programlisting language="php"><![CDATA[
340 $form->addElement(
341 'ComboBox',
342 'foo',
343 array(
344 'label' => 'ComboBox (select)',
345 'value' => 'blue',
346 'autocomplete' => false,
347 'multiOptions' => array(
348 'red' => 'Rouge',
349 'blue' => 'Bleu',
350 'white' => 'Blanc',
351 'orange' => 'Orange',
352 'black' => 'Noir',
353 'green' => 'Vert',
354 ),
355 )
356 );
357 ]]></programlisting>
358 </example>
360 <example id="zend.dojo.form.elements.comboBox.datastoreExample">
361 <title>ComboBox dijit element usage with datastore</title>
363 <programlisting language="php"><![CDATA[
364 $form->addElement(
365 'ComboBox',
366 'foo',
367 array(
368 'label' => 'ComboBox (datastore)',
369 'storeId' => 'stateStore',
370 'storeType' => 'dojo.data.ItemFileReadStore',
371 'storeParams' => array(
372 'url' => '/js/states.txt',
373 ),
374 'dijitParams' => array(
375 'searchAttr' => 'name',
376 ),
377 )
378 );
379 ]]></programlisting>
380 </example>
382 <para>
383 The above examples could also utilize <classname>FilteringSelect</classname>
384 instead of <classname>ComboBox</classname>.
385 </para>
386 </sect3>
388 <sect3 id="zend.dojo.form.elements.currencyTextBox">
389 <title>CurrencyTextBox</title>
391 <para>
392 The CurrencyTextBox is primarily for supporting currency input. The
393 currency may be localized, and can support both fractional and
394 non-fractional values.
395 </para>
397 <para>
398 Internally, CurrencyTextBox derives from <link
399 linkend="zend.dojo.form.elements.numberTextBox">NumberTextBox</link>,
400 <link
401 linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>,
402 and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
403 all methods available to those classes are available. In addition,
404 the following constraint methods can be used:
405 </para>
407 <itemizedlist>
408 <listitem>
409 <para>
410 <methodname>setCurrency($currency)</methodname>: set the currency type to
411 use; should follow the <ulink
412 url="http://en.wikipedia.org/wiki/ISO_4217">ISO-4217</ulink> specification.
413 </para>
414 </listitem>
416 <listitem>
417 <para>
418 <methodname>getCurrency()</methodname>: retrieve the current currency type.
419 </para>
420 </listitem>
422 <listitem>
423 <para>
424 <methodname>setSymbol($symbol)</methodname>: set the 3-letter <ulink
425 url="http://en.wikipedia.org/wiki/ISO_4217">ISO-4217</ulink>
426 currency symbol to use.
427 </para>
428 </listitem>
430 <listitem>
431 <para>
432 <methodname>getSymbol()</methodname>: get the current currency symbol.
433 </para>
434 </listitem>
436 <listitem>
437 <para>
438 <methodname>setFractional($flag)</methodname>: set whether or not the
439 currency should allow for fractional values.
440 </para>
441 </listitem>
443 <listitem>
444 <para>
445 <methodname>getFractional()</methodname>: retrieve the status of the
446 fractional flag.
447 </para>
448 </listitem>
449 </itemizedlist>
451 <example id="zend.dojo.form.elements.currencyTextBox.example">
452 <title>Example CurrencyTextBox dijit element usage</title>
454 <programlisting language="php"><![CDATA[
455 $form->addElement(
456 'CurrencyTextBox',
457 'foo',
458 array(
459 'label' => 'Currency:',
460 'required' => true,
461 'currency' => 'USD',
462 'invalidMessage' => 'Invalid amount. ' .
463 'Include dollar sign, commas, and cents.',
464 'fractional' => false,
465 )
466 );
467 ]]></programlisting>
468 </example>
469 </sect3>
471 <sect3 id="zend.dojo.form.elements.dateTextBox">
472 <title>DateTextBox</title>
474 <para>
475 DateTextBox provides a calendar drop-down for selecting a date, as
476 well as client-side date validation and formatting.
477 </para>
479 <para>
480 Internally, DateTextBox derives from <link
481 linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
482 and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
483 all methods available to those classes are available. In addition,
484 the following methods can be used to set individual constraints:
485 </para>
487 <itemizedlist>
488 <listitem>
489 <para>
490 <methodname>setAmPm($flag)</methodname> and <methodname>getAmPm()</methodname>:
491 Whether or not to use AM or PM strings in times.
492 </para>
493 </listitem>
495 <listitem>
496 <para>
497 <methodname>setStrict($flag)</methodname> and
498 <methodname>getStrict()</methodname>: whether or not to use strict regular
499 expression matching when validating input. If <constant>FALSE</constant>, which
500 is the default, it will be lenient about whitespace and some abbreviations.
501 </para>
502 </listitem>
504 <listitem>
505 <para>
506 <methodname>setLocale($locale)</methodname> and
507 <methodname>getLocale()</methodname>: Set and retrieve the locale to use with
508 this specific element.
509 </para>
510 </listitem>
512 <listitem>
513 <para>
514 <methodname>setDatePattern($pattern)</methodname> and
515 <methodname>getDatePattern()</methodname>: provide and retrieve the <ulink
516 url="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">unicode
517 date format pattern</ulink> for formatting the date.
518 </para>
519 </listitem>
521 <listitem>
522 <para>
523 <methodname>setFormatLength($formatLength)</methodname> and
524 <methodname>getFormatLength()</methodname>: provide and retrieve the format
525 length type to use; should be one of "long", "short", "medium" or "full".
526 </para>
527 </listitem>
529 <listitem>
530 <para>
531 <methodname>setSelector($selector)</methodname> and
532 <methodname>getSelector()</methodname>: provide and retrieve the style of
533 selector; should be either "date" or "time".
534 </para>
535 </listitem>
536 </itemizedlist>
538 <example id="zend.dojo.form.elements.dateTextBox.example">
539 <title>Example DateTextBox dijit element usage</title>
541 <programlisting language="php"><![CDATA[
542 $form->addElement(
543 'DateTextBox',
544 'foo',
545 array(
546 'label' => 'Date:',
547 'required' => true,
548 'invalidMessage' => 'Invalid date specified.',
549 'formatLength' => 'long',
550 )
551 );
552 ]]></programlisting>
553 </example>
554 </sect3>
556 <sect3 id="zend.dojo.form.elements.editor">
557 <title>Editor</title>
559 <para>
560 Editor provides a <acronym>WYSIWYG</acronym> editor that can be used to both create and
561 edit rich <acronym>HTML</acronym> content. <command>dijit.Editor</command> is pluggable
562 and may be extended with custom plugins if desired; see <ulink
563 url="http://dojotoolkit.org/reference-guide/dijit/Editor.html">the
564 dijit.Editor documentation</ulink> for more details.
565 </para>
567 <para>
568 The Editor form element provides a number of accessors and mutators
569 for manipulating various dijit parameters, as follows:
570 </para>
572 <itemizedlist>
573 <listitem>
574 <para>
575 <emphasis>captureEvents</emphasis> are events that connect
576 to the editing area itself. The following accessors and
577 mutators are available for manipulating capture events:
578 </para>
580 <itemizedlist>
581 <listitem>
582 <para><methodname>addCaptureEvent($event)</methodname></para>
583 </listitem>
585 <listitem>
586 <para><methodname>addCaptureEvents(array $events)</methodname></para>
587 </listitem>
589 <listitem>
590 <para><methodname>setCaptureEvents(array $events)</methodname></para>
591 </listitem>
593 <listitem><para><methodname>getCaptureEvents()</methodname></para></listitem>
595 <listitem>
596 <para><methodname>hasCaptureEvent($event)</methodname></para>
597 </listitem>
599 <listitem>
600 <para><methodname>removeCaptureEvent($event)</methodname></para>
601 </listitem>
603 <listitem>
604 <para><methodname>clearCaptureEvents()</methodname></para>
605 </listitem>
606 </itemizedlist>
607 </listitem>
609 <listitem>
610 <para>
611 <emphasis>events</emphasis> are standard <acronym>DOM</acronym> events, such as
612 onClick, onKeyUp, etc. The following accessors and mutators
613 are available for manipulating events:
614 </para>
616 <itemizedlist>
617 <listitem><para><methodname>addEvent($event)</methodname></para></listitem>
619 <listitem>
620 <para><methodname>addEvents(array $events)</methodname></para>
621 </listitem>
623 <listitem>
624 <para><methodname>setEvents(array $events)</methodname></para>
625 </listitem>
627 <listitem><para><methodname>getEvents()</methodname></para></listitem>
628 <listitem><para><methodname>hasEvent($event)</methodname></para></listitem>
629 <listitem><para><methodname>removeEvent($event)</methodname></para></listitem>
630 <listitem><para><methodname>clearEvents()</methodname></para></listitem>
631 </itemizedlist>
632 </listitem>
634 <listitem>
635 <para>
636 <emphasis>plugins</emphasis> add functionality to the
637 Editor -- additional tools for the toolbar, additional
638 styles to allow, etc. The following accessors and mutators
639 are available for manipulating plugins:
640 </para>
642 <itemizedlist>
643 <listitem><para><methodname>addPlugin($plugin)</methodname></para></listitem>
645 <listitem>
646 <para><methodname>addPlugins(array $plugins)</methodname></para>
647 </listitem>
649 <listitem>
650 <para><methodname>setPlugins(array $plugins)</methodname></para>
651 </listitem>
653 <listitem><para><methodname>getPlugins()</methodname></para></listitem>
654 <listitem><para><methodname>hasPlugin($plugin)</methodname></para></listitem>
655 <listitem><para><methodname>removePlugin($plugin)</methodname></para></listitem>
656 <listitem><para><methodname>clearPlugins()</methodname></para></listitem>
657 </itemizedlist>
658 </listitem>
660 <listitem>
661 <para>
662 <emphasis>editActionInterval</emphasis> is used to group
663 events for undo operations. By default, this value is 3
664 seconds. The method
665 <methodname>setEditActionInterval($interval)</methodname> may be used to
666 set the value, while <methodname>getEditActionInterval()</methodname>
667 will retrieve it.
668 </para>
669 </listitem>
671 <listitem>
672 <para>
673 <emphasis>focusOnLoad</emphasis> is used to determine
674 whether this particular editor will receive focus when the
675 page has loaded. By default, this is <constant>FALSE</constant>. The method
676 <methodname>setFocusOnLoad($flag)</methodname> may be used to
677 set the value, while <methodname>getFocusOnLoad()</methodname>
678 will retrieve it.
679 </para>
680 </listitem>
682 <listitem>
683 <para>
684 <emphasis>height</emphasis> specifies the height of the
685 editor; by default, this is 300px. The method
686 <methodname>setHeight($height)</methodname> may be used to set the
687 value, while <methodname>getHeight()</methodname> will retrieve it.
688 </para>
689 </listitem>
691 <listitem>
692 <para>
693 <emphasis>inheritWidth</emphasis> is used to determine
694 whether the editor will use the parent container's width or
695 simply default to 100% width. By default, this is <constant>FALSE</constant>
696 (i.e., it will fill the width of the window). The method
697 <methodname>setInheritWidth($flag)</methodname> may be used to set the
698 value, while <methodname>getInheritWidth()</methodname> will retrieve
699 it.
700 </para>
701 </listitem>
703 <listitem>
704 <para>
705 <emphasis>minHeight</emphasis> indicates the minimum height
706 of the editor; by default, this is 1em. The method
707 <methodname>setMinHeight($height)</methodname> may be used to set the
708 value, while <methodname>getMinHeight()</methodname> will retrieve it.
709 </para>
710 </listitem>
712 <listitem>
713 <para>
714 <emphasis>styleSheets</emphasis> indicate what additional
715 <acronym>CSS</acronym> stylesheets should be used to affect the display of the
716 Editor. By default, none are registered, and it inherits the
717 page styles. The following accessors and mutators are
718 available for manipulating editor stylesheets:
719 </para>
721 <itemizedlist>
722 <listitem>
723 <para><methodname>addStyleSheet($styleSheet)</methodname></para>
724 </listitem>
726 <listitem>
727 <para><methodname>addStyleSheets(array $styleSheets)</methodname></para>
728 </listitem>
730 <listitem>
731 <para><methodname>setStyleSheets(array $styleSheets)</methodname></para>
732 </listitem>
734 <listitem><para><methodname>getStyleSheets()</methodname></para></listitem>
736 <listitem>
737 <para><methodname>hasStyleSheet($styleSheet)</methodname></para>
738 </listitem>
740 <listitem>
741 <para><methodname>removeStyleSheet($styleSheet)</methodname></para>
742 </listitem>
744 <listitem><para><methodname>clearStyleSheets()</methodname></para></listitem>
745 </itemizedlist>
746 </listitem>
747 </itemizedlist>
749 <example id="zend.dojo.form.elements.editor.example">
750 <title>Example Editor dijit element usage</title>
752 <programlisting language="php"><![CDATA[
753 $form->addElement('editor', 'content', array(
754 'plugins' => array('undo', '|', 'bold', 'italic'),
755 'editActionInterval' => 2,
756 'focusOnLoad' => true,
757 'height' => '250px',
758 'inheritWidth' => true,
759 'styleSheets' => array('/js/custom/editor.css'),
760 ));
761 ]]></programlisting>
762 </example>
764 <note>
765 <title>Editor Dijit uses div by default</title>
767 <para>
768 The Editor dijit uses an <acronym>HTML</acronym> <acronym>DIV</acronym> by default.
769 The <command>dijit._editor.RichText</command> documentation indicates that
770 having it built on an <acronym>HTML</acronym> <acronym>TEXTAREA</acronym> can
771 potentially have security implications.
772 </para>
774 <para>
775 That said, there may be times when you want an Editor widget that can gracefully
776 degrade to a <acronym>TEXTAREA</acronym>. In such situations, you can do so by
777 setting the <property>degrade</property> property to <constant>TRUE</constant>:
778 </para>
780 <programlisting language="php"><![CDATA[
781 // At instantiation:
782 $editor = new Zend_Dojo_Form_Element_Editor('foo', array(
783 'degrade' => true,
784 ));
786 // Construction via the form:
787 $form->addElement('editor', 'content', array(
788 'degrade' => true,
789 ));
791 // Or after instantiation:
792 $editor->degrade = true;
793 ]]></programlisting>
794 </note>
795 </sect3>
797 <sect3 id="zend.dojo.form.elements.horizontalSlider">
798 <title>HorizontalSlider</title>
800 <para>
801 HorizontalSlider provides a slider UI widget for selecting a
802 numeric value in a range. Internally, it sets the value of a hidden
803 element which is submitted by the form.
804 </para>
806 <para>
807 HorizontalSlider derives from the <link
808 linkend="zend.dojo.form.elements.slider">abstract Slider dijit
809 element</link>. Additionally, it has a variety of methods for
810 setting and configuring slider rules and rule labels.
811 </para>
813 <itemizedlist>
814 <listitem>
815 <para>
816 <methodname>setTopDecorationDijit($dijit)</methodname> and
817 <methodname>setBottomDecorationDijit($dijit)</methodname>: set the name
818 of the dijit to use for either the top or bottom of the
819 slider. This should not include the "dijit.form." prefix,
820 but rather only the final name -- one of "HorizontalRule"
821 or "HorizontalRuleLabels".
822 </para>
823 </listitem>
825 <listitem>
826 <para>
827 <methodname>setTopDecorationContainer($container)</methodname> and
828 <methodname>setBottomDecorationContainer($container)</methodname>:
829 specify the name to use for the container element of the
830 rules; e.g. 'topRule', 'topContainer', etc.
831 </para>
832 </listitem>
834 <listitem>
835 <para>
836 <methodname>setTopDecorationLabels(array $labels)</methodname> and
837 <methodname>setBottomDecorationLabels(array $labels)</methodname>: set
838 the labels to use for one of the RuleLabels dijit types.
839 These should be an indexed array; specify a single empty
840 space to skip a given label position (such as the beginning
841 or end).
842 </para>
843 </listitem>
845 <listitem>
846 <para>
847 <methodname>setTopDecorationParams(array $params)</methodname> and
848 <methodname>setBottomDecorationParams(array $params)</methodname>:
849 dijit parameters to use when configuring the given Rule or
850 RuleLabels dijit.
851 </para>
852 </listitem>
854 <listitem>
855 <para>
856 <methodname>setTopDecorationAttribs(array $attribs)</methodname> and
857 <methodname>setBottomDecorationAttribs(array $attribs)</methodname>:
858 <acronym>HTML</acronym> attributes to specify for the given Rule or RuleLabels
859 <acronym>HTML</acronym> element container.
860 </para>
861 </listitem>
863 <listitem>
864 <para>
865 <methodname>getTopDecoration()</methodname> and
866 <methodname>getBottomDecoration()</methodname>: retrieve all metadata
867 for a given Rule or RuleLabels definition, as provided by
868 the above mutators.
869 </para>
870 </listitem>
871 </itemizedlist>
873 <example id="zend.dojo.form.elements.horizontalSlider.example">
874 <title>Example HorizontalSlider dijit element usage</title>
876 <para>
877 The following will create a horizontal slider selection with
878 integer values ranging from -10 to 10. The top will have labels
879 at the 20%, 40%, 60%, and 80% marks. The bottom will have rules
880 at 0, 50%, and 100%. Each time the value is changed, the hidden
881 element storing the value will be updated.
882 </para>
884 <programlisting language="php"><![CDATA[
885 $form->addElement(
886 'HorizontalSlider',
887 'horizontal',
888 array(
889 'label' => 'HorizontalSlider',
890 'value' => 5,
891 'minimum' => -10,
892 'maximum' => 10,
893 'discreteValues' => 11,
894 'intermediateChanges' => true,
895 'showButtons' => true,
896 'topDecorationDijit' => 'HorizontalRuleLabels',
897 'topDecorationContainer' => 'topContainer',
898 'topDecorationLabels' => array(
899 ' ',
900 '20%',
901 '40%',
902 '60%',
903 '80%',
904 ' ',
905 ),
906 'topDecorationParams' => array(
907 'container' => array(
908 'style' => 'height:1.2em; font-size=75%;color:gray;',
909 ),
910 'list' => array(
911 'style' => 'height:1em; font-size=75%;color:gray;',
912 ),
913 ),
914 'bottomDecorationDijit' => 'HorizontalRule',
915 'bottomDecorationContainer' => 'bottomContainer',
916 'bottomDecorationLabels' => array(
917 '0%',
918 '50%',
919 '100%',
920 ),
921 'bottomDecorationParams' => array(
922 'list' => array(
923 'style' => 'height:1em; font-size=75%;color:gray;',
924 ),
925 ),
926 )
927 );
928 ]]></programlisting>
929 </example>
930 </sect3>
932 <sect3 id="zend.dojo.form.elements.numberSpinner">
933 <title>NumberSpinner</title>
935 <para>
936 A number spinner is a text element for entering numeric values; it
937 also includes elements for incrementing and decrementing the value
938 by a set amount.
939 </para>
941 <para>
942 The following methods are available:
943 </para>
945 <itemizedlist>
946 <listitem>
947 <para>
948 <methodname>setDefaultTimeout($timeout)</methodname> and
949 <methodname>getDefaultTimeout()</methodname>: set and retrieve the default
950 timeout, in milliseconds, between when the button is held
951 pressed and the value is changed.
952 </para>
953 </listitem>
955 <listitem>
956 <para>
957 <methodname>setTimeoutChangeRate($rate)</methodname> and
958 <methodname>getTimeoutChangeRate()</methodname>: set and retrieve the
959 rate, in milliseconds, at which changes will be made when a
960 button is held pressed.
961 </para>
962 </listitem>
964 <listitem>
965 <para>
966 <methodname>setLargeDelta($delta)</methodname> and
967 <methodname>getLargeDelta()</methodname>: set and retrieve the amount by
968 which the numeric value should change when a button is held pressed.
969 </para>
970 </listitem>
972 <listitem>
973 <para>
974 <methodname>setSmallDelta($delta)</methodname> and
975 <methodname>getSmallDelta()</methodname>: set and retrieve the delta by
976 which the number should change when a button is pressed once.
977 </para>
978 </listitem>
980 <listitem>
981 <para>
982 <methodname>setIntermediateChanges($flag)</methodname> and
983 <methodname>getIntermediateChanges()</methodname>: set and retrieve the
984 flag indicating whether or not each value change should be
985 shown when a button is held pressed.
986 </para>
987 </listitem>
989 <listitem>
990 <para>
991 <methodname>setRangeMessage($message)</methodname> and
992 <methodname>getRangeMessage()</methodname>: set and retrieve the message
993 indicating the range of values available.
994 </para>
995 </listitem>
997 <listitem>
998 <para>
999 <methodname>setMin($value)</methodname> and <methodname>getMin()</methodname>:
1000 set and retrieve the minimum value possible.
1001 </para>
1002 </listitem>
1004 <listitem>
1005 <para>
1006 <methodname>setMax($value)</methodname> and <methodname>getMax()</methodname>:
1007 set and retrieve the maximum value possible.
1008 </para>
1009 </listitem>
1010 </itemizedlist>
1012 <example id="zend.dojo.form.elements.numberSpinner.example">
1013 <title>Example NumberSpinner dijit element usage</title>
1015 <programlisting language="php"><![CDATA[
1016 $form->addElement(
1017 'NumberSpinner',
1018 'foo',
1019 array(
1020 'value' => '7',
1021 'label' => 'NumberSpinner',
1022 'smallDelta' => 5,
1023 'largeDelta' => 25,
1024 'defaultTimeout' => 500,
1025 'timeoutChangeRate' => 100,
1026 'min' => 9,
1027 'max' => 1550,
1028 'places' => 0,
1029 'maxlength' => 20,
1030 )
1031 );
1032 ]]></programlisting>
1033 </example>
1034 </sect3>
1036 <sect3 id="zend.dojo.form.elements.numberTextBox">
1037 <title>NumberTextBox</title>
1039 <para>
1040 A number text box is a text element for entering numeric values;
1041 unlike NumberSpinner, numbers are entered manually. Validations and
1042 constraints can be provided to ensure the number stays in a
1043 particular range or format.
1044 </para>
1046 <para>
1047 Internally, NumberTextBox derives from <link
1048 linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
1049 and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
1050 all methods available to those classes are available. In addition,
1051 the following methods can be used to set individual constraints:
1052 </para>
1054 <itemizedlist>
1055 <listitem>
1056 <para>
1057 <methodname>setLocale($locale)</methodname> and
1058 <methodname>getLocale()</methodname>: specify and retrieve a specific or
1059 alternate locale to use with this dijit.
1060 </para>
1061 </listitem>
1063 <listitem>
1064 <para>
1065 <methodname>setPattern($pattern)</methodname> and
1066 <methodname>getPattern()</methodname>: set and retrieve a <ulink
1067 url="http://www.unicode.org/reports/tr35/#Number_Format_Patterns">number
1068 pattern format</ulink> to use to format the number.
1069 </para>
1070 </listitem>
1072 <listitem>
1073 <para>
1074 <methodname>setType($type)</methodname> and <methodname>getType()</methodname>:
1075 set and retrieve the numeric format type to use (should be one of
1076 'decimal', 'percent', or 'currency').
1077 </para>
1078 </listitem>
1080 <listitem>
1081 <para>
1082 <methodname>setPlaces($places)</methodname> and
1083 <methodname>getPlaces()</methodname>: set and retrieve the number of decimal
1084 places to support.
1085 </para>
1086 </listitem>
1088 <listitem>
1089 <para>
1090 <methodname>setStrict($flag)</methodname> and
1091 <methodname>getStrict()</methodname>: set and retrieve the value of the strict
1092 flag, which indicates how much leniency is allowed in relation to whitespace and
1093 non-numeric characters.
1094 </para>
1095 </listitem>
1096 </itemizedlist>
1098 <example id="zend.dojo.form.elements.numberTextBox.example">
1099 <title>Example NumberTextBox dijit element usage</title>
1101 <programlisting language="php"><![CDATA[
1102 $form->addElement(
1103 'NumberTextBox',
1104 'elevation',
1105 array(
1106 'label' => 'NumberTextBox',
1107 'required' => true,
1108 'invalidMessage' => 'Invalid elevation.',
1109 'places' => 0,
1110 'constraints' => array(
1111 'min' => -20000,
1112 'max' => 20000,
1113 ),
1114 )
1115 );
1116 ]]></programlisting>
1117 </example>
1118 </sect3>
1120 <sect3 id="zend.dojo.form.elements.passwordTextBox">
1121 <title>PasswordTextBox</title>
1123 <para>
1124 PasswordTextBox is simply a ValidationTextBox that is tied to a
1125 password input; its sole purpose is to allow for a dijit-themed text
1126 entry for passwords that also provides client-side validation.
1127 </para>
1129 <para>
1130 Internally, PasswordTextBox derives from <link
1131 linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
1132 and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
1133 all methods available to those classes are available.
1134 </para>
1136 <example id="zend.dojo.form.elements.passwordTextBox.example">
1137 <title>Example PasswordTextBox dijit element usage</title>
1139 <programlisting language="php"><![CDATA[
1140 $form->addElement(
1141 'PasswordTextBox',
1142 'password',
1143 array(
1144 'label' => 'Password',
1145 'required' => true,
1146 'trim' => true,
1147 'lowercase' => true,
1148 'regExp' => '^[a-z0-9]{6,}$',
1149 'invalidMessage' => 'Invalid password; ' .
1150 'must be at least 6 alphanumeric characters',
1151 )
1152 );
1153 ]]></programlisting>
1154 </example>
1155 </sect3>
1157 <sect3 id="zend.dojo.form.elements.radioButton">
1158 <title>RadioButton</title>
1160 <para>
1161 RadioButton wraps standard radio input elements to provide a
1162 consistent look and feel with other dojo dijits.
1163 </para>
1165 <para>
1166 RadioButton extends from DijitMulti, which
1167 allows you to specify select options via the
1168 <methodname>setMultiOptions()</methodname> and <methodname>setMultiOption()</methodname>
1169 methods.
1170 </para>
1172 <para>
1173 By default, this element registers an <classname>InArray</classname> validator
1174 which validates against the array keys of registered options. You
1175 can disable this behavior by either calling
1176 <methodname>setRegisterInArrayValidator(false)</methodname>, or by passing a
1177 <constant>FALSE</constant> value to the <property>registerInArrayValidator</property>
1178 configuration key.
1179 </para>
1181 <example id="zend.dojo.form.elements.radioButton.example">
1182 <title>Example RadioButton dijit element usage</title>
1184 <programlisting language="php"><![CDATA[
1185 $form->addElement(
1186 'RadioButton',
1187 'foo',
1188 array(
1189 'label' => 'RadioButton',
1190 'multiOptions' => array(
1191 'foo' => 'Foo',
1192 'bar' => 'Bar',
1193 'baz' => 'Baz',
1194 ),
1195 'value' => 'bar',
1196 )
1197 );
1198 ]]></programlisting>
1199 </example>
1200 </sect3>
1202 <sect3 id="zend.dojo.form.elements.simpletextarea">
1203 <title>SimpleTextarea</title>
1205 <para>
1206 SimpleTextarea acts primarily like a standard <acronym>HTML</acronym> textarea. However,
1207 it does not support either the rows or cols settings. Instead, the
1208 textarea width should be specified using standard <acronym>CSS</acronym> measurements.
1209 Unlike Textarea, it will not grow automatically
1210 </para>
1212 <example id="zend.dojo.form.elements.simpletextarea.example">
1213 <title>Example SimpleTextarea dijit element usage</title>
1215 <programlisting language="php"><![CDATA[
1216 $form->addElement(
1217 'SimpleTextarea',
1218 'simpletextarea',
1219 array(
1220 'label' => 'SimpleTextarea',
1221 'required' => true,
1222 'style' => 'width: 80em; height: 25em;',
1223 )
1224 );
1225 ]]></programlisting>
1226 </example>
1227 </sect3>
1229 <sect3 id="zend.dojo.form.elements.slider">
1230 <title>Slider abstract element</title>
1232 <para>
1233 Slider is an abstract element from which
1234 <link linkend="zend.dojo.form.elements.horizontalSlider">HorizontalSlider</link>
1235 and <link linkend="zend.dojo.form.elements.verticalSlider">VerticalSlider</link>
1236 both derive. It exposes a number of common methods for configuring
1237 your sliders, including:
1238 </para>
1240 <itemizedlist>
1241 <listitem>
1242 <para>
1243 <methodname>setClickSelect($flag)</methodname> and
1244 <methodname>getClickSelect()</methodname>: set and retrieve the flag
1245 indicating whether or not clicking the slider changes the value.
1246 </para>
1247 </listitem>
1249 <listitem>
1250 <para>
1251 <methodname>setIntermediateChanges($flag)</methodname> and
1252 <methodname>getIntermediateChanges()</methodname>: set and retrieve the
1253 flag indicating whether or not the dijit will send a
1254 notification on each slider change event.
1255 </para>
1256 </listitem>
1258 <listitem>
1259 <para>
1260 <methodname>setShowButtons($flag)</methodname> and
1261 <methodname>getShowButtons()</methodname>: set and retrieve the flag
1262 indicating whether or not buttons on either end will be
1263 displayed; if so, the user can click on these to change the
1264 value of the slider.
1265 </para>
1266 </listitem>
1268 <listitem>
1269 <para>
1270 <methodname>setDiscreteValues($value)</methodname> and
1271 <methodname>getDiscreteValues()</methodname>: set and retrieve the number
1272 of discrete values represented by the slider.
1273 </para>
1274 </listitem>
1276 <listitem>
1277 <para>
1278 <methodname>setMaximum($value)</methodname> and
1279 <methodname>getMaximum()</methodname>: set the maximum value of the slider.
1280 </para>
1281 </listitem>
1283 <listitem>
1284 <para>
1285 <methodname>setMinimum($value)</methodname> and
1286 <methodname>getMinimum()</methodname>: set the minimum value of the slider.
1287 </para>
1288 </listitem>
1290 <listitem>
1291 <para>
1292 <methodname>setPageIncrement($value)</methodname> and
1293 <methodname>getPageIncrement()</methodname>: set the amount by which the
1294 slider will change on keyboard events.
1295 </para>
1296 </listitem>
1297 </itemizedlist>
1299 <para>
1300 Example usage is provided with each concrete extending class.
1301 </para>
1302 </sect3>
1304 <sect3 id="zend.dojo.form.elements.submitButton">
1305 <title>SubmitButton</title>
1307 <para>
1308 While there is no Dijit named SubmitButton, we include one here to
1309 provide a button dijit capable of submitting a form without
1310 requiring any additional javascript bindings. It works exactly like
1311 the <link linkend="zend.dojo.form.elements.button">Button dijit</link>.
1312 </para>
1314 <example id="zend.dojo.form.elements.submitButton.example">
1315 <title>Example SubmitButton dijit element usage</title>
1317 <programlisting language="php"><![CDATA[
1318 $form->addElement(
1319 'SubmitButton',
1320 'foo',
1321 array(
1322 'required' => false,
1323 'ignore' => true,
1324 'label' => 'Submit Button!',
1325 )
1326 );
1327 ]]></programlisting>
1328 </example>
1329 </sect3>
1331 <sect3 id="zend.dojo.form.elements.textBox">
1332 <title>TextBox</title>
1334 <para>
1335 TextBox is included primarily to provide a text input with
1336 consistent look-and-feel to the other dijits. However, it also
1337 includes some minor filtering and validation capabilities,
1338 represented in the following methods:
1339 </para>
1341 <itemizedlist>
1342 <listitem>
1343 <para>
1344 <methodname>setLowercase($flag)</methodname> and
1345 <methodname>getLowercase()</methodname>: set and retrieve the flag
1346 indicating whether or not input should be cast to lowercase.
1347 </para>
1348 </listitem>
1350 <listitem>
1351 <para>
1352 <methodname>setPropercase($flag)</methodname> and
1353 <methodname>getPropercase()</methodname>: set and retrieve the flag
1354 indicating whether or not the input should be cast to Proper Case.
1355 </para>
1356 </listitem>
1358 <listitem>
1359 <para>
1360 <methodname>setUppercase($flag)</methodname> and
1361 <methodname>getUppercase()</methodname>: set and retrieve
1362 the flag indicating whether or not the input should be cast to
1363 <acronym>UPPERCASE</acronym>.
1364 </para>
1365 </listitem>
1367 <listitem>
1368 <para>
1369 <methodname>setTrim($flag)</methodname> and <methodname>getTrim()</methodname>:
1370 set and retrieve the flag indicating whether or not leading or trailing
1371 whitespace should be stripped.
1372 </para>
1373 </listitem>
1375 <listitem>
1376 <para>
1377 <methodname>setMaxLength($length)</methodname> and
1378 <methodname>getMaxLength()</methodname>: set and retrieve the maximum
1379 length of input.
1380 </para>
1381 </listitem>
1382 </itemizedlist>
1384 <example id="zend.dojo.form.elements.textBox.example">
1385 <title>Example TextBox dijit element usage</title>
1387 <programlisting language="php"><![CDATA[
1388 $form->addElement(
1389 'TextBox',
1390 'foo',
1391 array(
1392 'value' => 'some text',
1393 'label' => 'TextBox',
1394 'trim' => true,
1395 'propercase' => true,
1396 )
1397 );
1398 ]]></programlisting>
1399 </example>
1400 </sect3>
1402 <sect3 id="zend.dojo.form.elements.textarea">
1403 <title>Textarea</title>
1405 <para>
1406 Textarea acts primarily like a standard <acronym>HTML</acronym> textarea. However, it
1407 does not support either the rows or cols settings. Instead, the
1408 textarea width should be specified using standard <acronym>CSS</acronym> measurements;
1409 rows should be omitted entirely. The textarea will then grow
1410 vertically as text is added to it.
1411 </para>
1413 <example id="zend.dojo.form.elements.textarea.example">
1414 <title>Example Textarea dijit element usage</title>
1416 <programlisting language="php"><![CDATA[
1417 $form->addElement(
1418 'Textarea',
1419 'textarea',
1420 array(
1421 'label' => 'Textarea',
1422 'required' => true,
1423 'style' => 'width: 200px;',
1424 )
1425 );
1426 ]]></programlisting>
1427 </example>
1428 </sect3>
1430 <sect3 id="zend.dojo.form.elements.timeTextBox">
1431 <title>TimeTextBox</title>
1433 <para>
1434 TimeTextBox is a text input that provides a drop-down for selecting
1435 a time. The drop-down may be configured to show a certain window of
1436 time, with specified increments.
1437 </para>
1439 <para>
1440 Internally, TimeTextBox derives from <link
1441 linkend="zend.dojo.form.elements.dateTextBox">DateTextBox</link>,
1442 <link
1443 linkend="zend.dojo.form.elements.validationTextBox">ValidationTextBox</link>
1444 and <link linkend="zend.dojo.form.elements.textBox">TextBox</link>;
1445 all methods available to those classes are available. In addition,
1446 the following methods can be used to set individual constraints:
1447 </para>
1449 <itemizedlist>
1450 <listitem>
1451 <para>
1452 <methodname>setTimePattern($pattern)</methodname> and
1453 <methodname>getTimePattern()</methodname>: set and retrieve the <ulink
1454 url="http://www.unicode.org/reports/tr35/#Date_Format_Patterns">unicode
1455 time format pattern</ulink> for formatting the time.
1456 </para>
1457 </listitem>
1459 <listitem>
1460 <para>
1461 <methodname>setClickableIncrement($format)</methodname> and
1462 <methodname>getClickableIncrement()</methodname>: set the <ulink
1463 url="http://en.wikipedia.org/wiki/ISO_8601">ISO_8601</ulink>
1464 string representing the amount by which every clickable element
1465 in the time picker increases.
1466 </para>
1467 </listitem>
1469 <listitem>
1470 <para>
1471 <methodname>setVisibleIncrement($format)</methodname> and
1472 <methodname>getVisibleIncrement()</methodname>: set the increment visible
1473 in the time chooser; must follow <constant>ISO_8601</constant> formats.
1474 </para>
1475 </listitem>
1477 <listitem>
1478 <para>
1479 <methodname>setVisibleRange($format)</methodname> and
1480 <methodname>getVisibleRange()</methodname>: set and retrieve the range of
1481 time visible in the time chooser at any given moment; must
1482 follow <constant>ISO_8601</constant> formats.
1483 </para>
1484 </listitem>
1485 </itemizedlist>
1487 <example id="zend.dojo.form.elements.timeTextBox.example">
1488 <title>Example TimeTextBox dijit element usage</title>
1490 <para>
1491 The following will create a TimeTextBox that displays 2 hours
1492 at a time, with increments of 10 minutes.
1493 </para>
1495 <programlisting language="php"><![CDATA[
1496 $form->addElement(
1497 'TimeTextBox',
1498 'foo',
1499 array(
1500 'label' => 'TimeTextBox',
1501 'required' => true,
1502 'visibleRange' => 'T04:00:00',
1503 'visibleIncrement' => 'T00:10:00',
1504 'clickableIncrement' => 'T00:10:00',
1505 )
1506 );
1507 ]]></programlisting>
1508 </example>
1509 </sect3>
1511 <sect3 id="zend.dojo.form.elements.validationTextBox">
1512 <title>ValidationTextBox</title>
1514 <para>
1515 ValidationTextBox provides the ability to add validations and constraints to a text
1516 input. Internally, it derives from <link
1517 linkend="zend.dojo.form.elements.textBox">TextBox</link>, and adds the following
1518 accessors and mutators for manipulating dijit parameters:
1519 </para>
1521 <itemizedlist>
1522 <listitem>
1523 <para>
1524 <methodname>setInvalidMessage($message)</methodname> and
1525 <methodname>getInvalidMessage()</methodname>: set and retrieve the tooltip
1526 message to display when the value does not validate.
1527 </para>
1528 </listitem>
1530 <listitem>
1531 <para>
1532 <methodname>setPromptMessage($message)</methodname> and
1533 <methodname>getPromptMessage()</methodname>: set and retrieve the tooltip
1534 message to display for element usage.
1535 </para>
1536 </listitem>
1538 <listitem>
1539 <para>
1540 <methodname>setRegExp($regexp)</methodname> and
1541 <methodname>getRegExp()</methodname>: set and retrieve the regular expression to
1542 use for validating the element. The regular expression does not need boundaries
1543 (unlike <acronym>PHP</acronym>'s preg* family of functions).
1544 </para>
1545 </listitem>
1547 <listitem>
1548 <para>
1549 <methodname>setConstraint($key, $value)</methodname> and
1550 <methodname>getConstraint($key)</methodname>: set and retrieve additional
1551 constraints to use when validating the element; used primarily
1552 with subclasses. Constraints are stored in the 'constraints'
1553 key of the dijit parameters.
1554 </para>
1555 </listitem>
1557 <listitem>
1558 <para>
1559 <methodname>setConstraints(array $constraints)</methodname> and
1560 <methodname>getConstraints()</methodname>: set and retrieve individual
1561 constraints to use when validating the element; used primarily with subclasses.
1562 </para>
1563 </listitem>
1565 <listitem>
1566 <para>
1567 <methodname>hasConstraint($key)</methodname>: test whether a given constraint
1568 exists.
1569 </para>
1570 </listitem>
1572 <listitem>
1573 <para>
1574 <methodname>removeConstraint($key)</methodname> and
1575 <methodname>clearConstraints()</methodname>: remove an individual or all
1576 constraints for the element.
1577 </para>
1578 </listitem>
1579 </itemizedlist>
1581 <example id="zend.dojo.form.elements.validationTextBox.example">
1582 <title>Example ValidationTextBox dijit element usage</title>
1584 <para>
1585 The following will create a ValidationTextBox that requires a
1586 single string consisting solely of word characters (i.e., no
1587 spaces, most punctuation is invalid).
1588 </para>
1590 <programlisting language="php"><![CDATA[
1591 $form->addElement(
1592 'ValidationTextBox',
1593 'foo',
1594 array(
1595 'label' => 'ValidationTextBox',
1596 'required' => true,
1597 'regExp' => '[\w]+',
1598 'invalidMessage' => 'Invalid non-space text.',
1599 )
1600 );
1601 ]]></programlisting>
1602 </example>
1603 </sect3>
1605 <sect3 id="zend.dojo.form.elements.verticalSlider">
1606 <title>VerticalSlider</title>
1608 <para>
1609 VerticalSlider is the sibling of <link
1610 linkend="zend.dojo.form.elements.horizontalSlider">HorizontalSlider</link>,
1611 and operates in every way like that element. The only real
1612 difference is that the 'top*' and 'bottom*' methods are replaced by
1613 'left*' and 'right*', and instead of using HorizontalRule and
1614 HorizontalRuleLabels, VerticalRule and VerticalRuleLabels should be
1615 used.
1616 </para>
1618 <example id="zend.dojo.form.elements.verticalSlider.example">
1619 <title>Example VerticalSlider dijit element usage</title>
1621 <para>
1622 The following will create a vertical slider selection with
1623 integer values ranging from -10 to 10. The left will have labels
1624 at the 20%, 40%, 60%, and 80% marks. The right will have rules
1625 at 0, 50%, and 100%. Each time the value is changed, the hidden
1626 element storing the value will be updated.
1627 </para>
1629 <programlisting language="php"><![CDATA[
1630 $form->addElement(
1631 'VerticalSlider',
1632 'foo',
1633 array(
1634 'label' => 'VerticalSlider',
1635 'value' => 5,
1636 'style' => 'height: 200px; width: 3em;',
1637 'minimum' => -10,
1638 'maximum' => 10,
1639 'discreteValues' => 11,
1640 'intermediateChanges' => true,
1641 'showButtons' => true,
1642 'leftDecorationDijit' => 'VerticalRuleLabels',
1643 'leftDecorationContainer' => 'leftContainer',
1644 'leftDecorationLabels' => array(
1645 ' ',
1646 '20%',
1647 '40%',
1648 '60%',
1649 '80%',
1650 ' ',
1651 ),
1652 'rightDecorationDijit' => 'VerticalRule',
1653 'rightDecorationContainer' => 'rightContainer',
1654 'rightDecorationLabels' => array(
1655 '0%',
1656 '50%',
1657 '100%',
1658 ),
1659 )
1660 );
1661 ]]></programlisting>
1662 </example>
1663 </sect3>
1664 </sect2>
1665 <!--
1666 vim:se ts=4 sw=4 et:
1667 -->