View Source

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{composition-setup}{composition-setup}]]></ac:plain-text-body></ac:macro>
<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[{zone-template-instance:ZFPROP:Proposal Zone Template}

{zone-data:component-name}
Dojo Zend_Form Widgets
{zone-data}

{zone-data:proposer-list}
[~matthew]
{zone-data}

{zone-data:liaison}
[~ralph]
{zone-data}

{zone-data:revision}
1.0 - 20 June 2008: Initial Draft.
{zone-data}

{zone-data:overview}
Dojo offers a number of form-related widgets via its dijit.form widgets (dijit == widget in Dojo parlance). Additionally, there are a number of layout widgets via dijit.layout that are well-suited to form presentation. This proposal aims to identify a number of these widgets to include as specialized form elements and decorators for use with the Zend_Form component.
{zone-data}

{zone-data:references}
* [Dojo form widgets|http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/form-validation-specialized-input]
* [Dojo layout widgets|http://dojotoolkit.org/book/dojo-book-0-9/part-2-dijit/layout]
* [Zend_Form|http://framework.zend.com/manual/en/zend.form.html]
{zone-data}

{zone-data:requirements}
* MUST live within the Zend_Dojo component
* MUST implement programmatic javascript decoration of elements
** MAY allow utilizing dojoType and other attribute declarations
* SHOULD allow specifying dojo-specific options via explicit mutators
* Form elements and decorators MUST utilize [Dojo view helper|Zend_View_Helper_Dojo] to setup appropriate dojo.require statements and other dojo-specific environment requirements.
* SHOULD provide both decorators AND view helpers for layout components
* MAY provide both view helpers for dijit elements
{zone-data}

{zone-data:dependencies}
* [Dojo view helper|Zend_View_Helper_Dojo]
* Zend_Exception
* Zend_Form
{zone-data}

{zone-data:operation}
Developers wishing to use Dojo form elements and layouts would point their form object to the Dojo elements:
{code:php}
$form->addPrefixPath('Zend_Dojo_Form', 'Zend/Dojo/Form/')
->addElementPrefixPath('Zend_Dojo_Form', 'Zend/Dojo/Form/')
->addDisplayGroupPrefixPath('Zend_Dojo_Form', 'Zend/Dojo/Form/');
{code}
Once the paths are in place, they would simply reference the appropriate form elements and decorators by name.
{zone-data}

{zone-data:milestones}
* Milestone 1: \[DONE\] Prepare this proposal
* Milestone 2: Prepare test suite and API
* Milestone 3: Complete initial implementation
* Milestone 4: Write documentation
{zone-data}

{zone-data:class-list}
* Elements
** Zend_Dojo_Form_Element_CheckBox
** Zend_Dojo_Form_Element_ComboBox
** Zend_Dojo_Form_Element_CurrencyTextBox
** Zend_Dojo_Form_Element_DateTextBox
** Zend_Dojo_Form_Element_FilteringSelect
** Zend_Dojo_Form_Element_HorizontalSlider
** Zend_Dojo_Form_Element_NumberSpinner
** Zend_Dojo_Form_Element_NumberTextBox
** Zend_Dojo_Form_Element_RadioButton
** Zend_Dojo_Form_Element_Textarea
** Zend_Dojo_Form_Element_Textbox
** Zend_Dojo_Form_Element_TimeTextBox
** Zend_Dojo_Form_Element_ToggleButton
** Zend_Dojo_Form_Element_ValidationTextbox
** Zend_Dojo_Form_Element_VerticalSlider
* Layout-related decorators
** Zend_Dojo_Form_Decorator_AccordionContainer
** Zend_Dojo_Form_Decorator_BorderContainer
** Zend_Dojo_Form_Decorator_ContentPane
** Zend_Dojo_Form_Decorator_Form
** Zend_Dojo_Form_Decorator_StackContainer
** Zend_Dojo_Form_Decorator_TabContainer
* View helpers
** Zend_Dojo_View_Helper_AccordionContainer
** Zend_Dojo_View_Helper_BorderContainer
** Zend_Dojo_View_Helper_ContentPane
** Zend_Dojo_View_Helper_Form
** Zend_Dojo_View_Helper_HorizontalSlider
** Zend_Dojo_View_Helper_StackContainer
** Zend_Dojo_View_Helper_TabContainer
** Zend_Dojo_View_Helper_VerticalSlider
{zone-data}

{zone-data:use-cases}
{deck:id=Use Cases 01}
{card:label=UC-01}
h3. Telling Zend_Form to use the Dojo widgets
{code:php}
$form->addPrefixPath('Zend_Dojo_Form', 'Zend/Dojo/Form/')
->addElementPrefixPath('Zend_Dojo_Form', 'Zend/Dojo/Form/')
->addDisplayGroupPrefixPath('Zend_Dojo_Form', 'Zend/Dojo/Form/');
{code}
{card}

{card:label=UC-02}
h3. Using a ValidationTextBox widget in your form
{code:php}
$form->addElement('validationTextBox', 'username', array(
'lowercase' => 'true',
'maxlength' => 20,
'regExp' => '^[a-z][a-z0-9]{3,}$',
'required' => 'true',
'invalidMessage' => 'Please enter a string between 3 and 20 characters with only alphanumeric characters',
'filters' => array(
'StringTrim',
'StringToLower',
),
'validators' => array(
'NotEmpty',
array('StringLength', true, array(3, 20)),
array('Regex', true, array('/^[a-z][a-z0-9]+$/i')),
),
));
{code}
{card}

{card:label=UC-03}
h3. Using dijit layout elements with a form
{code:php}
// Tell the form to act as a tab container
$form->setDecorators(array(
'FormElements',
'TabContainer',
'Form',
));

// Tell a display group that it is a ContentPane for the parent container
$displayGroup->setDecorators(array(
'FormElements',
array('ContentPane', array(
'preload' => true,
'refreshOnShow' => true,
)),
));
{code}
{card}
{deck}
{zone-data}

{zone-data:skeletons}
No class skeletons will be provided in the proposal. All will merely be extensions of the base Zend_Form classes, with a few added mutators and accessors.
{zone-data}

{zone-template-instance}]]></ac:plain-text-body></ac:macro>