Zend Framework: ZendX_JQuery UI Widgets View and Form Helpers Component Proposal

Table of Contents

1. Overview

The jQuery UI extension adds several view helpers and form elements, aswell
as a jQuery Form Extension that combines these elements that use the functionality
of the jQuery UI Widget Library.

2. References

• ZendX JQuery Helper
• jQuery UI Library
• Demo showing jQuery UI Widgets + View Helpers integration

3. Component Requirements, Constraints, and Acceptance Criteria

• MUST utilize the jQuery helper
• SHOULD allow to specify all possible options of jQuery UI widgets
• SHOULD offer both form and view helpers for usage
• SHOULD match Dojo naming/functionality scheme as near as possible

4. Dependencies on Other Framework Components

• ZendX_JQuery_View_Helper_JQuery
• Zend_Form
• Zend_View_Helper_HtmlElement

5. Theory of Operation

The jQuery UI Widget Library is a jQuery extension that offers a (currently)
small range of widgets for UI development, Accordion, DatePicker, Dialog,
Slider and Tabs. The development pace is very fast, and the next version
that includes new widgets (for example Autocomplete) is due to be released in the next
weeks. As development of jQuery UI goes on additional helpers and form
elements will be added.

This extension offers View helpers for all those widgets and integrates them
into the form building process. It uses the jQuery Helper to stack required javascript
code onto the jQuery onLoad stack. It can optionally use the Helpers
method to include the jQuery UI library from the Google CDN to simplify
the usage of the helpers.

The DatePicker Helper will be combined with Zend Translate and Zend Locale
to offer translated date naming strings and default date display format.

Accordion and Tabs will become Decorators to group form parts together.

Slider will be an additional input field works with a hidden field to
transport the chosen slider data.

Dialog will allow to render content in a Dialog box, which includes adding
forms to a dialog box, by default dialog opens on load. But it should also
be possible to combine it with events that are triggerd by css selectors.

Autocomplete will extend an input text field to offer auto complete functionality.

6. Milestones / Tasks

• Milestone 1: Finish First Proposal
• Milestone 2: Community Review
• Milestone 3: Unit Tests that cover Use-Cases
• Milestone 4: Implementation
• Milestone 5: Full Unit-Test Coverage
• Milestone 6: Documentation

7. Class Index

• ZendX_JQuery_View_Helper_Accordion
• ZendX_JQuery_View_Helper_Autocomplete
• ZendX_JQuery_View_Helper_DatePicker
• ZendX_JQuery_View_Helper_Dialog
• ZendX_JQuery_View_Helper_Slider
• ZendX_JQuery_View_Helper_Tabs
• ZendX_JQuery_Form
• ZendX_JQuery_Form_Element_Autocomplete
• ZendX_JQuery_Form_Element_DatePicker
• ZendX_JQuery_Form_Element_Slider
• ZendX_JQuery_Form_Decorator_Accordion
• ZendX_JQuery_Form_Decorator_Tabs
• ZendX_JQuery_Form_Decorator_Dialog

8. Use Cases

I have a demo up and running of all current UI widgets, showing the PHP
code to initialize them: View Helpers Demo

Comments  (Hide Comments)

