Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: ZendX_JQuery_View_Helper_JQuery Component Proposal

Proposed Component Name ZendX_JQuery_View_Helper_JQuery
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/ZendX_JQuery_View_Helper_JQuery
Proposers Benjamin Eberlei
Zend Liaison Matthew Weier O'Phinney
Revision 1.0 - 14 July 2008: Initial Draft.
1.1 - 16 August 2008: Final Review Version (wiki revision: 29)

Table of Contents

1. Overview

The jQuery helper allows to simplify the setup of an enviroment that uses jQuery as Javascript library and provides the possibilty to construct a wide range of ajax calls.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • MUST be a single view helper with multiple methods
  • MUST be able to render as string
  • MUST support direct deployment via CDN (Google Ajax Library API), using specified version
  • MUST support using local install, via path
  • SHOULD default to CDN if no path specified
  • MUST have method for requiring plugin files (js and css)
  • SHOULD be base component for further jQuery Plugins that use its infrastructure methods

The jQuery Ajax Helper should provide methods to build Ajax Requests using the jQuery Helper.

  • MUST integrate with jQuery Library to append requests to onLoad Event.
  • MUST add value to simply using jQuery Ajax Requests (Auto building most wanted callbacks)
  • SHOULD allow inlining Javascript, but MUST default to stack Javascript to onLoad

4. Dependencies on Other Framework Components

  • Zend_View_Exception
  • Zend_Json

5. Theory of Operation

Theory of Operation:
Using the jQuery Helper enables one to setup an jQuery enviroment in a ZF MVC implementation very fast, specifing helper methods to include jQuery Javascript Files and additional plugin requirements.

The jQuery Link Helper allows to construct simple ajax calls from within a view template. The following call signature is proposed:

