Author: vkorluzhenko Date: 2007-10-16 11:24:13 -0400 (Tue, 16 Oct 2007) New Revision: 3399 Modified: trunk/docs/userguide/en/src/main/docbook/included/jQuery.desc.xml trunk/docs/userguide/en/src/main/docbook/included/jQuery.xml Log: http://jira.jboss.com/jira/browse/RF-1123 -added description Modified: trunk/docs/userguide/en/src/main/docbook/included/jQuery.desc.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/jQuery.desc.xml 2007-10-16 15:00:44 UTC (rev 3398) +++ trunk/docs/userguide/en/src/main/docbook/included/jQuery.desc.xml 2007-10-16 15:24:13 UTC (rev 3399) @@ -7,23 +7,22 @@ </sectioninfo> <section> <title>Description</title> - + <para>The <emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> allows to apply styles and behaviour to the DOM object.</para> - <mediaobject> + <!--mediaobject> <imageobject> <imagedata fileref="images/jQuery.png"/> </imageobject> - </mediaobject> + </mediaobject--> </section> <section> <title>Key Features</title> - <!--itemizedlist> - <listitem>Highly customizable look and feel</listitem> - <listitem>Popup representation</listitem> - <listitem>Disablement support</listitem> - <listitem>Smart and user-defined positioning</listitem> - <listitem>Cells customization</listitem> - <listitem>Macro substitution based on tool bars customization</listitem> - </itemizedlist--> + <itemizedlist> + <listitem>No developer JavaScript code needed to use the component on a page</listitem> + <listitem>Presents jQuery JavaScript framework functionality</listitem> + <listitem>Works without conflicts with prototype.js library</listitem> + </itemizedlist> </section> </section> Modified: trunk/docs/userguide/en/src/main/docbook/included/jQuery.xml =================================================================== --- trunk/docs/userguide/en/src/main/docbook/included/jQuery.xml 2007-10-16 15:00:44 UTC (rev 3398) +++ trunk/docs/userguide/en/src/main/docbook/included/jQuery.xml 2007-10-16 15:24:13 UTC (rev 3399) @@ -57,13 +57,12 @@ <para>To create the simplest variant on a page use the following syntax:</para> - <para> <emphasis role="bold">Example:</emphasis> </para> - <!--programlisting role="XML"><![CDATA[... - <rich:jQuery name="makeFat" timing="onJScall" query="stop().animate({width:param.ewidth})" /> -...]]></programlisting--> + <programlisting role="XML"><![CDATA[... + <rich:jQuery selector="#customList tr:odd" timing="onload" query="addClass(odd)" /> +...]]></programlisting> </section> <section> @@ -81,5 +80,265 @@ <section> <title>Details of Usage</title> + <para><emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> can be used in two major modes:</para> + <itemizedlist> + <listitem>as a one-time query applied immediately or on document ready event</listitem> + <listitem>as a JavaScript function that can be invoked from the JavaScript code</listitem> + </itemizedlist> + <para>The mode is chosen with <emphasis> + <property>&quot;timing&quot;</property> + </emphasis> attribute that has following options:</para> + <itemizedlist> + <listitem>immediate - execution a query immediately</listitem> + <listitem>onload - execution a query when a document is loaded</listitem> + <listitem>onJScall - execution a query by invoked JavaScript function defined with the <emphasis> + <property>&quot;name&quot;</property> + </emphasis> attribute</listitem> + </itemizedlist> + <para>Definition the <emphasis> + <property>&quot;name&quot;</property> + </emphasis> attribute is mandatory when the value of <emphasis> + <property>&quot;timing&quot;</property> + </emphasis> attribute is <property>&quot;onJScall&quot;</property>. If the<emphasis> + <property>&quot;name&quot;</property> + </emphasis> attribute is defined when <emphasis> + <property>&quot;timing&quot;</property> + </emphasis> value equals to <property>&quot;immediate&quot;</property> or + <property>&quot;onload&quot;</property>, the query is applied according to this + value, but you still have an opportunity to invoke it by function name.</para> + <para>The <emphasis> + <property>&quot;selector&quot;</property> + </emphasis> attribute define an object or a list of objects. The query is defined with the <emphasis> + <property>&quot;query&quot;</property> + </emphasis>attribute.</para> + <para>There is an example how to highlight odd rows in a table:</para> + <para> + <emphasis role="bold">Example:</emphasis> + </para> + <programlisting role="XML"><![CDATA[... + <style> + .odd { + background-color: #FFC; + } + </style> + ... + + <rich:table id="customList" ...> + ... + </rich:table> + ... + <rich:jQuery selector="#customList tr:odd" timing="onload" query="addClass(odd)" /> +...]]></programlisting> + <para>The <emphasis> + <property>&quot;selector&quot;</property> + </emphasis> attribute uses defined by w3c consortium syntax for CSS rule <ulink + url="http://www.w3.org/TR/REC-CSS2/selector.html">selector&l... with some jQuery + extensions. </para> + <para>Those are typical examples of using selector in the <emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> component.</para> + + <table> + <title>Examples of using selector</title> + + <tgroup cols="2"> + <thead> + <row> + <entry>Selector</entry> + + <entry>Comment</entry> + </row> + </thead> + + <tbody> + + <row> + <entry>&quot;p[a]&quot;</entry> + <entry>In a document find all &quot;p&quot; tags with &quot;a&quot; tag + inside</entry> + </row> + + <row> + <entry>&quot;ul/li&quot;</entry> + <entry>All &quot;li&quot; elements of unordered &quot;ul&quot; lists + </entry> + </row> + + <row> + <entry>&quot;p.foo[a]&quot;</entry> + <entry>All &quot;p&quot; tags with &quot;foo&quot; class and inserted + &quot;a&quot; tag </entry> + </row> + + <row> + <entry>&quot;input[@name=bar]&quot;</entry> + <entry>All &quot;input&quot; tags with &quot;name&quot; attribute which + value is &quot;bar&quot;</entry> + </row> + + <row> + <entry>&quot;input[@type=radio][@checked]&quot;</entry> + <entry>Find all &quot;input&quot; tags with attribute + &quot;type&quot;=&quot;radio&quot; and attribute value = + &quot;chekced&quot;</entry> + </row> + + <row> + <entry>&quot;p,span,td&quot;</entry> + <entry>All tag elements &quot;p&quot; or&quot;span&quot; or + &quot;td&quot; </entry> + </row> + + <row> + <entry>&quot;p#secret&quot;</entry> + <entry>&quot;p&quot; paragraph element with &quot;id&quot; + identification = &quot;secret&quot; </entry> + </row> + + <row> + <entry>&quot;p span&quot;</entry> + <entry>&quot;span&quot; tag is a (direct or non-direct) child of + &quot;p&quot; tag. If it&apos;s necessary, use &quot;p > + span&quot; or &quot;p/span&quot; </entry> + </row> + + <row> + <entry>&quot;p[@foo^=bar]&quot;</entry> + <entry>&quot;p&quot; tag containing &quot;foo&quot; attribute with + textual value beginning with &quot;bar&quot; word </entry> + </row> + + <row> + <entry>&quot;p[@foo$=bar] &quot;</entry> + <entry>&quot;p&quot; tag containing &quot;foo&quot; attribute with + textual value ending with &quot;bar&quot; word</entry> + </row> + + <row> + <entry>&quot;p[@foo*=bar] &quot;</entry> + <entry>&quot;p&quot; tag with &quot;foo&quot; attribute containing + substring &quot;bar&quot; in any place</entry> + </row> + + <row> + <entry>&quot;p//span &quot;</entry> + <entry>&quot;span&quot; tag is a (direct or non-direct) child of + &quot;p&quot; tag </entry> + </row> + + <row> + <entry>&quot;p/../span &quot;</entry> + <entry>&quot;span&quot; tag is a grandchild of &quot;p&quot; tag</entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>In addition, RichFaces allows using either component id or client id if you apply the + query to the JSF component. When you define a selector, RichFaces examines its content and + tries to replace the defined in the selector id with component id if found.</para> + <para>For example, you have the following code:</para> + + <programlisting role="XML"><![CDATA[... + <h:form id="form"> + ... + <h:panelGrid id="menu"> + <h:graphicImage ... /> + <h:graphicImage ... /> + ... + </h:panelGrid> + </h:form> +...]]></programlisting> + + <para>The actual id of the <emphasis role="bold"> + <property>&lt;h:panelGrid&gt;</property> + </emphasis> table in the browser DOM is &quot;form:menu&quot;. However, you still can + reference to images inside this table using the following selector: </para> + + <programlisting role="XML"><![CDATA[... + <rich:jQuery selector="#menu img" query="..." /> +...]]></programlisting> + + <para>You can define the exact id in the selector if you want. The following code reference to + the same set of DOM object:</para> + + <programlisting role="XML"><![CDATA[... + <rich:jQuery selector="#form\\:menu img" query="..." /> +...]]></programlisting> + + <para>Pay attention to the double slashes that escapes the colon in the id.</para> + + <para>In case when the <emphasis> + <property>&quot;name&quot;</property> + </emphasis> attribute is defined, <emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> generates a JavaScript function that might be used from any place of JavaScript + code on a page.</para> + + <para>There is an example how to enlarge the picture smoothly on mouse over event and return + back to the normal size on mouse out:</para> + + <programlisting role="XML"><![CDATA[... + <h:graphicImage onmouseover="enlargePic(this)" width="50" value=""/images/price.gif" + onmouseover="enlargePic(this, {pwidth:'60px'})" onmouseover="releasePic(this)" /> + <h:graphicImage onmouseover="enlargePic(this)" width="50" value="/images/discount.gif" + onmouseover="enlargePic(this, {pwidth:'100px'})" onmouseover="releasePic(this)" /> + ... + <rich:jQuery name="enlargePic" timing="onJScall" query="animate({width:param.pwidth})" /> + <rich:jQuery name="releasePic" timing="onJScall" query="animate({width:'50px'})"/> +...]]></programlisting> + + <para>The JavaScript could use two parameters. The first parameter is a replacement for the + selector attribute. Thus, you can share the same query execution it to the different DOM + objects. You can use the literal value or the direct reference to the existing DOM object. The + second parameter can be used to path the specific value inside the query. The JSON syntax is + used for the second parameter. The &quot;param.&quot; namespace is used for + referencing to data inside the parameter value.</para> + + <para><emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> adds styles and behavior to the DOM object dynamically. This means if you replace + something on a page during an Ajax response, the applied artifacts will be overwritten. You + are resistible to apply them again after the Ajax response is complete.</para> + <para>Normally, it could be done with reRendering the <emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> components in the same Ajax interaction with the components those queries are + applied to. Note, that queries with <emphasis> + <property>&quot;timing&quot;</property> + </emphasis> attribute set to <property>&quot;onload&quot;</property> will not be + invoked even the query is reRendered because, the DOM document is not fully reloaded during + the Ajax interaction. If you need to re-applies query with + <property>&quot;onload&quot;</property> value of <emphasis> + <property>&quot;timing&quot;</property> + </emphasis> attribute , define the <emphasis> + <property>&quot;name</property> + </emphasis> attribute and invoke the query by name in the <emphasis> + <property>&quot;oncomplete&quot;</property> + </emphasis> attribute of the Ajax component.</para> + + <para>RichFaces includes jQuery JavaScript framework. You can use the futures of jQuery directly + without defining the <emphasis role="bold"> + <property>&lt;rich:jQuery&gt;</property> + </emphasis> component on a page if it is convenient for you. To start using the jQuery feature + on the page, include the library to the page with the following code:</para> + + <programlisting role="XML"><![CDATA[... + <a4j:loadScript src="resource://jquery.js"/> +...]]></programlisting> + + <para>Refer to the <ulink url="http://docs.jquery.com/">jQuery documentation </ulink> for the + right sintax. Remember to use jQuery() function instead of $(), as soon as jQuery works + without conflicts with prototype.js.</para> </section> + <section> + <title>Relevant Resources Links</title> + <para>More information about jQuery framework and its features you can read <ulink + url="http://jquery.com/">here</ulink>.</para> + <para>How to use jQuery with other libraries see <ulink + url="http://docs.jquery.com/Using_jQuery_with_Other_Libraries"&... + + </section> </section>