<?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>Here is a simple example as it could be used on a page: </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 <emphasis>
                <property>bean.autocomplete</property>
            </emphasis> 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>
                <emphasis>
                    <property>&quot;for&quot;</property>
                </emphasis>
                <para>The attribute where there is an input component which activation causes a
                    suggestion activation</para>
            </listitem>
            <listitem>
                <emphasis>
                    <property>&quot;suggestionAction&quot;</property>
                </emphasis>
                <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>
                <emphasis>
                    <property>&quot;var&quot;</property>
                </emphasis>
                <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>SuggestionBox with tooltip window</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/suggestionbox2.gif"/>
                </imageobject>
            </mediaobject>
        </figure>
        <para>When some string is chosen input receives the corresponding value from the second
            column containing <property>#{cit.text}</property></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:suggestiobox 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>SuggestionBox with chosen word</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/suggestionbox3.gif"/>
                </imageobject>
            </mediaobject>
        </figure>
        <para>For a multiple definition use either &quot;,.; &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;layout&quot;</property>
            </emphasis> and <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>

    </section>

	<section>
	<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:suggestiobox 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:suggestiobox for="test" suggestionAction="#{bean.autocomplete}" var="cit"> 
	<facet name="nothingLabel">
		<h:outputText value="Empty"/>
	</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>SuggestionBox with empty list</title>
            <mediaobject>
                <imageobject>
                    <imagedata fileref="images/suggestionbox5.gif"/>
                </imageobject>
            </mediaobject>
        </figure>
</section>
    
    <section>
        <title>Look-and-Feel Customization</title>
        
        <para>For skinnability implementation, the components use a style class redefinition method.
            Default style classes are mapped on skin parameters.</para>
        
        <para>There are two ways to redefine the appearance of all suggestionbox at once:</para>
        
        <itemizedlist>
            <listitem>
                <para>Redefine the corresponding skin parameters</para>
            </listitem>
            
            <listitem>
                <para>Add to your style sheets style classes used by a suggestionbox</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/suggestionbox4.gif"/>
                </imageobject>
            </mediaobject>
        </figure>
        
        <para>On the screenshot, there are classes names defining specified elements.</para>
        
        <table>
            <title>Component skin class</title>
            
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Class name</entry>
                        
                        <entry>Description</entry>
                    </row>
                </thead>
                
                <tbody>
                    <row>
                        <entry>rich-sb-overflow</entry>
                        
                        <entry>Defines the styles of outer div</entry>
                    </row>
                    
                    <row>
                        <entry>rich-sb-int-decor-table</entry>
                        
                        <entry>Defines the styles for suggestion box table</entry>
                    </row>
                    
                    <row>
                        <entry>rich-sb-int</entry>
                        
                        <entry>Defines the styles for 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-shadow</entry>
                        
                        <entry>Defines the styles for shadow</entry>
                    </row>
                    
                    <row>
                        <entry>rich-sb-int-sel</entry>
                        
                        <entry>Defines the styles for selected row</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        
        <para>In order to redefine the style for all saggestionbox components on a page using CSS, it's enough to
            create classes with the same names and define the necessary properties in them.</para>
        
        <para>To change the style of particular suggestionbox components define your own style classes in the corresponding suggestionbox attributes. </para>
    </section>

	
	
    <section>
        <title>Relevant Resources Links</title>
        <para>
            <ulink
                url="http://livedemo.exadel.com/richfaces-demo/richfaces/suggestionBox.jsf?c=suggestionBox"
                >Here</ulink> you can see the example of <emphasis role="bold"
                ><property>&lt;rich:suggestionBox&gt;</property></emphasis> usage and sources for the given
            example. </para>
    </section>

</section>
