<?xml version='1.0' encoding='UTF-8'?>
<section>
          <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>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>
    </rich:suggestionbox>
...
]]></programlisting>
                    <para>Here is the <code>bean.autocomplete</code> method that returns the
                              collection to pop up:</para>

                    <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;
    }
]]></programlisting>
          </section>
          <section>
                    <title>Creating the Component Dynamically Using Java</title>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="JAVA"><![CDATA[import org.richfaces.component.html.HtmlSuggestionBox;
...
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>&quot;for&quot;</property>
                                                  </emphasis>
                                        </para>
                                        <para>The attribute where there is an input component which
                                                  activation causes a suggestion activation</para>
                              </listitem>
                              <listitem>
                                        <para>
                                                  <emphasis>
                                                  <property>&quot;suggestionAction&quot;</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>&quot;var&quot;</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>&quot;width&quot;</property>
                              </emphasis> and <emphasis>
                                        <property>&quot;height&quot;</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>
    </rich:suggestionbox>
...
]]></programlisting>
                    <para>It looks on a page in the following way:</para>
                    <figure>
                              <title><emphasis role="bold">
                                                  <property>&lt;rich:suggestionbox&gt;</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>&quot;tokens&quot;</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>
    </rich:suggestionbox>
...
]]></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>&lt;rich:suggestionbox&gt;</property>
                                        </emphasis> with chosen word</title>
                              <mediaobject>
                                        <imageobject>
                                                  <imagedata fileref="images/suggestionbox3.png"/>
                                        </imageobject>
                              </mediaobject>
                    </figure>
                    <para>For a multiple definition use either &quot;<code>,.;</code> &quot;
                              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>&quot;style&quot;</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/projects/jbossajax4jsf">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>&quot;minChars&quot;</property>
                              </emphasis> attribute). The 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> &quot;nothingLabel&quot; </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>
    </rich:suggestionbox>
...
]]></programlisting>
                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[...
<rich:suggestionbox for="test" suggestionAction="#{bean.autocomplete}" var="cit"> 
	<f:facet name="nothingLabel">
		<h:outputText value="Empty"/>
	</f:facet>		
	<h:column>
		<h:outputText value="#{cit.text}"/>
	</h:column>
</rich:suggestionbox>
...
]]></programlisting>


                    <para>It looks on a page in the following way:</para>

                    <figure>
                              <title><emphasis role="bold">
                                                  <property>&lt;rich:suggestionbox&gt;</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>&lt;rich:suggestionbox&gt;</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> &quot;usingSuggestObjects&quot;
                                        </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>&quot;process&quot;</property>
                    </emphasis> attribute usage you can findin the 
                              <link linkend="process"> &quot;Decide what to process&quot; </link> guide section. </para>
                    <para>In RichFaces Wiki article about
                              <ulink
                                        url="http://wiki.jboss.org/wiki/RichFacesSuggestionGettingAdditionalProperties"
                                        >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
                                                  &quot;ignoreMinChars&quot;
                                                  value is
                                                  &quot;true&quot; 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>
		
		<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 &quot;nothingLabel&quot;</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>

                    <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>&lt;rich:suggestionbox&gt;</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>&lt;rich:suggestionbox&gt;</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
                                                  &lt;div&gt; element of
                                                  a suggestion container</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sb-ext-decor-1</entry>

                                                  <entry>Defines styles for the first
                                                  wrapper &lt;div&gt;
                                                  element of a suggestion box
                                                  exterior</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sb-ext-decor-2</entry>

                                                  <entry>Defines styles for the second
                                                  wrapper &lt;div&gt;
                                                  element of a suggestion box
                                                  exterior</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sb-ext-decor-3</entry>

                                                  <entry>Defines styles for the third
                                                  wrapper &lt;div&gt;
                                                  element of a suggestion box
                                                  exterior</entry>
                                                  </row>

                                                  <row>
                                                  <entry>rich-sb-overflow</entry>

                                                  <entry>Defines styles for a wrapper
                                                  &lt;div&gt;
                                                  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>&lt;rich:suggestionbox&gt;</property>
                              </emphasis> components on a page using CSS, it&apos;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[...
.rich-sb-int{
        font-weight:bold;
}
...]]></programlisting>

                    <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>

                    <para>In the example the font weight for rows was changed.</para>

                    <para>Also it&apos;s possible to change styles of particular <emphasis
                                        role="bold">
                                        <property>&lt;rich:suggestionbox&gt;</property>
                              </emphasis> component. In this case you should create own style
                              classes and use them in corresponding <emphasis role="bold">
                                        <property>&lt;rich:suggestionbox&gt;</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[...
.myClass{
        background-color:#f0ddcd;
}
...]]></programlisting>
                    <para>The <emphasis>
                                        <property>&quot;selectedClass&quot;</property>
                              </emphasis> attribute for <emphasis role="bold">
                                        <property>&lt;rich:suggestionbox&gt;</property>
                              </emphasis> is defined as it&apos;s shown in the example below:</para>

                    <para>
                              <emphasis role="bold">Example:</emphasis>
                    </para>
                    <programlisting role="XML"><![CDATA[<rich:suggestionbox ... selectedClass="myClass"/>
]]></programlisting>

                    <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>

                    <para>As it could be seen on the picture above,background color for selected
                              item was changed.</para>



          </section>



          <section>
                    <title>Relevant Resources Links</title>
                    <para>Vizit <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/suggestionBox.jsf?c=suggestionBox">SuggestionBox</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>&lt;rich:suggestionbox&gt;</property></emphasis>:
					</para>
					<itemizedlist>
					    <listitem>
						    <para>
							    &quot;<ulink url="http://www.jboss.org/community/docs/DOC-11851">Creating suggestion box dynamically</ulink>&quot;;
							</para>
						</listitem>
                        <listitem>
                            <para>
							    &quot;<ulink url="http://www.jboss.org/community/docs/DOC-11865">Getting additional properties from &lt;rich:suggectionbox&gt;</ulink>&quot;.
                            </para>
						</listitem>                        
                    </itemizedlist>
					
                    
          </section>

</section>
