<?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:suggestionbBox>
...
]]></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;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>

   
	<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 find <link linkend="process">here</link>.
	    </para>  
		<para>
			<ulink url="http://wiki.jboss.org/wiki/RichFacesSuggestionGettingAdditionalProperties">Here </ulink>
			you can find example of getting additional properties.
		</para>
</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>
        	Additional information on how to build
        	<emphasis role="bold">
        		<property>&lt;rich:HtmlSuggestionBox&gt;</property>
        	</emphasis>
        	dynamically you can read
        	<ulink
        		url="http://wiki.jboss.org/wiki/RichFacesCookBookCreatingSuggestionBoxDynamically">
        		here
        	</ulink>
        	.
        </para>
        <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>