6. Milestones / Tasks

  • Milestone 1: Finish First Proposal [DONE]
  • Milestone 2: Community Review [DONE]
  • Milestone 3: Finish First Implementation DONE (SVN: http://www.beberlei.de/dev/svn/ZendX_JQuery/)
  • Milestone 4: Complete Unit Test Coverage [DONE]
  • Milestone 5: Finish Component
  • Milestone 6: Documentation

7. Class Index

  • ZendX_JQuery
  • ZendX_JQuery_View_Helper_JQuery
  • ZendX_JQuery_View_Helper_JqLink

8. Use Cases

9. Class Skeletons

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Jul 14, 2008

    <p>On the problem of the jQuery Plugin architecture i have already written two entries on my blog:</p>

    <p><a class="external-link" href="http://www.whitewashing.de/blog/articles/47">http://www.whitewashing.de/blog/articles/47</a>
    <a class="external-link" href="http://www.whitewashing.de/blog/articles/48">http://www.whitewashing.de/blog/articles/48</a></p>

    <p>and the question is, how a ZF jQuery component could support additional components like the jQuery<br />
    UI Library, Zend_JQuery_Form that uses a jQuery plugin or a jQuery Autocomplete View Helper. All<br />
    of which would need additional downloads of JS and Stylesheets (No CDN available). They would<br />
    add lots of additional value to people who want to construct ZF MVC projects with ajax support<br />
    in a fast way with no direct concerns about the javascript overhead (But: Refactoring all the auto-build code is supported of course).</p>

    <p>Because of the complexity of jQuery requirements (when deadling with additions) I included lots of<br />
    helper methods that cope with this problem, deadling with js and css include directory, adding<br />
    js and css files. All this stuff will be built into HTML markup, when <?php echo $this->jQuery(); ?> is called. I don't use headScript() and headStyle() for the same reasons as Matthew did not in his Dojo proposal, to group all the jQuery stuff together and make it independant, allowing for specific disabling of all the jQuery output, when refactoring occured.</p>

    <p>Additionally I have also tested around a little bit already and have implementations of the DatePicker and Autocomplete components working that depend on a first jQuery View Helper implementation. They require the additional includes and stylesheets I talked about, so I won't add them to the proposal just yet.</p>

  2. Jul 14, 2008

    <p>Congrats for idea and for work on this component. jQuery is a must to for ZF since jQuery is highly used by developers...</p>

  3. Jul 15, 2008

    <p>A jQuery view helper will be a great addition to the Zend Framework since many of its user, including me, use this library. Thank you!</p>

  4. Jul 15, 2008

    <p>A few notes, based on the dojo version: please try and mimic the dojo method names as much as possible so that we can start determining what might be put into an abstract class and/or interface. For example:</p>
    <ul>
    <li>setLibraryPath() -> setLocalPath() (this one also better encapsulates the distinction between a <em>remote</em> CDN resource vs. a <em>local</em> resource)</li>
    <li>addStyleSheet() -> addStylesheet() (same goes for the get variant)</li>
    </ul>

    <p>I'd also recommend extending the new Zend_View_Helper_Abstract, which will negate the need for the setView() method. (note to self: must do this for the dojo() helper as well!)</p>

    <p>Additionally, I'll just get this out of the way now: start using the ZendX prefix. We've already determined and publically stated that any JS toolkits outside of Dojo will be in the extras library. As such, you should show a use case indicating how you would attach the view helper to the view object ($view->addHelperPath('ZendX/View/Helper/', 'ZendX_View_Helper')).</p>

    <p>Finally, do you think it likely that there would be additional jQuery components outside the view helpers at any point? If so, I'm going to recommend using a top-level namespace: ZendX_JQuery. The rationales are that it keeps all jQuery components grouped, making them easy to locate in the tree; it promotes encapsulation; and it promotes the idea of use-at-will.</p>

    <p>Nice work, and ping me if you have any questions or would like help with identifying abstraction points (for a generic JS view helper interface or abstract class).</p>

    1. Jul 15, 2008

      <p>Thanks for the feedback. I will add all the changes to the method body tonight. Also i will claim ZendX_Jquery then. (or can it be JQuery? ZF Coding Standards Puzzle me on this specific application of the CamelCase rule).</p>

      <p>Additional components are possible, ajaxForm, Autocomplete and such stuff. But at first i plan to implement this Helper and the basic jQuery Ajax Functionality and then maybe extend the functonality to include additional features.</p>

      1. Jul 15, 2008

        <p>We discussed CamelCasing yesterday internally, and I made the case that it's confusing to users when our CamelCasing rules conflict with known standard names. The one caveat is that the first letter following an underscore <em>always</em> has to be Uppercase to ensure class name lookups will work.</p>

        <p>So, short answer: JQuery as a classname segment is fine.</p>

        <p>Looking forward to seeing what other features you propose later!</p>

        1. Jul 16, 2008

          <p>Please consider the above: personally, I really like that I don't have to know or think upon the name of a component, just the rules. ZendX_Jquery would be a better choice.</p>

          1. Jul 16, 2008

            <p>The library is called jQuery, and jQuery users are used to seeing the capital Q. This is also true of services like OpenID and OAuth. It's more confusing to have a disconnect between the widely know and accepted name and how it is named internally in ZF.</p>

            1. Jul 17, 2008

              <p>I will always value a single convention over different rules based on context, but I can see Matthew's argument here as well. I do think this is something probably best left to the community. Also, the framework should have consistent naming rules for method names as well. So, for example, isXmlHttpRequest() would become isXMLHttpRequest() instead.</p>

          2. Jul 16, 2008

            <p>From the way jQuery is written I have to stick with JQuery as class names. As an application developer you propably won't come accross calling the class anyways, except in your layout view to output the collected onLoad/include statements. The jQuery helper is really just a helper to bundle all jQuery-releated helpers required output together.</p>

            <p>If sticking to ZF conventions you might even only have to implement some derivation of UC-00 and UC-01. The helpers like jqLink are good to go then. The real importance comes when you want to build your own helper, see UC-02 for that.</p>

  5. Jul 15, 2008

    <p>The use cases are a bit too abstract to see how this helper will actually be used in real application code. Is the idea to place calls to the methods such as <code>addJavascriptFile()</code> and <code>addStyleSheet()</code> in view scripts for specific controllers, and then place a single call to <code>jQuery()</code> in the head of the layout? I think fleshing out the examples will clarify this.</p>

    <p>Also, how would you go about configuring things such as the library path, etc. just once (in some central place, such as the bootstrap or a plugin), or is this concern not even applicable?</p>

    1. Jul 15, 2008

      <p>You're right, the UC are to abstract. I will refine them tonight.</p>

      <p>The calls to addJavascriptfile and addStylesheet are supposed to be called in addional helpers that facilitate the jQuery Helper. For example if you write your own View Helper that uses jQuery, you can make sure that the appropriate additional javascript libraries are loaded.</p>

      <p>One central place to define the paths and directory variables is recommended. I can clarify this in an additional Use Case.</p>

  6. Jul 15, 2008

    <p>I have incorporated Bryces and Matthews suggestions into the proposal. For anyone who has already seen the uses cases, please re-look at Use Cases 00, 01 and 02.</p>

    <p>@Bryce: The new UC-02 clarifies your questions about calling addJavascriptFile() and addStylesheet().</p>

    <p>@Matthew: UC-00 shows how to initialize the jQuery Helper using addHelperPath().</p>

    1. Jul 17, 2008

      <p>The updated use cases are clearer, thank you!</p>

  7. Jul 15, 2008

    <p>Maybe these links will be helpfull:
    <a class="external-link" href="http://jquery.hohli.com/">http://jquery.hohli.com/</a>
    <a class="external-link" href="http://jquery.hohli.com/zf.html">http://jquery.hohli.com/zf.html</a></p>

  8. Jul 15, 2008

    <p>Good to see that someone is working on this.</p>

    <p>A small suggestion, please try to replace private with protected. private visibility is really limited to your helper otherwise. If I extended your helper, I couldn't access private methods and variables.</p>

    1. Jul 15, 2008

      <p>You are right. I've already done this. Thanks for the suggestion.</p>

  9. Jul 15, 2008

    <p>Question to all the jQuery people, would you like to have an infrastructure helper for the jQuery Events? Or should this be left out for further extensions of the component so far? I want to push the component to 1.7 which will be released soon after 1.6, so maybe there shouldn't be too much fucntionality in this proposal just yet to get it through the process?</p>

    <p>That would be a helper that can be included in more practical helpers like the first proposed practical helper "jqLink" or any future implementations may they be called jqForm, jqAutocomplete, jqDatePicker (NOT included in this proposal) and so on to register/inject global and local ajax events or the common javascript events like onClick, onSubmit and so on into the ZendX_JQuery_View_Helper_JQuery::addOnLoad method.</p>

    <p>Also, what are your suggestions on the jqLink() method header, escpecilly the $options Array. Are default effects like loading, flashing, disabling (or any others) on the wishlist?</p>

  10. Jul 16, 2008

    <p>'inline' True or false, wheater to inline the javascript in onClick="" atttribute or append it to jQuery onLoad Stack.</p>

    <p><promotingBestPractices></p>

    <p>I would suggest not to have the ability of using inline JavaScript.</p>

    <p></promotingBestPractices></p>

    1. Jul 16, 2008

      <p>I second this (I think), no inline JS rather have jquery assign it all by itself.</p>

      1. Jul 16, 2008

        <p>I dont like inline JS aswell, but someone might. Since the difference between inline or onLoad/grouped javascript ist in my opinion just a small difference and not at all something you have to restrict, I leave it in as optional argument. Also the documentation will provide hints why not to use inline javascript and what difficulties might occur (escaping).</p>

        1. Jul 17, 2008

          <p>People like all kinds of things, but I think "inline" is not best practice, and the component should adhere to that. At least IMHO. <ac:emoticon ac:name="smile" /></p>

          1. Aug 08, 2008

            <p>I agree that best practice is not having inline JavaScript code.</p>

            <p>Consider these scenarios:</p>

            <p>1. Inline JavaScript, for instance an anchor with onclick attribute, will be clickable before the page has finished loading, but it may attempt to trigger code that has yet to initialize or otherwise result in an error.</p>

            <p>2. At the same time, there may be situations where you'd want to inline something, simply because you want it to be clickable before the page has finished loading completely. That could be the case if a page has lots of images and/or third party integration that results in the page being visible and (to the visitor) usable, but is not yet fully loaded.</p>

            <p>So I agree with Benjamin and think it would be worth having the flexibility to generate either, but to default to what most would consider best practice; onload/grouped javascript.</p>

            <p>The flexibility and loosely-coupled nature of the Zend Framework is what makes it so attractive.</p>

  11. Aug 15, 2008

    <p>Thank you all for the feedback, i have finished a new version of the component (see SVN <a class="external-link" href="http://www.beberlei.de/dev/svn">http://www.beberlei.de/dev/svn</a>) and integrated all your thoughts as good as possible. Open Questions (to me) are now:</p>

    <p>1.) Should jqLink be renamed to something more insightful? jurl? (like url Helper), or jLink or something?</p>

    <p>2.) Should jqLink use the Url helper as parent class? Or should it be standalone? (Not inheriting the MVC route match of the Url helper).</p>

    <p>3.) Its the $options array layout "ok"? or are there any thoughts? (See Point 5 Theory of Operation with jqLink DocComment)</p>

    <p>I move this proposal to the next stage now, since this are questions that are more likely to match the later proposal stages.</p>

    1. Aug 17, 2008

      <p>i am sorry, i had to change the proposal at this late stage to include the functions for the jQuery UI library, that are needed to integrate the jQuery UI library smoothly.</p>

      <p>I also added the docblocks I have for all the functions to clarify the functionality.</p>

  12. Sep 04, 2008

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Comments</ac:parameter><ac:rich-text-body>
    <p>This proposal is approved for immediate development in the extras/incubator, with the following feedback:</p>
    <ul>
    <li>Please include a Zend_JQuery class with enableView() and enableForm() static methods for setting up appropriate plugin paths in those objects (as a convenience feature)<br />
    We are very pleased with this proposal and how closely it mirrors Zend_Dojo; it will serve as an excellent blueprint for additional JS offerings in the future.</li>
    </ul>
    </ac:rich-text-body></ac:macro>