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/suggestionbox.desc.xml
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.xml
Log:
https://jira.jboss.org/jira/browse/RF-7677 - rich:suggestionBox component description
review
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml
===================================================================
---
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml 2009-08-17
12:39:01 UTC (rev 15183)
+++
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml 2009-08-17
13:00:39 UTC (rev 15184)
@@ -1,48 +1,73 @@
<?xml version="1.0" encoding="UTF-8"?>
<section>
-<sectioninfo>
-<keywordset>
- <keyword>rich:suggestionBox</keyword>
-</keywordset>
-</sectioninfo>
-<section>
-<title>Description</title>
- <para>The component adds on-keypress suggestions capabilities to any input text
component
- (like <emphasis
role="bold"><property><h:inputText></property></emphasis>).
When a key
- is pressed in the field Ajax request is sent to the server. When the suggestion
action returns a
- list of possible values, it pop ups them inside the
- <emphasis
role="bold"><property><div></property></emphasis>
element bellow the input.</para>
- <figure>
- <title><emphasis
role="bold"><property><rich:suggestionbox></property></emphasis>
component</title>
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/suggestionbox_init.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- </section>
- <section>
- <title>Key Features</title>
- <itemizedlist>
- <listitem><para>Fully skinnable
component</para></listitem>
- <listitem><para>Adds
<emphasis><property>"onkeypress"</property></emphasis>
suggestions capabilities to any input text component</para></listitem>
- <listitem><para>Performs suggestion via Ajax requests without any
line of JavaScript code written
- by you</para></listitem>
- <listitem><para>Possible to render table as a popup
suggestion</para></listitem>
- <listitem><para>Can be pointed to any Ajax request status indicator
of the page</para></listitem>
- <listitem><para>Easily customizable size of suggestion
popup</para></listitem>
- <listitem><para>Setting rules that appear between cells within a
table of popup values</para></listitem>
- <listitem><para><emphasis
-
-><property>"Event queue"</property></emphasis> and
<emphasis
-
-><property>"request delay"</property></emphasis>
attributes present to divide
- frequently requests</para></listitem>
- <listitem><para>Managing area of components submitted on Ajax
request</para></listitem>
- <listitem><para>Flexible list of components to update after Ajax
request managed by attributes</para></listitem>
- <listitem><para>Setting restriction to Ajax request
generation</para></listitem>
- <listitem><para>Easily setting action to collect suggestion
data</para></listitem>
- <listitem><para>Keyboard navigation
support</para></listitem>
- </itemizedlist>
+ <sectioninfo>
+ <keywordset>
+ <keyword>rich:suggestionBox</keyword>
+ </keywordset>
+ </sectioninfo>
+ <section>
+ <title>Description</title>
+ <para>
+ The component adds on-keypress suggestions capabilities to any input
+ text component
+ like
+ <emphasis role="bold">
+ <property><h:inputText></property>
+ </emphasis>
+ .
+ </para>
+ <figure>
+ <title>
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ component
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox_init.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
</section>
+ <section>
+ <title>Key Features</title>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Adds
+ <emphasis>
+ <property>"onkeypress"</property>
+ </emphasis>
+ suggestions capabilities to any input text component
+ </para>
+ </listitem>
+ <listitem>
+ <para>Possible to render table as a popup suggestion</para>
+ </listitem>
+ <listitem>
+ <para>Can be pointed to any Ajax request status indicator of the
+ page</para>
+ </listitem>
+ <listitem>
+ <para>Easily customizable look-and-feel</para>
+ </listitem>
+ <listitem>
+ <para>Fully skinnable component</para>
+ </listitem>
+ <listitem>
+ <para>Managing area of components submitted on Ajax request</para>
+ </listitem>
+ <listitem>
+ <para>Flexible list of components to update after Ajax request
+ managed by attributes</para>
+ </listitem>
+ <listitem>
+ <para>Setting restriction to Ajax request generation</para>
+ </listitem>
+ <listitem>
+ <para>Keyboard navigation support</para>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>
\ No newline at end of file
Modified:
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.xml
===================================================================
---
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.xml 2009-08-17
12:39:01 UTC (rev 15183)
+++
branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/suggestionbox.xml 2009-08-17
13:00:39 UTC (rev 15184)
@@ -1,734 +1,771 @@
<?xml version='1.0' encoding='UTF-8'?>
<section>
- <sectioninfo>
- <keywordset>
- <keyword>on-keypress suggestion</keyword>
- <keyword>rich:suggestionbox</keyword>
- <keyword>HtmlsuggestionBox</keyword>
- </keywordset>
- </sectioninfo>
+ <sectioninfo>
+ <keywordset>
+ <keyword>on-keypress suggestion</keyword>
+ <keyword>rich:suggestionbox</keyword>
+ <keyword>HtmlsuggestionBox</keyword>
+ </keywordset>
+ </sectioninfo>
- <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.SuggestionBox</entry>
- </row>
- <row>
-
<entry>component-class</entry>
-
<entry>org.richfaces.component.html.HtmlSuggestionBox</entry>
- </row>
- <row>
-
<entry>component-family</entry>
-
<entry>org.richfaces.SuggestionBox</entry>
- </row>
- <row>
-
<entry>renderer-type</entry>
-
<entry>org.richfaces.SuggestionBoxRenderer</entry>
- </row>
- <row>
- <entry>tag-class</entry>
-
<entry>org.richfaces.taglib.SuggestionBoxTag</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <section>
+ <title>Details of Usage</title>
- <section>
- <title>Creating the Component with a Page Tag</title>
- <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[...
-<h:inputText value="#{bean.property}" id="suggest"/>
-<rich:suggestionbox for="suggest"
suggestionAction="#{bean.autocomplete}" var="suggest">
- <h:column>
- <h:outputText value="#{suggest.text}"/>
- </h:column>
+ <section>
+ <title>Main attributes</title>
+ <para>There are 3 main component attributes:</para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>
+ <property>"for"</property>
+ </emphasis>
+ contains an ID of an input component
+ for which the suggestion
+ support is provided
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>
+ <property>"suggestionAction"</property>
+ </emphasis>
+ defines the method to get a collection of suggestion data on
+ request
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>
+ <property>"var"</property>
+ </emphasis>
+ defines a collection name that provides an access for the current
+ row while iterating through
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>To create the simplest variant on a page use the following
+ syntax:</para>
+ <programlisting role="XML"><![CDATA[...
+<h:inputText id="city" value="#{capitalsBean.capital}" />
+<rich:suggestionbox for="city" var="result"
suggestionAction="#{capitalsBean.autocomplete}">
+ <h:column>
+ <h:outputText value="#{result.name}" />
+ </h:column>
</rich:suggestionbox>
...
]]></programlisting>
- <para>Here is the <code>bean.autocomplete</code>
method that returns the
- collection to pop up:</para>
+ <para>
+ There is a managed bean:
+ </para>
+ <programlisting role="JAVA"><![CDATA[...
+public class SBbean {
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="JAVA"><![CDATA[public List
autocomplete(Object event) {
- String pref = event.toString();
- //Collecting some data that begins with "pref" letters
- ...
- return result;
-}
+ private ArrayList<Capital> capitals = new ArrayList<Capital>();
+ private ArrayList<String> capitalsNames = new ArrayList<String>();
+ private List<SelectItem> capitalsOptions = new ArrayList<SelectItem>();
+ private String capital = "";
+
+ public List<Capital> autocomplete(Object suggest) {
+ String pref = (String) suggest;
+ ArrayList<Capital> result = new ArrayList<Capital>();
+
+ Iterator<Capital> iterator = getCapitals().iterator();
+ while (iterator.hasNext()) {
+ Capital elem = ((Capital) iterator.next());
+ if ((elem.getName() != null && elem.getName().toLowerCase()
+ .indexOf(pref.toLowerCase()) == 0)
+ || "".equals(pref)) {
+ result.add(elem);
+ }
+ }
+ return result;
+ }
+
+ public SBbean() {
+ URL rulesUrl = getClass().getResource("capitals-rules.xml");
+ Digester digester = 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;
+ }
+}
]]></programlisting>
- </section>
- <section>
- <title>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="city"/></code>
+ .
+ </para>
+ <para>
+ Here is a result:
+ </para>
+ <figure>
+ <title>
+ <emphasis role="bold">
+ Simple
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox_simple.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="JAVA"><![CDATA[import
org.richfaces.component.html.HtmlSuggestionBox;
+ <para>
+ The
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ component could get any collection
+ and outputs it in a
+ popup in
+ several columns. The
+ <emphasis>
+ <property>"fetchValue"</property>
+ </emphasis>
+ 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.
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:inputText id="city" value="#{capitalsBean.capital}" />
+<rich:suggestionbox for="city" var="result"
fetchValue="#{result.state}"
+ suggestionAction="#{capitalsBean.autocomplete}">
+ <h:column>
+ <h:outputText value="#{result.name}" />
+ </h:column>
+ <h:column>
+ <h:outputText value="#{result.state}" />
+ </h:column>
+</rich:suggestionbox>
...
-HtmlSuggestionBox myList = new HtmlSuggestionBox();
-...
]]></programlisting>
- </section>
- <section>
- <title>Details of Usage</title>
- <para>As it is shown in the example above, the main component
attribute are:</para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>
-
<property>"for"</property>
- </emphasis>
- </para>
- <para>The attribute where there is an input
component which
- activation causes a suggestion
activation</para>
- </listitem>
- <listitem>
- <para>
- <emphasis>
-
<property>"suggestionAction"</property>
- </emphasis>
- </para>
- <para> is an accepting parameter of a
suggestionEvent type
- that returns as a result a collection
for
- rendering in a tool tip
window.</para>
- </listitem>
- <listitem>
- <para>
- <emphasis>
-
<property>"var"</property>
- </emphasis>
- </para>
- <para> a collection name that provides
access for inputting
- into a table in a popup</para>
- </listitem>
- </itemizedlist>
- <para>There are also two size attributes (<emphasis>
-
<property>"width"</property>
- </emphasis> and <emphasis>
-
<property>"height"</property>
- </emphasis>) that are obligatory for the suggestion
component. The
- attributes have initial Defaults but should be specified
manually in
- order to be changed.</para>
- <para>The <property>suggestionbox</property>
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 dataTable (in several
columns)</para>
- <programlisting role="XML"><![CDATA[...
-<rich:suggestionbox for="test"
suggestionAction="#{bean.autocomplete}" var="cit"
fetchValue="#{cit.text}">
- <h:column>
- <h:outputText value="#{cit.label}"/>
- </h:column>
- <h:column>
- <h:outputText value="#{cit.text}"/>
- </h:column>
+ <para>
+ In the example above if you choose any string input will receive the
+ corresponding value
+ from the second column containing
+ <code>#{result.state}</code>
+ .
+ </para>
+ <para>Here is a result:</para>
+ <figure>
+ <title>
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ with output in several columns
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox2.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ There is also one more important attribute named
+ <emphasis>
+ <property>"tokens"</property>
+ </emphasis>
+ 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.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:inputText id="city" value="#{capitalsBean.capital}" />
+<rich:suggestionbox for="city" var="result"
suggestionAction="#{capitalsBean.autocomplete}"
+ tokens=",">
+ <h:column>
+ <h:outputText value="#{result.name}" />
+ </h:column>
</rich:suggestionbox>
...
]]></programlisting>
- <para>It looks on a page in the following way:</para>
- <figure>
- <title><emphasis role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> with ToolTip
window</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/suggestionbox2.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>When some string is chosen input receives the
corresponding value from the
- second column containing
<code>#{cit.text}</code></para>
- <para>There is also one more important attribute named
<emphasis>
-
<property>"tokens"</property>
- </emphasis> 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.</para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
-<rich:suggestionbox for="test"
suggestionAction="#{bean.autocomplete}" var="cit"
selfRendered="true" tokens=",">
- <h:column>
- <h:outputText value="#{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="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ with chosen word
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox3.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>For
+ a multiple definition use either "
+ <code>,.;[]</code>
+ "
+ syntax as a value for
+ <emphasis>
+ <property>"tokens"</property>
+ </emphasis>
+ attribute or link a parameter to some bean
+ property that transmits
+ separators collection.
+ </para>
+ </section>
+ <section>
+ <title>JavaScript API</title>
+ <para>
+ There is such feature of the
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ component as
+ <property>object selection</property>
+ .
+ If you want to get the selected item as object on the client side
+ you should set the value of the
+ <emphasis>
+ <property> "usingSuggestObjects" </property>
+ </emphasis>
+ attribute
+ to "true".
+ After that you should specify
+ JavaScript method in the
+ <emphasis>
+ <property> "onobjectchange"</property>
+ </emphasis>
+ attribute and pass the
+ <code>suggestion</code>
+ object as a parameter:
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:inputText id="city" value="#{capitalsBean.capital}" />
+<rich:suggestionbox for="city" var="result"
suggestionAction="#{capitalsBean.autocomplete}"
+ onobjectchange="processObjects(suggestion)"
usingSuggestObjects="true">
+ <h:column>
+ <h:outputText value="#{result.name}" />
+ </h:column>
</rich:suggestionbox>
+<h:panelGroup>
+ <div id="state"></div>
+</h:panelGroup>
...
]]></programlisting>
- <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="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> with chosen word</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/suggestionbox3.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para>For a multiple definition use either
"<code>,.;</code> "
- syntax as a value for tokens or link a parameter to some
bean property
- transmitting separators collection.</para>
- <para>The component also encompasses <emphasis>
-
<property>"style"</property>
- </emphasis> attributes corresponding to dataTable
ones for a table
- appearing in popup (for additional information, read JSF
Reference)
- and custom attribute managing Ajax requests sending (for
additional
- information, see <ulink
-
url="http://www.jboss.org/community/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 more
its own attribute
- limiting requests (the <emphasis>
-
<property>"minChars"</property>
- </emphasis> attribute). The attribute defines
characters quantity
- inputted into a field after which Ajax requests 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="XML"><![CDATA[<script
type="text/javascript">
+function processObjects(suggestionBox) {
+ var items = suggestionBox.getSelectedItems();
+ var state;
+ if (items && items.length > 0) {
+ for ( var i = 0; i < items.length; i++) {
+ state = items[i].state;
+ }
+ document.getElementById('state').innerHTML = "State: "+state;
+ }else{
+ document.getElementById('state').innerHTML = '';
+ }
+}
+</script>
+]]></programlisting>
+ <para>
+ Here is a result:
+ </para>
+ <figure>
+ <title>
+ Usage of
+ <code>getSelectedItems()</code>
+ method
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionboxAPI.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section>
+ <title>Other attributes and facets</title>
+ <para>
+ In addition to attributes common for Ajax action components
+ and
+ limiting requests quantity and frequency,
+ the
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ has one more its own attribute
+ limiting requests: the
+ <emphasis>
+ <property>"minChars"</property>
+ </emphasis>
+ attribute. This attribute defines characters quantity
+ inputted into a
+ field after which Ajax requests are called to perform
+ suggestion.
+ </para>
- <para> There is possibility to define what be shown if the
autocomplete returns
- empty list. Attribute<emphasis>
- <property> "nothingLabel"
</property>
- </emphasis>or facet with the same name could be used
for it. </para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
-<rich:suggestionbox nothingLabel="Empty" for="test"
suggestionAction="#{bean.autocomplete}" var="cit">
- <h:column>
- <h:outputText value="#{cit.text}"/>
- </h:column>
+ <para>
+ There is possibility to define what is shown if the autocomplete
+ returns empty list. Attribute
+ <emphasis>
+ <property> "nothingLabel" </property>
+ </emphasis>
+ or facet with the same name could be used for this purpose.
+ </para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<rich:suggestionbox for="city" var="result"
suggestionAction="#{capitalsBean.autocomplete}"
+ nothingLabel="No cities found">
+ <h:column>
+ <h:outputText value="#{result.name}" />
+ </h:column>
</rich:suggestionbox>
...
]]></programlisting>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
-<rich:suggestionbox for="test"
suggestionAction="#{bean.autocomplete}" var="cit">
+ <para>Here is a result:</para>
+ <figure>
+ <title>
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ with empty list
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox4.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ You can also use facets for the further
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ customization:
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:inputText id="city" value="#{capitalsBean.capital}" />
+<rich:suggestionbox for="city"
var="result" suggestionAction="#{capitalsBean.autocomplete}">
<f:facet name="nothingLabel">
- <h:outputText value="Empty"/>
- </f:facet>
+ <h:outputText value="No cities found" />
+ </f:facet>
+ <f:facet name="header">
+ <h:outputText value="Select your city" />
+ </f:facet>
<h:column>
- <h:outputText value="#{cit.text}"/>
+ <h:outputText value="#{result.name}" />
</h:column>
</rich:suggestionbox>
...
]]></programlisting>
-
-
- <para>It looks on a page in the following way:</para>
-
- <figure>
- <title><emphasis role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> with empty list</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/suggestionbox4.png"/>
- </imageobject>
- </mediaobject>
- </figure>
- <para> There is such feature in <emphasis
role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> component as object selection. If you
want that selected
- item has been represented as object, you could set to
"true" the value
- for <emphasis>
- <property>
"usingSuggestObjects"
- </property>
- </emphasis> attribute, "false" value means
that selected item
- represents as string. </para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="XML"><![CDATA[...
-<rich:suggestionbox for="test"
suggestionAction="#{bean.autocomplete}" var="cit"
usingSuggestObjects="true">
- <h:column>
- <h:outputText value="#{cit.text}"/>
- </h:column>
-</rich:suggestionbox>
-...
-]]></programlisting>
- <para> Information about the <emphasis>
-
<property>"process"</property>
- </emphasis> attribute usage you can findin the
- <link linkend="process"> "Decide
what to process" </link> guide section. </para>
- <para>In RichFaces Wiki article about
- <ulink
-
url="http://wiki.jboss.org/wiki/RichFacesSuggestionGettingAdditional...
- >Additional Properties </ulink> you can
find example of getting additional
- properties. </para>
- </section>
- <section>
- <title>JavaScript API</title>
- <table>
- <title>JavaScript API</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Function</entry>
-
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
-
<entry>callSuggestion()</entry>
- <entry>Calls the suggestion. If
the
- "ignoreMinChars"
- value is
- "true" then
- the number of symbols to send
- a query is no longer actual
- for callSuggestion()</entry>
- </row>
-
- <row>
-
<entry>getSelectedItems()</entry>
- <entry>Returns the array of
- objects</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
+ <para>
+ Here is a result:
+ </para>
+ <figure>
+ <title>
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ facets
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox5.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
+ <para>
+ Information about the
+ <emphasis>
+ <property>"process"</property>
+ </emphasis>
+ attribute usage you can findin the
+ <link linkend="process"> "Decide what to process"
</link>
+ guide section.
+ </para>
+ <para>
+ In RichFaces Wiki article about
+ <ulink
+
url="http://wiki.jboss.org/wiki/RichFacesSuggestionGettingAdditional...
+ Additional Properties </ulink>
+ you can find example of getting additional
+ properties.
+ </para>
+ </section>
<section>
- <title>Facets</title>
- <table>
- <title>Facets</title>
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Facet name</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>nothingLabel</entry>
- <entry>Redefines the content item if the autocomplete returns empty list.
Related attribute is "nothingLabel"</entry>
- </row>
- <row>
- <entry>popup</entry>
- <entry>Redefines the content for the popup list of the
suggestion</entry>
- </row>
- <row>
- <entry>header</entry>
- <entry>Defines the header content</entry>
- </row>
- <row>
- <entry>footer</entry>
- <entry>Defines the footer content</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Look-and-Feel Customization</title>
+ <title>Custom style classes redefinition</title>
+ <para>
+ In order to redefine styles for all
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ components on a page using CSS, it's enough to
+ create classes
+ with the same names (possible classes could be found in
+ the tables
+ <link linkend="suggBoxC"> above</link>
+ ) and define
+ necessary properties in them.
+ </para>
- <para>For skinnability implementation, the components use a
<emphasis>
- <property>style class redefinition
method.</property>
- </emphasis> Default style classes are mapped on
<emphasis>
- <property>skin
parameters.</property>
- </emphasis></para>
-
- <para>There are two ways to redefine the appearance of all
<emphasis role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> components at once:</para>
-
- <itemizedlist>
- <listitem>
- <para>Redefine the corresponding skin
parameters</para>
- </listitem>
-
- <listitem>
- <para>Add to your style sheets
<emphasis>
- <property>style
classes</property>
- </emphasis> used by a
<emphasis role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis>
component</para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title> Skin Parameters Redefinition</title>
-
- <table>
- <title>General skin parameters redefinition for popup
list</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Parameters for popup
list</entry>
-
- <entry>CSS
properties</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
-
<entry>additionalBackgroundColor</entry>
-
-
<entry>background-color</entry>
- </row>
-
- <row>
-
<entry>panelBorderColor</entry>
-
-
<entry>border-color</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Skin parameters redefinition for shadow
element of the list</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Parameters for shadow
element of
- the list</entry>
-
- <entry>CSS
properties</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
-
<entry>shadowBackgroundColor</entry>
-
-
<entry>background-color</entry>
- </row>
-
- <row>
-
<entry>shadowBackgroundColor</entry>
-
-
<entry>border-color</entry>
- </row>
-
- <row>
-
<entry>shadowOpacity</entry>
-
- <entry>opacity</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Skin parameters redefinition for popup table
rows</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Parameters for popup table
rows</entry>
-
- <entry>CSS
properties</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
-
<entry>generalSizeFont</entry>
-
- <entry>font-size</entry>
- </row>
-
- <row>
-
<entry>generalTextColor</entry>
-
- <entry>color</entry>
- </row>
-
- <row>
-
<entry>generalFamilyFont</entry>
-
- <entry>font-family</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Skin parameters redefinition for selected
row</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Parameters for selected
row</entry>
-
- <entry>CSS
properties</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
-
<entry>headerBackgroundColor</entry>
-
-
<entry>background-color</entry>
- </row>
-
- <row>
-
<entry>generalSizeFont</entry>
-
- <entry>font-size</entry>
- </row>
-
- <row>
-
<entry>generalFamilyFont</entry>
-
- <entry>font-family</entry>
- </row>
- <row>
-
<entry>headerTextColor</entry>
-
- <entry>color</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Definition of Custom Style Classes</title>
-
- <figure>
- <title>Classes names</title>
-
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/suggestionbox_cn.png"/>
- </imageobject>
- </mediaobject>
- </figure>
-
- <para>On the screenshot, there are classes names defining
specified elements.</para>
-
- <table id="suggBoxC">
- <title>Classes names that define a
suggestionbox</title>
-
- <tgroup cols="2">
- <thead>
- <row>
- <entry>Class name</entry>
-
- <entry>Description</entry>
- </row>
- </thead>
-
- <tbody>
- <row>
-
<entry>rich-sb-common-container</entry>
-
- <entry>Defines styles for a
wrapper
- <div> element of
- a suggestion container</entry>
- </row>
-
- <row>
-
<entry>rich-sb-ext-decor-1</entry>
-
- <entry>Defines styles for the
first
- wrapper <div>
- element of a suggestion box
- exterior</entry>
- </row>
-
- <row>
-
<entry>rich-sb-ext-decor-2</entry>
-
- <entry>Defines styles for the
second
- wrapper <div>
- element of a suggestion box
- exterior</entry>
- </row>
-
- <row>
-
<entry>rich-sb-ext-decor-3</entry>
-
- <entry>Defines styles for the
third
- wrapper <div>
- element of a suggestion box
- exterior</entry>
- </row>
-
- <row>
-
<entry>rich-sb-overflow</entry>
-
- <entry>Defines styles for a
wrapper
- <div>
- element</entry>
- </row>
-
- <row>
-
<entry>rich-sb-int-decor-table</entry>
-
- <entry>Defines styles for a
suggestion
- box table</entry>
- </row>
-
- <row>
- <entry>rich-sb-int</entry>
-
- <entry>Defines the styles for a
- suggestion box table rows
- (tr)</entry>
- </row>
-
- <row>
-
<entry>rich-sb-cell-padding</entry>
-
- <entry>Defines the styles for
suggestion
- box table cells (td)</entry>
- </row>
-
- <row>
-
<entry>rich-sb-int-sel</entry>
-
- <entry>Defines styles for a
selected
- row</entry>
- </row>
-
- <row>
-
<entry>rich-sb-shadow</entry>
-
- <entry>Defines styles for a
suggestion
- boxshadow</entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>In order to redefine styles for all <emphasis
role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> components on a page using CSS,
it's enough to
- create classes with the same names (possible classes could
be found in
- the tables <link linkend="suggBoxC">
above</link>) and define
- necessary properties in them. </para>
-
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="CSS"><![CDATA[...
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[...
.rich-sb-int{
font-weight:bold;
}
...]]></programlisting>
- <para>This is a result:</para>
+ <para>This is a result:</para>
- <figure>
- <title>Redefinition styles with predefined
classes</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/suggestionbox_pc.png"/>
- </imageobject>
- </mediaobject>
- </figure>
+ <figure>
+ <title>Redefinition styles with predefined classes</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox_pc.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>In the example the font weight for rows was
changed.</para>
+ <para>In the example the font weight for rows was changed.</para>
- <para>Also it's possible to change styles of
particular <emphasis
- role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> component. In this case you should create
own style
- classes and use them in corresponding <emphasis
role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis>
- <emphasis>
- <property>styleClass</property>
- </emphasis> attributes. An example is placed
below:</para>
+ <para>Also
+ it's possible to change styles of particular
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ component. In this case you should create own style
+ classes and use
+ them in corresponding
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ <emphasis>
+ <property>styleClass</property>
+ </emphasis>
+ attributes. An example is placed below:
+ </para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting role="CSS"><![CDATA[...
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="CSS"><![CDATA[...
.myClass{
background-color:#f0ddcd;
}
...]]></programlisting>
- <para>The <emphasis>
-
<property>"selectedClass"</property>
- </emphasis> attribute for <emphasis
role="bold">
-
<property><rich:suggestionbox></property>
- </emphasis> is defined as it's shown in the
example below:</para>
+ <para>
+ The
+ <emphasis>
+ <property>"selectedClass"</property>
+ </emphasis>
+ attribute for
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ is defined as it's shown in the example below:
+ </para>
- <para>
- <emphasis
role="bold">Example:</emphasis>
- </para>
- <programlisting
role="XML"><![CDATA[<rich:suggestionbox ...
selectedClass="myClass"/>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[<rich:suggestionbox ...
selectedClass="myClass"/>
]]></programlisting>
- <para>This is a result:</para>
+ <para>This is a result:</para>
- <figure>
- <title>Redefinition styles with own classes and
<emphasis>
-
<property>styleClass</property>
- </emphasis> attributes</title>
- <mediaobject>
- <imageobject>
- <imagedata
fileref="images/suggestionbox_oc.png"/>
- </imageobject>
- </mediaobject>
- </figure>
+ <figure>
+ <title>
+ Redefinition styles with own classes and
+ <emphasis>
+ <property>styleClass</property>
+ </emphasis>
+ attributes
+ </title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox_oc.png" />
+ </imageobject>
+ </mediaobject>
+ </figure>
- <para>As it could be seen on the picture above,background color
for selected
- item was changed.</para>
+ <para>As it could be seen on the picture above,background color for
+ selected
+ item was changed.</para>
+ </section>
+ </section>
+ <section>
+ <sectioninfo>
+ <keywordset>
+ <keyword>rich:suggestionbox</keyword>
+ </keywordset>
+ </sectioninfo>
+ <title>Reference Data</title>
+ <para>
+ <ulink
+
url="http://www.jboss.org/file-access/default/members/jbossrichfaces...
+ Table of <rich:suggestionbox> 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.SuggestionBox</entry>
+ </row>
+ <row>
+ <entry>component-class</entry>
+ <entry>org.richfaces.component.html.HtmlSuggestionBox</entry>
+ </row>
+ <row>
+ <entry>component-family</entry>
+ <entry>org.richfaces.SuggestionBox</entry>
+ </row>
+ <row>
+ <entry>renderer-type</entry>
+ <entry>org.richfaces.SuggestionBoxRenderer</entry>
+ </row>
+ <row>
+ <entry>tag-class</entry>
+ <entry>org.richfaces.taglib.SuggestionBoxTag</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
+ <title>Facets</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Facet name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>nothingLabel</entry>
+ <entry>Redefines the content item if the autocomplete returns
+ empty
+ list. Related attribute is "nothingLabel"</entry>
+ </row>
+ <row>
+ <entry>popup</entry>
+ <entry>Redefines the content for the popup list of the suggestion
+ </entry>
+ </row>
+ <row>
+ <entry>header</entry>
+ <entry>Defines the header content</entry>
+ </row>
+ <row>
+ <entry>footer</entry>
+ <entry>Defines the footer content</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
+ <title>JavaScript API</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Function</entry>
- </section>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>callSuggestion()</entry>
+ <entry>Calls the suggestion. If the
+ "ignoreMinChars"
+ value is
+ "true" then
+ the number of symbols to send
+ a query
+ is no longer actual
+ for callSuggestion()</entry>
+ </row>
- <section>
- <title>Relevant Resources Links</title>
- <para>Vizit <ulink
url="http://livedemo.exadel.com/richfaces-demo/richfaces/suggestionB...
- page at RichFaces Livedemo for examples of component usage and sources.
- </para>
- <para>RichFaces cookbook at JBoss Portal includes some articles that cover
different aspects of working with
- <emphasis
role="bold"><property><rich:suggestionbox></property></emphasis>:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- "<ulink
url="http://www.jboss.org/community/docs/DOC-11851">Creating suggestion box
dynamically</ulink>";
- </para>
- </listitem>
- <listitem>
- <para>
- "<ulink
url="http://www.jboss.org/community/docs/DOC-11865">Getting additional
properties from <rich:suggectionbox></ulink>".
- </para>
- </listitem>
- </itemizedlist>
-
-
- </section>
+ <row>
+ <entry>getSelectedItems()</entry>
+ <entry>Returns the array of
+ objects</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table id="suggBoxC">
+ <title>Classes names with the corresponding skin parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Class name</entry>
+ <entry>Description</entry>
+ <entry>Skin Parameters</entry>
+ <entry>CSS properties</entry>
+
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry morerows="2">.rich-sb-int</entry>
+ <entry morerows="2">Defines the styles for a
+ suggestion box table
+ rows
+ <tr></entry>
+ <entry>generalSizeFont</entry>
+ <entry>font-size</entry>
+ </row>
+ <row>
+ <entry>generalFamilyFont</entry>
+ <entry>font-family</entry>
+ </row>
+ <row>
+ <entry>generalTextColor</entry>
+ <entry>color</entry>
+ </row>
+
+ <row>
+ <entry morerows="3">.rich-sb-int-sel</entry>
+ <entry morerows="3">Defines styles for a selected
+ row</entry>
+ <entry>headerBackgroundColor</entry>
+ <entry>background-color</entry>
+ </row>
+ <row>
+ <entry>generalSizeFont</entry>
+ <entry>font-size</entry>
+ </row>
+ <row>
+ <entry>generalFamilyFont</entry>
+ <entry>font-family</entry>
+ </row>
+ <row>
+ <entry>headerTextColor</entry>
+ <entry>color</entry>
+ </row>
+ <row>
+ <entry morerows="1">.rich-sb-ext-decor-2</entry>
+ <entry morerows="1">Defines styles for the second
+ wrapper
+ <div>
+ element of
+ a suggestion box
+ exterior</entry>
+ <entry>panelBorderColor</entry>
+ <entry>border-color</entry>
+ </row>
+ <row>
+ <entry>additionalBackgroundColor</entry>
+ <entry>background-color</entry>
+ </row>
+ <row>
+ <entry morerows="2">.rich-sb-shadow</entry>
+ <entry morerows="2">Defines styles for a suggestion
+ boxshadow
+ </entry>
+ <entry>shadowBackgroundColor</entry>
+ <entry>background-color</entry>
+ </row>
+ <row>
+ <entry>shadowBackgroundColor</entry>
+ <entry>border-color</entry>
+ </row>
+ <row>
+ <entry>shadowOpacity</entry>
+ <entry>opacity</entry>
+ </row>
+
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <section>
+ <title>Relevant Resources Links</title>
+ <para>
+ Vizit
+ <ulink
+
url="http://livedemo.exadel.com/richfaces-demo/richfaces/suggestionB...
role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis></ulink>
+ page at RichFaces Livedemo for examples of component usage and
+ sources.
+ </para>
+ <para>
+ RichFaces cookbook at JBoss Portal includes some articles that cover
+ different aspects of working with
+ <emphasis role="bold">
+ <property><rich:suggestionbox></property>
+ </emphasis>
+ :
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ "
+ <ulink
url="http://www.jboss.org/community/docs/DOC-11851">Creating
suggestion box dynamically</ulink>
+ ";
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ "
+ <ulink
url="http://www.jboss.org/community/docs/DOC-11865">Getting
additional properties from
+ <rich:suggectionbox></ulink>
+ ".
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
</section>