I'm not sure how you envision the autoComplete view helper to work, but right now I don't see how you can specify a default value. Considering that the auto complete widget essentially is a combo box, which is a more flexible version of the select box (even though technically it's implemented as text input box), and given the flexibility of the autocomplete widget (per http://docs.jquery.com/UI/Autocomplete/autocomplete#options) I think it would make sense to stick to the formSelect view helper syntax when it comes to specifying parameters.

public function autoComplete($name, $value = null, $attribs = null, $options = null);

Your UC-05 would look like this:

<?php $data = array('New York', 'Sydney', 'Berlin', 'London', 'Peking'); ?>
<?php echo $this->autoComplete('accity1', '', null, array('data' => $data )); ?>

<?php echo $this->autoComplete('accity2', '', null, array('url' => '/from/url')); ?>

It might also be a good idea to automagically encode the "extraParams" option values if it's an array, but leave as-is if it's a string.

That way it is possible to specify something like this:

<?php echo $this->autoComplete('accity', 'New York', array('style' => 'background-color: #ffffe6;'), array('url' => '/cities/search', 'extraParams' => array('country' => 'US', 'ac' => true))) ?>

I'd expect that to build an auto complete widget named "accity", with a default value of "New York", a yellowish background color, fed by a remote resource with the two extra parameters. So if I typed "Los" into the box, it should fire off a request to "/cities/search?q=Los&country=US&ac=true".

Thanks!

Posted by Marcus Welz at Aug 18, 2008 09:08

Hello Marcus,

thanks for the suggestions. While trying to setup some first versions of the components I realized that the autoComplete helper had to be done the way you specified. The current function header
for the autocomplete function is now: autoComplete($id, $value, $ajaxOptions, $htmlAttribs);

So you would specifiy $ajaxOptions['url'] or $ajaxOptions['data'] to setup the autoComplete
datasource.

You can see this in the (new) UC-05 or the online demo: http://www.beberlei.de/jquery/demo/

Posted by Benjamin Eberlei at Aug 22, 2008 10:45

I dig the demo and how it generates a clean snippet of Javascript! Very cool!

For consistency, I recommend keeping the parameters the same as the Zend_View_Helper_FormSelect helper. That way, switching from a FormSelect to a JQuery-based autocompletion form element is simply calling a different view helper with regards to the order of passing $options and $attribs.

The current convention is also that your first parameter should be $name, rather than $id. They can be the same, but that is not necessarily the case.

For instance, you could have multiple autocomplete widgets that have same name, say, "recipient[]", but different id attributes ("recipient1", "recipient2", etc). I'd expect to be able to achieve that with a call such as $this->autoComplete('recipient[]', $defaultvalue, array('id' => 'recipient1'), array('url' => '/users/search'));

Logically, I think, a JQuery Autocomplete widget breaks down into a text box and the JQuery-based autocompletion "add-on". That said, you could simply extend Zend_View_Helper_FormText, and add in the JQuery functionality.

class ZendX_JQuery_View_Helper_AutoComplete extends Zend_View_Helper_FormText { public function autoComplete($name, $value = null, $attribs = null, $options = null) { /* * Create the text box */ $xhtml = parent::formText($name, $value, $attribs); /* * Add the Autocomplete functionality */ // [JQuery Code here] return $xhtml; } }

Posted by Marcus Welz at Aug 25, 2008 11:47

If you take it a step further, you could decouple things a bit more. By encapsulating all of the JQuery UI specific functionality in a JQueryUI view helper, you're allowing developers more flexibility, and the autoComplete() view helper becomes more of a convenience helper.

The actual Javascript call to hook autocompletion into a form element is

$('form_element_id').autocomplete(options);

(Per [http://docs.jquery.com/UI/Autocomplete/autocomplete#options documentation]). For that you just need the element id, and the options. That goes back to the original API that you had before the revision.

Not sure on the capitalization at the moment, Jqueryui, JqueryUi. JQueryUI seems most natural. I'll use that. Someone please correct me.

class ZendX_JQuery_View_Helper_JQueryUI extends Zend_View_Helper_Abstract { /** * * @return ZendX_JQuery_View_Helper_JQueryUI */ public function JQueryUI() { return $this; } public function autocomplete($id, $options) { /* * Replace these cheap includes with something more sophisticated * This just demonstrates the dependency on the libs */ $this->view->headScript()->appendFile('/includes/jquery-latest.min.js'); $this->view->headScript()->appendFile('/includes/jqueryui-latest.min.js'); // Treat $options here, encode as necessary // Render the javascript for autocomplete. Again, just for demonstration $this->view->appendScript("\$('{$id}').autocomplete(" . Zend_Json::encode($options) .');'); return ''; } }

With that in mind, you'd get an autocomplete view helper with something like this:

class ZendX_JQuery_View_Helper_AutoComplete extends Zend_View_Helper_FormText { public function autoComplete($name, $value = null, $attribs = null, $options = null) { /* * Create the text box */ $xhtml = parent::formText($name, $value, $attribs); $id = $name; if (is_array($attribs) and isset($attribs['id'])) $id = $attribs['id']; /* * Add the autocompletion functionality */ $xhtml .= $this->view->JQueryUI()->autocomplete($id, $options); return $xhtml; } }

The advantage is that if someone wants to use autocompletion with their own view helper, or directly in their view to modify an element they've previously created through other means, they're not left out in the cold:

<input type="text" name="q" id="search" value="Enter search term" /> <?php echo $this->JQueryUI()->autocomplete('search', array('url' => '/some/url')); ?>

Even though ZendX_JQuery_View_Helper_JQueryUI::autocomplete() doesn't return any output, i'd still echo the return value since there was some discussion going on regarding letting the jquery view helper return inline javascript through a configuration option.

Anyway, just a thought.

Thanks!

Posted by Marcus Welz at Aug 25, 2008 12:04

View the rest of this thread. Most recent comment: Sep 04, 2008
3 more comments by: Benjamin Eberlei, Marcus Welz

Zend Comments We approve this proposal for immediate development in the extras/incubator, with the following feedback: Use the method name "addPane()" in both Accordion and Tabs for consistency within the offering as well as consistency with conventions set in Zend_Dojo Add a Pane view helper and form decorator to use with Accordion and Tabs for creating the panes used with them. This will allow forms to be decorated with Accordion, and sub forms with Pane. Add capturing ability to Accordion, Tabs, and Pane. As noted privately, keep the method parameter order as used with the Zend_Dojo view helpers Excellent proposal!

Posted by Matthew Weier O'Phinney at Sep 04, 2008 14:10

I'd like to see the ability to adjust the HTML Markup on the accordionContainer somehow. ie:
either through the settings or through methods.

There's the _elementHtmlTemplate which I think could be set via a method, or have the ability to
set the accordion group tag, accordion header tag, and the accordion content tag.

Just an idea there..

Posted by Jay M. Keith at Sep 26, 2008 14:41

I have difficulties finding the new location of updated documentation of this extension.

For example, this signature has apparently changed:
<?= $this->datePicker("date1", "2008/17/08", array(), array("class" => "beautify")); ?>

Should now be called as:
<?= $this->datePicker("date1", array('value' => "2008/17/08", "class" => "beautify", 'label' => 'myDate'));

This may not be the appropriate place to note this kind of things, a link to recently updated documentation would be very much appreciated.

Posted by Bart McLeod at Oct 26, 2008 12:59