From richfaces-svn-commits at lists.jboss.org Mon Aug 17 09:00:40 2009 Content-Type: multipart/mixed; boundary="===============7053909284878142719==" MIME-Version: 1.0 From: richfaces-svn-commits at lists.jboss.org To: richfaces-svn-commits at lists.jboss.org Subject: [richfaces-svn-commits] JBoss Rich Faces SVN: r15184 - branches/community/3.3.X/docs/userguide/en/src/main/docbook/included. Date: Mon, 17 Aug 2009 09:00:40 -0400 Message-ID: <200908171300.n7HD0ekG017713@svn01.web.mwc.hst.phx2.redhat.com> --===============7053909284878142719== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: artdaw Date: 2009-08-17 09:00:39 -0400 (Mon, 17 Aug 2009) New Revision: 15184 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/sug= gestionbox.desc.xml branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/sug= gestionbox.xml Log: https://jira.jboss.org/jira/browse/RF-7677 - rich:suggestionBox component d= escription review Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/inclu= ded/suggestionbox.desc.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/su= ggestionbox.desc.xml 2009-08-17 12:39:01 UTC (rev 15183) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/su= ggestionbox.desc.xml 2009-08-17 13:00:39 UTC (rev 15184) @@ -1,48 +1,73 @@
- - - rich:suggestionBox - - -
-Description - The component adds on-keypress suggestions capabilities to any i= nput text component = - (like <h:inputText>= ). When a key = - is pressed in the field Ajax request is sent to the server. When the s= uggestion action returns a = - list of possible values, it pop ups them inside the = - <div> = element bellow the input. -
- <emphasis role=3D"bold"><property><rich:suggestionbox>= ;</property></emphasis> component - = - - - - -
-
-
- Key Features - - Fully skinnable component - Adds "onkeypress" suggestions capabilities to any input text component - Performs suggestion via Ajax requests without any = line of JavaScript code written = - by you - Possible to render table as a popup suggestion - Can be pointed to any Ajax request status indicato= r of the page - Easily customizable size of suggestion popup - Setting rules that appear between cells within a t= able of popup values - "Event queue" and "request delay" attributes pres= ent to divide - frequently requests - Managing area of components submitted on Ajax requ= est - Flexible list of components to update after Ajax r= equest managed by attributes - Setting restriction to Ajax request generation - Easily setting action to collect suggestion data = - Keyboard navigation support = - + + + rich:suggestionBox + + +
+ Description + + The component adds on-keypress suggestions capabilities to any input + text component + like + + <h:inputText> + + . + +
+ + <emphasis role=3D"bold"> + <property><rich:suggestionbox></property> + </emphasis> + component + + + + + + +
+
+ Key Features + + + + Adds + + "onkeypress" + + suggestions capabilities to any input text component + + + + Possible to render table as a popup suggestion + + + Can be pointed to any Ajax request status indicator of the + page + + + Easily customizable look-and-feel + + + Fully skinnable component + + + Managing area of components submitted on Ajax request + + + Flexible list of components to update after Ajax request + managed by attributes + + + Setting restriction to Ajax request generation + + + Keyboard navigation support + + +
\ No newline at end of file Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/inclu= ded/suggestionbox.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/su= ggestionbox.xml 2009-08-17 12:39:01 UTC (rev 15183) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/su= ggestionbox.xml 2009-08-17 13:00:39 UTC (rev 15184) @@ -1,734 +1,771 @@
- - - on-keypress suggestion - rich:suggestionbox - HtmlsuggestionBox - - + + + on-keypress suggestion + rich:suggestionbox + HtmlsuggestionBox + + = - - Component identification parameters - - - - Name - Value - - - - - component-type - org.richfaces.Sug= gestionBox - - - component-class - org.richfaces.com= ponent.html.HtmlSuggestionBox - - - component-family<= /entry> - org.richfaces.Sug= gestionBox - - - renderer-type - org.richfaces.Sug= gestionBoxRenderer - - - tag-class - org.richfaces.tag= lib.SuggestionBoxTag - - - -
+
+ Details of Usage = -
- Creating the Component with a Page Tag - To create the simplest variant on a page use the= following syntax: - - - Example: - - - - - = - +
+ Main attributes + There are 3 main component attributes: + + + + + "for" + + contains an ID of an input component + for which the suggestion + support is provided + + + + + + "suggestionAction" + + defines the method to get a collection of suggestion data on + request + + + + + + "var" + + defines a collection name that provides an access for the current + row while iterating through + + + + To create the simplest variant on a page use the following + syntax: + + + + + ... ]]> - Here is the bean.autocomplete metho= d that returns the - collection to pop up: + + There is a managed bean: + + - Example: - - capitals =3D new ArrayList(); + private ArrayList capitalsNames =3D new ArrayList(); + private List capitalsOptions =3D new ArrayList(); + private String capital =3D ""; + + public List autocomplete(Object suggest) { + String pref =3D (String) suggest; + ArrayList result =3D new ArrayList(); + + Iterator iterator =3D getCapitals().iterator(); + while (iterator.hasNext()) { + Capital elem =3D ((Capital) iterator.next()); + if ((elem.getName() !=3D null && elem.getName().toLowerCase() + .indexOf(pref.toLowerCase()) =3D=3D 0) + || "".equals(pref)) { + result.add(elem); + } + } + return result; + } + + public SBbean() { + URL rulesUrl =3D getClass().getResource("capitals-rules.xml"); + Digester digester =3D DigesterLoader.createDigester(rulesUrl); + digester.push(this); + try { + digester.parse(getClass().getResourceAsStream("capitals.xml")); + } catch (IOException e) { + throw new FacesException(e); + } catch (SAXException e) { + throw new FacesException(e); + } + capitalsNames.clear(); + for (Capital cap : capitals) { + capitalsNames.add(cap.getName()); + } + capitalsOptions.clear(); + for (Capital cap : capitals) { + capitalsOptions.add(new SelectItem(cap.getName(), cap.getState())); + } + } + + public String addCapital(Capital capital) { + capitals.add(capital); + return null; + } +} = ]]> -
-
- Creating the Component Dynamically Using Java</= title> + <para> + In the example above when suggestion item (city) is selected it is + set as a value of + <code><h:inputText id=3D"city"/></code> + . + </para> + <para> + Here is a result: + </para> + <figure> + <title> + <emphasis role=3D"bold"> + Simple + <property><rich:suggestionbox></property> + </emphasis> + + + + + + + = - - Example: - - + The + + <rich:suggestionbox> + + component could get any collection + and outputs it in a + popup in + several columns. The + + "fetchValue" + + attribute points to the data that is inserted into the input field + if a particular row is selected + or clicked from the suggested list. + Therefore when some string is chosen input + receives the proper value. + + + + + + + + + + ... -HtmlSuggestionBox myList =3D new HtmlSuggestionBox(); -... ]]> -
-
- Details of Usage - As it is shown in the example above, the main co= mponent attribute are: - - - - - "for"= ; - - - The attribute where there is= an input component which - activation causes a sugg= estion activation - - - - - "suggesti= onAction" - - - is an accepting parameter o= f a suggestionEvent type - that returns as a result= a collection for - rendering in a tool tip = window. - - - - - "var"= ; - - - a collection name that prov= ides access for inputting - into a table in a popup<= /para> - - - There are also two size attributes ( - "width" - and - "height" - ) that are obligatory for the sug= gestion component. The - attributes have initial Defaults but should = be specified manually in - order to be changed. - The suggestionbox component= , as it is shown on the - screenshot, could get any collection for an = output and outputs it in a - ToolTip window the same as a custom dataTabl= e (in several columns) - - - - - - - + + In the example above if you choose any string input will receive the + corresponding value + from the second column containing + #{result.state} + . + + Here is a result: +
+ + <emphasis role=3D"bold"> + <property><rich:suggestionbox></property> + </emphasis> + with output in several columns + + + + + + +
+ + There is also one more important attribute named + + "tokens" + + that specifies separators after which a set of some + characters + sequence is defined as a new prefix beginning from this + separator and + not from the string beginning. + + + Example: + + + + + + ... ]]> - It looks on a page in the following way: -
- <emphasis role=3D"bold"> - <property><rich:sugge= stionbox></property> - </emphasis> with ToolTip window</t= itle> - <mediaobject> - <imageobject> - <imagedata fileref=3D"im= ages/suggestionbox2.png"/> - </imageobject> - </mediaobject> - </figure> - <para>When some string is chosen input receives the co= rresponding value from the - second column containing <code>#{cit.text}</= code></para> - <para>There is also one more important attribute named= <emphasis> - <property>"tokens"</prop= erty> - </emphasis> that specifies separators after = which a set of some - characters sequence is defined as a new pref= ix beginning from this - separator and not from the string beginning.= </para> - <para> - <emphasis role=3D"bold">Example:</emphasis> - </para> - <programlisting role=3D"XML"><![CDATA[... -<rich:suggestionbox for=3D"test" suggestionAction=3D"#{bean.autocomplete}"= var=3D"cit" selfRendered=3D"true" tokens=3D","> = - <h:column> - <h:outputText value=3D"#{cit.text}"/> - </h:column> + <para>This example shows that when a city is chosen and a comma and + first letter + character are input, Ajax request is called again, but + it + submits a + value starting from the last token:</para> + <figure> + <title> + <emphasis role=3D"bold"> + <property><rich:suggestionbox></property> + </emphasis> + with chosen word + + + + + + +
+ For + a multiple definition use either " + ,.;[] + " + syntax as a value for + + "tokens" + + attribute or link a parameter to some bean + property that transmits + separators collection. + +
+
+ JavaScript API + + There is such feature of the + + <rich:suggestionbox> + + component as + object selection + . + If you want to get the selected item as object on the client side + you should set the value of the + + "usingSuggestObjects" + + attribute + to "true". + After that you should specify + JavaScript method in the + + "onobjectchange" + + attribute and pass the + suggestion + object as a parameter: + + + + + + + +
+ ... ]]> - This example shows that when a city is chosen an= d a comma and first letter - character are input, Ajax request is called = again, but it submits a - value starting from the last token: -
- <emphasis role=3D"bold"> - <property><rich:sugge= stionbox></property> - </emphasis> with chosen word</titl= e> - <mediaobject> - <imageobject> - <imagedata fileref=3D"im= ages/suggestionbox3.png"/> - </imageobject> - </mediaobject> - </figure> - <para>For a multiple definition use either "<code= >,.;</code> " - syntax as a value for tokens or link a param= eter to some bean property - transmitting separators collection.</para> - <para>The component also encompasses <emphasis> - <property>"style"</prope= rty> - </emphasis> attributes corresponding to data= Table ones for a table - appearing in popup (for additional informati= on, read JSF Reference) - and custom attribute managing Ajax requests = sending (for additional - information, see <ulink - url=3D"http://www.jboss.org/commun= ity/wiki/Ajax4jsf">Ajax4JSF - Project</ulink>).</para> - <para>In addition to these attributes common for Ajax = action components and - limiting requests quantity and frequency, - <property>suggestionbox</property> has one m= ore its own attribute - limiting requests (the <emphasis> - <property>"minChars"</pr= operty> - </emphasis> attribute). The attribute define= s characters quantity - inputted into a field after which Ajax reque= sts are called to perform - suggestion.</para> + <para> + When the item is selected you can get it as an object on the client + side and use + <code>getSelectedItems()</code> + method to access any object properties: + </para> + <programlisting role=3D"XML"><![CDATA[<script type=3D"text/javascript"> +function processObjects(suggestionBox) { + var items =3D suggestionBox.getSelectedItems(); + var state; + if (items && items.length > 0) { + for ( var i =3D 0; i < items.length; i++) { + state =3D items[i].state; + } + document.getElementById('state').innerHTML =3D "State: "+state; = + }else{ + document.getElementById('state').innerHTML =3D ''; + } +} = +</script> +]]></programlisting> + <para> + Here is a result: + </para> + <figure> + <title> + Usage of + <code>getSelectedItems()</code> + method + + + + + + +
+
+
+ Other attributes and facets + + In addition to attributes common for Ajax action components + and + limiting requests quantity and frequency, + the + + <rich:suggestionbox> + + has one more its own attribute + limiting requests: the + + "minChars" + + attribute. This attribute defines characters quantity + inputted into a + field after which Ajax requests are called to perform + suggestion. + = = - There is possibility to define what be shown if= the autocomplete returns - empty list. Attribute - "nothingLabel"= ; - or facet with the same name could= be used for it. - - Example: - - = - - - + + There is possibility to define what is shown if the autocomplete + returns empty list. Attribute + + "nothingLabel" + + or facet with the same name could be used for this purpose. + + + Example: + + + + + ... ]]> - - Example: - - = + Here is a result: +
+ + <emphasis role=3D"bold"> + <property><rich:suggestionbox></property> + </emphasis> + with empty list + + + + + + +
+ + You can also use facets for the further + + <rich:suggestionbox> + + customization: + + + - - = + + + + + - + ... ]]> - - - It looks on a page in the following way: - -
- <emphasis role=3D"bold"> - <property><rich:sugge= stionbox></property> - </emphasis> with empty list - - - - - -
- There is such feature in - <rich:suggestionbox&g= t; - component as object selection. I= f you want that selected - item has been represented as object, you cou= ld set to "true" the value - for - "usingSuggestObjec= ts" - - attribute, "false" value means t= hat selected item - represents as string. - - Example: - - = - - - - -... -]]> - Information about the - "process" - attribute usage you can findin the = - "Decide what= to process" guide section. - In RichFaces Wiki article about - Additional Properties yo= u can find example of getting additional - properties. -
-
- JavaScript API - - JavaScript API - - - - - Function - - Description - - - - - - - callSuggestion()<= /entry> - Calls the suggest= ion. If the - "ignoreMinChars&quo= t; - value is - "true" then - the number of symbols to= send - a query is no longer act= ual - for callSuggestion() - - - - getSelectedItems(= ) - Returns the array= of - objects - - - - -
-
- = + + Here is a result: + +
+ + <emphasis role=3D"bold"> + <property><rich:suggestionbox></property> + </emphasis> + facets + + + + + + +
+ + Information about the + + "process" + + attribute usage you can findin the + "Decide what to process" + guide section. + + + In RichFaces Wiki article about + + Additional Properties + you can find example of getting additional + properties. + +
- Facets - - Facets - - - - Facet name - Description - - - - - nothingLabel - Redefines the content item if the autocomplete returns empty= list. Related attribute is "nothingLabel" - - - popup - Redefines the content for the popup list of the suggestion - - - header - Defines the header content - - - footer - Defines the footer content - - - -
-
- = -
- Look-and-Feel Customization + Custom style classes redefinition + + In order to redefine styles for all + + <rich:suggestionbox> + + components on a page using CSS, it's enough to + create classes + with the same names (possible classes could be found in + the tables + above + ) and define + necessary properties in them. + = - For skinnability implementation, the components = use a - style class redefinition= method. - Default style classes are mapped= on - skin parameters. - - - There are two ways to redefine the appearance of= all - <rich:suggestionbox&g= t; - components at once: - - - - Redefine the corresponding s= kin parameters - - - - Add to your style sheets - style classes<= /property> - used by a - <rich:sugge= stionbox> - component - - -
- -
- Skin Parameters Redefinition - - - General skin parameters redefinition = for popup list - - - - - Parameters for po= pup list - - CSS properties - - - - - - additionalBackgro= undColor - - background-color<= /entry> - - - - panelBorderColor<= /entry> - - border-color - - - -
- - - Skin parameters redefinition for shad= ow element of the list - - - - - Parameters for sh= adow element of - the list - - CSS properties - - - - - - shadowBackgroundC= olor - - background-color<= /entry> - - - - shadowBackgroundC= olor - - border-color - - - - shadowOpacity - - opacity - - - -
- - - Skin parameters redefinition for popu= p table rows - - - - - Parameters for po= pup table rows - - CSS properties - - - - - - generalSizeFont - - font-size - - - - generalTextColor<= /entry> - - color - - - - generalFamilyFont= - - font-family - - - -
- - - Skin parameters redefinition for sele= cted row - - - - - Parameters for se= lected row - - CSS properties - - - - - - headerBackgroundC= olor - - background-color<= /entry> - - - - generalSizeFont - - font-size - - - - generalFamilyFont= - - font-family - - - headerTextColor - - color - - - - -
-
- -
- Definition of Custom Style Classes - -
- Classes names - - - - - - -
- - On the screenshot, there are classes names defin= ing specified elements. - - - Classes names that define a suggestio= nbox - - - - - Class name - - Description - - - - - - rich-sb-common-co= ntainer - - Defines styles fo= r a wrapper - <div> element of - a suggestion container - - - - rich-sb-ext-decor= -1 - - Defines styles fo= r the first - wrapper <div> - element of a suggestion = box - exterior - - - - rich-sb-ext-decor= -2 - - Defines styles fo= r the second - wrapper <div> - element of a suggestion = box - exterior - - - - rich-sb-ext-decor= -3 - - Defines styles fo= r the third - wrapper <div> - element of a suggestion = box - exterior - - - - rich-sb-overflow<= /entry> - - Defines styles fo= r a wrapper - <div> - element - - - - rich-sb-int-decor= -table - - Defines styles fo= r a suggestion - box table - - - - rich-sb-int - - Defines the style= s for a - suggestion box table rows - (tr) - - - - rich-sb-cell-padd= ing - - Defines the style= s for suggestion - box table cells (td) - - - - rich-sb-int-sel - - Defines styles fo= r a selected - row - - - - rich-sb-shadow - - Defines styles fo= r a suggestion - boxshadow - - - - -
- - In order to redefine styles for all - <rich:suggestionbox&g= t; - components on a page using CSS, = it's enough to - create classes with the same names (possible= classes could be found in - the tables above= ) and define - necessary properties in them. - - - Example: - - + Example: + + = - This is a result: + This is a result: = -
- Redefinition styles with predefined c= lasses - - - - - -
+
+ Redefinition styles with predefined classes + + + + + +
= - In the example the font weight for rows was chan= ged. + In the example the font weight for rows was changed. = - Also it's possible to change styles of part= icular - <rich:suggestionbox&g= t; - component. In this case you shou= ld create own style - classes and use them in corresponding - <rich:suggestionbox&g= t; - - - styleClass - attributes. An example is placed= below: + Also + it's possible to change styles of particular + + <rich:suggestionbox> + + component. In this case you should create own style + classes and use + them in corresponding + + <rich:suggestionbox> + + + styleClass + + attributes. An example is placed below: + = - - Example: - - + Example: + + - The - "selectedClass"= ; - attribute for - <rich:suggestionbox&g= t; - is defined as it's shown in= the example below: + + The + + "selectedClass" + + attribute for + + <rich:suggestionbox> + + is defined as it's shown in the example below: + = - - Example: - - + + Example: + + ]]> = - This is a result: + This is a result: = -
- Redefinition styles with own classes = and <emphasis> - <property>styleClass</pr= operty> - </emphasis> attributes - - - - - -
+
+ + Redefinition styles with own classes and + <emphasis> + <property>styleClass</property> + </emphasis> + attributes + + + + + + +
= - As it could be seen on the picture above,backgro= und color for selected - item was changed. + As it could be seen on the picture above,background color for + selected + item was changed. +
= +
+
+ + + rich:suggestionbox + + + Reference Data + = + + Table of <rich:suggestionbox> attributes + + + + Component identification parameters + + + + Name + Value + + + + + component-type + org.richfaces.SuggestionBox + + + component-class + org.richfaces.component.html.HtmlSuggestionBox + + + component-family + org.richfaces.SuggestionBox + + + renderer-type + org.richfaces.SuggestionBoxRenderer + + + tag-class + org.richfaces.taglib.SuggestionBoxTag + + + +
+ + Facets + + + + Facet name + Description + + + + + nothingLabel + Redefines the content item if the autocomplete returns + empty + list. Related attribute is "nothingLabel" + + + popup + Redefines the content for the popup list of the suggestion + + + + header + Defines the header content + + + footer + Defines the footer content + + + +
+ + JavaScript API + + + + Function = - + Description + + = + = + + callSuggestion() + Calls the suggestion. If the + "ignoreMinChars" + value is + "true" then + the number of symbols to send + a query + is no longer actual + for callSuggestion() + = -
- Relevant Resources Links - Vizit SuggestionBox<= /ulink> = - page at RichFaces Livedemo for examples of component usage and source= s. - - RichFaces cookbook at JBoss Portal includes some articles that = cover different aspects of working with = - <rich:suggestionbox>: - - - - - "Creating suggestion box dynamically"; - - - - - "Getting additional properties from <rich:suggectionbox>&q= uot;. - - = - - = - = -
+ + getSelectedItems() + Returns the array of + objects + = + + +
+ + Classes names with the corresponding skin parameters + + + + Class name + Description + Skin Parameters + CSS properties + + + + + + .rich-sb-int + Defines the styles for a + suggestion box table + rows + <tr> + generalSizeFont + font-size + + + generalFamilyFont + font-family + + + generalTextColor + color + + + + .rich-sb-int-sel + Defines styles for a selected + row + headerBackgroundColor + background-color + + + generalSizeFont + font-size + + + generalFamilyFont + font-family + + + headerTextColor + color + + + .rich-sb-ext-decor-2 + Defines styles for the second + wrapper + <div> + element of + a suggestion box + exterior + panelBorderColor + border-color + + + additionalBackgroundColor + background-color + + + .rich-sb-shadow + Defines styles for a suggestion + boxshadow + + shadowBackgroundColor + background-color + + + shadowBackgroundColor + border-color + + + shadowOpacity + opacity + + + + +
+
+
+ Relevant Resources Links + + Vizit + + <rich:suggestionbox> + + page at RichFaces Livedemo for examples of component usage and + sources. + + + RichFaces cookbook at JBoss Portal includes some articles that cover + different aspects of working with + + <rich:suggestionbox> + + : + + + + + " + Creating= suggestion box dynamically + "; + + + + + " + Getting = additional properties from + <rich:suggectionbox> + ". + + + +
--===============7053909284878142719==--