Author: atsebro Date: 2009-08-27 12:12:28 -0400 (Thu, 27 Aug 2009) New Revision: 15353 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/rich_hotKey.xml Log: RF-7756: Rich Miscellaneous component group description review --> rich:hotKey Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/rich_hotKey.xml =================================================================== --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/rich_hotKey.xml 2009-08-27 16:08:52 UTC (rev 15352) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/rich_hotKey.xml 2009-08-27 16:12:28 UTC (rev 15353) @@ -1,102 +1,69 @@ <section role="NotInToc" id="rich_hotKey"> - <title> - &lt; - rich:hotKey - &gt; - <emphasis role="since"> - <superscript> available since <emphasis role="version">3.2.2</emphasis> - </superscript> - </emphasis> - </title> - <section> - <title>Description</title> - <para>The <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> component allows to register hot keys for the page or particular elements and to define client-side processing functions for these keys. - </para> - </section> - <section> - <title>Key Features</title> - <itemizedlist> - <listitem> - <para> - Includes all features of the <ulink url="http://code.google.com/p/js-hotkeys/">Javascript jQuery Hotkeys Plugin</ulink> - </para> - </listitem> - <listitem> - <para> - Hot key registration by request through JavaScript API - </para> - </listitem> - <listitem> - <para> - Possibility to attach <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> to a whole page or - to a particular element using <emphasis> - <property>"selector"</property> - </emphasis> attribute - </para> - </listitem> - <listitem> - <para> - Hot key registration timing - </para> - </listitem> + <title> &lt; rich:hotKey &gt; <emphasis role="since"> + <superscript> available since <emphasis role="version">3.2.2</emphasis> + </superscript> + </emphasis> + </title> + <section> + <title>Description</title> + <para> + The <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> component allows to register hot keys for the page or particular elements and to define client-side processing functions for these keys. + </para> + </section> + <section> + <title>Key Features</title> + <itemizedlist> + <listitem> + <para>Includes all features of the <ulink url="http://code.google.com/p/js-hotkeys/">Javascript jQuery Hotkeys Plugin</ulink> + </para> + </listitem> + <listitem> + <para> + Hot key registration by request through JavaScript API + </para> + </listitem> + <listitem> + <para> + Possibility to attach <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> to a whole page or to a particular element using <emphasis><property>"selector"</property></emphasis> attribute + </para> + </listitem> + <listitem> + <para> + Hot key registration timing + </para> + </listitem> - <listitem> - <para> - Enabling/disabling the <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> using JavaScript API - </para> - </listitem> - </itemizedlist> - </section> - <section> - <title>Details of Usage</title> - <para> - There are two ways to register <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis>: - </para> - <itemizedlist> - <listitem> - <para> - just place it anywhere on the page. In this case the <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> - component is attached to the whole page (<property>html[0] element</property>). This is default scenario. - </para> - </listitem> - <listitem> - <para> - attach it with <emphasis> - <property>"selector"</property> - </emphasis> attribute to all the elements defined using this selector. - This attribute uses defined by <ulink url="http://www.w3.org">w3c consortium</ulink> syntax for CSS rule selector with some jQuery extensions. - </para> - </listitem> - </itemizedlist> - <para> - The <emphasis> - <property>"key"</property> - </emphasis> attribute defines the hot key itself - which is processed by the component. - </para> - <para> - After the hot key has been registered and defined you could set the <emphasis> - <property>"handler"</property> - </emphasis> - attribute which determines a JavaScript function to be called every time when corresponding keys are pressed. - </para> - <para> - <emphasis role="bold"> - Example: - </emphasis> - </para> - <programlisting role="XML">... -&lt;rich:listShuttle var="cap" sourceValue="#{capitalsBean.capitals}" id="ls"&gt; + <listitem> + <para> + Enabling/disabling the <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> using JavaScript API + </para> + </listitem> + </itemizedlist> + </section> + <section> + <title>Details of Usage</title> + <para> + There are two ways to register <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis>: + </para> + <itemizedlist> + <listitem> + <para> + place it anywhere on the page. In this case the <emphasis role="bold"><property>&lt;rich:hotKey&gt;</property></emphasis> component is attached to the whole page (<code>html[0] element</code>). This is default scenario. + </para> + </listitem> + <listitem> + <para> + attach it with <emphasis><property>"selector"</property></emphasis> attribute to all the elements defined using this selector. This attribute uses defined by <ulink url="http://www.w3.org">w3c consortium</ulink> syntax for CSS rule selector with some jQuery extensions. + </para> + </listitem> + </itemizedlist> + <para> + The <emphasis><property>"key"</property></emphasis> attribute defines the hot key itself which is processed by the component. + </para> + <para> + After the hot key has been registered and defined you could set the <emphasis><property>"handler"</property></emphasis> attribute which determines a JavaScript function to be called every time when corresponding keys are pressed. + </para> + <programlisting role="XML">&lt;rich:listShuttle var="cap" sourceValue="#{capitalsBean.capitals}" id="ls"&gt; &lt;rich:column&gt; &lt;f:facet name="header"&gt; &lt;h:outputText value="State flag"/&gt; @@ -110,172 +77,137 @@ &lt;h:outputText value="#{cap.name}"/&gt; &lt;/rich:column&gt; &lt;/rich:listShuttle&gt; -&lt;rich:hotKey selector="#ls" key="right" handler="#{rich:component('ls')}.copy()"/&gt; -&lt;rich:hotKey selector="#ls" key="left" handler="#{rich:component('ls')}.remove()"/&gt; -&lt;rich:hotKey selector="#ls" key="end" handler="#{rich:component('ls')}.copyAll()"/&gt; -&lt;rich:hotKey selector="#ls" key="home" handler="#{rich:component('ls')}.removeAll()"/&gt; -...</programlisting> - <para> - In the example above the <emphasis> - <property>"selector"</property> - </emphasis> attribute is used. - So the keys work only if <emphasis role="bold"> - <property>&lt;rich:listShuttle&gt;</property> - </emphasis> component is focused. - </para> - <para> - You could press <property>Right</property> or <property>Left</property> keys in order to move some selected items between lists. - You could press <property>Home</property> or <property>End</property> buttons in order to move all items between lists. - </para> - <para> - With the help of the <emphasis> - <property>"timing"</property> - </emphasis> attribute - you could manage <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> registration timing. - There are three possible values of this attribute: - </para> - <itemizedlist> - <listitem> - <para> - "immediate" - the component is rendered in browser immediately (by default) - </para> - </listitem> - <listitem> - <para> - "onload" - the component is rendered after the page is fully loaded - </para> - </listitem> - <listitem> - <para> - "onregistercall" - the component is rendered only after JavaScript API for the key registration is used. - </para> - </listitem> - </itemizedlist> - <para> - The <emphasis> - <property>"type"</property> - </emphasis> attribute defines the type of keyboard event. Possible values are: - "onkeyup", "onkeypress" and "onkeydown". - </para> - <!--EXAMPLE --> - <para> - The <emphasis> - <property>"disableInInput"</property> - </emphasis> attribute disables the <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> if it is activated on input elements and the value of this attribute is "true". - </para> - <para> - The <emphasis> - <property>"checkParent"</property> - </emphasis> attribute defines the hotkey handling of events generated by child components nested into the parent component to which the <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> is attached. - </para> - <para> - The <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> component also provides a number of JavaScript API functions. There is an example below. - </para> - <para> - <emphasis role="bold">Example:</emphasis> - </para> - <programlisting role="XML">... -&lt;h:form id="myForm"&gt; +&lt;rich:hotKey selector="#ls" key="right" handler="#{rich:component('ls')}.copy()"/&gt; +&lt;rich:hotKey selector="#ls" key="left" handler="#{rich:component('ls')}.remove()"/&gt; +&lt;rich:hotKey selector="#ls" key="end" handler="#{rich:component('ls')}.copyAll()"/&gt; +&lt;rich:hotKey selector="#ls" key="home" handler="#{rich:component('ls')}.removeAll()"/&gt;</programlisting> + <para> In the example above the <emphasis> + <property>"selector"</property> + </emphasis> attribute is used. So the keys work only if <emphasis role="bold"> + <property>&lt;rich:listShuttle&gt;</property> + </emphasis> component is focused. </para> + <para> You could press <property>Right</property> or <property>Left</property> keys in order to move some selected items between lists. You could press <property>Home</property> or <property>End</property> buttons in order to + move all items between lists. </para> + <para> With the help of the <emphasis> + <property>"timing"</property> + </emphasis> attribute you could manage <emphasis role="bold"> + <property>&lt;rich:hotKey&gt;</property> + </emphasis> registration timing. There are three possible values of this attribute: </para> + <itemizedlist> + <listitem> + <para> + <code>immediate</code> — the component is rendered in browser immediately (default value); + </para> + </listitem> + <listitem> + <para> + <code>onload</code> — the component is rendered after the page is fully loaded; + </para> + </listitem> + <listitem> + <para> + <code>onregistercall</code> — the component is rendered only after JavaScript API for the key registration is used. + </para> + </listitem> + </itemizedlist> + <para>The <emphasis><property>"type"</property></emphasis> attribute defines the type of keyboard event. Possible values are: <code>onkeyup</code>, <code>onkeypress</code> and <code>onkeydown</code>. + </para> + <!--EXAMPLE --> + <para> The <emphasis> + <property>"disableInInput"</property> + </emphasis> attribute disables the <emphasis role="bold"> + <property>&lt;rich:hotKey&gt;</property> + </emphasis> if it is activated on input elements and the value of this attribute is <code>true</code>. </para> + <para> The <emphasis> + <property>"checkParent"</property> + </emphasis> attribute defines the hotkey handling of events generated by child components nested into the parent component to which the <emphasis role="bold"> + <property>&lt;rich:hotKey&gt;</property> + </emphasis> is attached. </para> + <para> The <emphasis role="bold"> + <property>&lt;rich:hotKey&gt;</property> + </emphasis> component also provides a number of JavaScript API functions. There is an example below. </para> + <programlisting role="XML">&lt;h:form id="myForm"&gt; &lt;rich:hotKey id="myKey" key="ctrl+g" handler="alert('Ctrl+G is pressed')" /&gt; &lt;button onclick="${rich:component('myKey')}.enable(); return false;"&gt;Turn Ctrl+G On&lt;/button&gt; &lt;button onclick="${rich:component('myKey')}.disable(); return false;"&gt;Turn Ctrl+G Off&lt;/button&gt; -&lt;/h:form&gt; -...</programlisting> - <para> - In the example above the <property>Ctrl+G</property> is registered as a global hotkey, - so if you press this key combination the alert window with the <property>"Ctrl+G is pressed"</property> text appears. With the help - of <property>enable()</property>, <property>disable()</property> JavaScript API fucntions you could enable or disable registered hotkey. - </para> - </section> - <section> - <title>Reference Data</title> - <para> - <ulink url="&tlddoc;rich/hotKey.html">Table of - &lt;rich:hotKey&gt; - attributes</ulink>. - </para> - <table> - <title>Component Identification Parameters</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Name</entry> - <entry>Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>component-type</entry> - <entry>org.richfaces.HotKey</entry> - </row> - <row> - <entry>component-class</entry> - <entry>org.richfaces.component.html.HtmlHotKey</entry> - </row> - <row> - <entry>component-family</entry> - <entry>org.richfaces.HotKey</entry> - </row> - <row> - <entry>renderer-type</entry> - <entry>org.richfaces.HotKeyRenderer</entry> - </row> - <!--row> +&lt;/h:form&gt;</programlisting> + <para> + In the example above the <code>Ctrl+G</code> is registered as a global hotkey, so if you press this key combination the alert window with the <code>"Ctrl+G is pressed"</code> text appears. + With the help of <code>enable()</code>, <code>disable()</code> JavaScript API fucntions you could enable or disable registered hotkey. + </para> + </section> + <section> + <title>Reference Data</title> + <para> + <ulink url="&tlddoc;rich/hotKey.html">Table of &lt;rich:hotKey&gt; attributes</ulink>. </para> + <table> + <title>Component Identification Parameters</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Name</entry> + <entry>Value</entry> + </row> + </thead> + <tbody> + <row> + <entry>component-type</entry> + <entry>org.richfaces.HotKey</entry> + </row> + <row> + <entry>component-class</entry> + <entry>org.richfaces.component.html.HtmlHotKey</entry> + </row> + <row> + <entry>component-family</entry> + <entry>org.richfaces.HotKey</entry> + </row> + <row> + <entry>renderer-type</entry> + <entry>org.richfaces.HotKeyRenderer</entry> + </row> + <!--row> <entry>tag-class</entry> <entry></entry> </row--> - </tbody> - </tgroup> - </table> - <table> - <title>JavaScript API</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Function</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - add(selector, key, handler) - </entry> - <entry> - Adds the hotkey(from key param) for elements targeted by selector. it assigns a handler function to the key - </entry> - </row> - <row> - <entry>remove()</entry> - <entry>Removes hotkey registration</entry> - </row> - <row> - <entry>enable()</entry> - <entry>Enables registered hotkey</entry> - </row> - <row> - <entry>disable()</entry> - <entry>Disables registered hotkey</entry> - </row> - </tbody> - </tgroup> - </table> - </section> - <section> - <title>Relevant Resources Links</title> - <para> - <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/hotKey.jsf?... RichFaces LiveDemo page </ulink> you can see an example of - <emphasis role="bold"> - <property>&lt;rich:hotKey&gt;</property> - </emphasis> usage and sources for the given example. - </para> - </section> -</section> \ No newline at end of file + </tbody> + </tgroup> + </table> + <table> + <title>JavaScript API</title> + <tgroup cols="2"> + <thead> + <row> + <entry>Function</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> add(selector, key, handler) </entry> + <entry> Adds the hotkey(from key param) for elements targeted by selector. it assigns a handler function to the key </entry> + </row> + <row> + <entry>remove()</entry> + <entry>Removes hotkey registration</entry> + </row> + <row> + <entry>enable()</entry> + <entry>Enables registered hotkey</entry> + </row> + <row> + <entry>disable()</entry> + <entry>Disables registered hotkey</entry> + </row> + </tbody> + </tgroup> + </table> + </section> + <section> + <title>Relevant Resources Links</title> + <para> + <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/hotKey.jsf?... RichFaces LiveDemo page </ulink> you can see an example of <emphasis role="bold"> + <property>&lt;rich:hotKey&gt;</property> + </emphasis> usage and sources for the given example. </para> + </section> +</section>