[richfaces-svn-commits] JBoss Rich Faces SVN: r4785 - trunk/docs/userguide/en/src/main/docbook/included.
richfaces-svn-commits at lists.jboss.org
richfaces-svn-commits at lists.jboss.org
Wed Dec 12 11:17:21 EST 2007
Author: vkorluzhenko
Date: 2007-12-12 11:17:21 -0500 (Wed, 12 Dec 2007)
New Revision: 4785
Added:
trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml
trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.xml
trunk/docs/userguide/en/src/main/docbook/included/toolTip.desc.xml
trunk/docs/userguide/en/src/main/docbook/included/toolTip.xml
Log:
http://jira.jboss.com/jira/browse/RF-1614 - fixed file names.
Added: trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml (rev 0)
+++ trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.desc.xml 2007-12-12 16:17:21 UTC (rev 4785)
@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+<sectioninfo>
+<keywordset>
+<keyword>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>SuggestionBox component</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/suggestionbox1.gif"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section>
+ <title>Key Features</title>
+ <itemizedlist>
+ <listitem>Fully skinnable component</listitem>
+ <listitem>Adds <emphasis><property>"onkeypress"</property></emphasis> suggestions capabilities to any input text component</listitem>
+ <listitem>Performs suggestion via Ajax requests without any line of JavaScript code written
+ by you</listitem>
+ <listitem>Possible to render table as a popup suggestion</listitem>
+ <listitem>Can be pointed to any Ajax request status indicator of the page</listitem>
+ <listitem>Easily customizable size of suggestion popup</listitem>
+ <listitem>Setting rules that appear between cells within a table of popup values</listitem>
+ <listitem><emphasis
+
+><property>"Event queue"</property></emphasis> and <emphasis
+
+><property>"request delay"</property></emphasis> attributes present to divide
+ frequently requests</listitem>
+ <listitem>Managing area of components submitted on Ajax request</listitem>
+ <listitem>Flexible list of components to update after Ajax request managed by attributes</listitem>
+ <listitem>Setting restriction to Ajax request generation</listitem>
+ <listitem>Easily setting action to collect suggestion data</listitem>
+ <listitem>Keyboard navigation support</listitem>
+ </itemizedlist>
+ </section>
+</section>
\ No newline at end of file
Added: trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.xml (rev 0)
+++ trunk/docs/userguide/en/src/main/docbook/included/suggestionbox.xml 2007-12-12 16:17:21 UTC (rev 4785)
@@ -0,0 +1,522 @@
+<?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>"for"</property>
+ </emphasis>
+ <para>The attribute where there is an input component which activation causes a
+ suggestion activation</para>
+ </listitem>
+ <listitem>
+ <emphasis>
+ <property>"suggestionAction"</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>"var"</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>"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>
+ </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>"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: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 ",.; " 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>"layout"</property>
+ </emphasis> and <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/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>"minChars"</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> "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: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 <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/suggestionbox4.gif"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+
+ <para>On the screenshot, there are classes names defining specified elements.</para>
+
+ <table>
+ <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 and define necessary properties in them.</para>
+
+ <para>To change styles of particular <emphasis role="bold">
+ <property><rich:suggestionBox></property>
+ </emphasis> components, define your own style classes in the corresponding <emphasis
+ role="bold">
+ <property><rich:suggestionBox></property>
+ </emphasis>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><rich:suggestionBox></property></emphasis> usage and sources for the given
+ example. </para>
+ </section>
+
+</section>
Added: trunk/docs/userguide/en/src/main/docbook/included/toolTip.desc.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/toolTip.desc.xml (rev 0)
+++ trunk/docs/userguide/en/src/main/docbook/included/toolTip.desc.xml 2007-12-12 16:17:21 UTC (rev 4785)
@@ -0,0 +1,29 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<section>
+<sectioninfo>
+<keywordset>
+<keyword>tooltip</keyword>
+</keywordset>
+</sectioninfo>
+<section>
+<title>Description</title>
+ <para>The component used for creation non-modal popup that activated on some event and display some information.
+ </para>
+ <figure>
+ <title>Tooltip component</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/tooltip1.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+ </section>
+ <section>
+ <title>Key Features</title>
+ <itemizedlist>
+ <listitem>Highly customizable look and feel </listitem>
+ <listitem>Different ways of data loading to tooltip</listitem>
+ <listitem>Disablement support</listitem>
+ </itemizedlist>
+</section>
+</section>
\ No newline at end of file
Added: trunk/docs/userguide/en/src/main/docbook/included/toolTip.xml
===================================================================
--- trunk/docs/userguide/en/src/main/docbook/included/toolTip.xml (rev 0)
+++ trunk/docs/userguide/en/src/main/docbook/included/toolTip.xml 2007-12-12 16:17:21 UTC (rev 4785)
@@ -0,0 +1,368 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<section>
+<sectioninfo>
+<keywordset>
+<keyword>tooltip</keyword>
+<keyword>rich:tooltip</keyword>
+<keyword>HtmlTooltip</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.component.ToolTip</entry>
+ </row>
+ <row>
+ <entry>component-class</entry>
+ <entry>org.richfaces.component.html.HtmlToolTip</entry>
+ </row>
+ <row>
+ <entry>component-family</entry>
+ <entry>org.richfaces.component.ToolTip</entry>
+ </row>
+ <row>
+ <entry>renderer-type</entry>
+ <entry>org.richfaces.renderkit.html.ToolTipRenderer</entry>
+ </row>
+ <row>
+ <entry>tag-class</entry>
+ <entry>org.richfaces.taglib.HtmlToolTipTag</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <section>
+ <title>Creating the Component with a Page Tag</title>
+ <para>To create the simplest variant of <property>tooltip</property> on a page, use the following syntax:</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:commandButton value="Button">
+ <rich:tooltip value="Tooltip content"/>
+</h:commandButton>
+...
+]]></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.HtmlToolTip;
+...
+HtmlToolTip myToolTip = new HtmlToolTip();
+...
+]]></programlisting>
+</section>
+
+<section>
+<title>Details of Usage</title>
+<para>
+<property>Tooltip</property> main area is a simple rectangle area with any information inside. The content may be defined via
+"value" attribute as text or via any nested content. When both are defined, the value is displayed as text and nested content
+after the text. <property>Tooltip</property> stretches if the content more than the <property>tooltip</property> sizes.
+</para>
+<para>
+There is possibility to define a facet with the name "defaultContent". This facet provides the default content to
+display while the main content is loaded to a page in an Ajax mode. Thus when <property>tooltip</property> called in an Ajax mode, it
+appears with the content defined in the facet and when loading is completed, the content is changed to a loaded one.
+</para>
+<para>
+ Here is an example:
+</para>
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<h:commandLink value="Simple Link">
+ <rich:toolTip followMouse="true" direction="top-right" mode="ajax" value="#{bean.toolTipContent}" horizontalOffset="5"
+ verticalOffset="5" layout="block">
+ <f:facet name="defaultContent">
+ <f:verbatim>DEFAULT TOOLTIP CONTENT</f:verbatim>
+ </f:facet>
+ </rich:toolTip>
+</h:commandLink>
+...
+]]></programlisting>
+
+<para>
+This is the result:
+</para>
+ <figure>
+ <title>Tooltip component with default content</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/tooltip2.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+<para>
+And after <property>tooltip</property> loaded it will be changed to next one:
+</para>
+ <figure>
+ <title>Tooltip component with loaded content</title>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/tooltip3.png"/>
+ </imageobject>
+ </mediaobject>
+ </figure>
+<para>
+By default, <property>tooltip</property> appears smart positioned. But as you can see from the previous example, you
+can define an appearance direction via the corresponding attribute "direction". And also it's possible to define vertical and horizontal
+offsets relatively to a mouse position.
+</para>
+<para>
+<property>Tooltip</property> appears attached to the corner dependent on the <emphasis><property>"direction"</property></emphasis> attribute. By default it is positioned bottom-right.
+<property>Tooltip</property> activation occurs after a defined event (default=mouseover) on the parent component takes into consideration
+the "delay" attribute (default=0) or after calling JS API function doShow(). <property>Tooltip</property> deactivation occurs after mouseout event on the parent component (excepting the situation when the mouse is hovered onto the <property>tooltip</property> itself) or after calling JS API function doHide().
+</para>
+
+<note>
+<title>Note:</title>
+It is recommended to define parent component "id" for correction of <property>tooltip</property> work.
+</note>
+
+ <para>The attribute <emphasis><property>"for"</property></emphasis> is used for defining the <emphasis><property>"id"</property></emphasis> of an element a tooltip should be attached to. Look at the example:
+</para>
+
+ <para>
+ <emphasis role="bold">Example:</emphasis>
+ </para>
+ <programlisting role="XML"><![CDATA[...
+<div id="elementId">
+ <rich:toolTip for="elementId">Using a toolTip<rich:toolTip>
+ <p>The first simple example<p>
+</div>
+...
+<div id="elementId">
+ <p>The second simple example<p>
+</div>
+<rich:toolTip for="elementId">Using a toolTip<rich:toolTip>
+...
+]]></programlisting>
+
+ <para>Here, the attribute <emphasis><property>"for"</property></emphasis> of a <emphasis role="bold">
+ <property><rich:tooltip></property>
+ </emphasis> component is required. Whithout it an example doesn’t work because HTML elements aren't presented in component tree built by facelets.
+ </para>
+
+<para>
+The <emphasis><property>"mode"</property></emphasis> attribute is provided you to control the way of data loading to <property>tooltip</property>. It has following values:
+ <itemizedlist>
+ <listitem>Client</listitem>
+ <listitem>Ajax</listitem>
+ </itemizedlist>
+</para>
+<para>
+In a client mode, <property>tooltip</property> content is rendered once on the server and could be reRendered only via external submit.
+In an Ajax mode, <property>tooltip</property> content is requested from server every activation.
+</para>
+<para>
+Special JS API is provided to control the component behaviour:
+ <itemizedlist>
+ <listitem> - </listitem>
+ <listitem> - </listitem>
+ <listitem> - </listitem>
+ <listitem> - </listitem>
+ </itemizedlist>
+</para>
+<para>
+Disabled <property>tooltip</property> is rendered to a page as usual but JS that responds for its activation is
+disabled until doEnable() is called.
+</para>
+<para>
+Moreover, to add some JavaScript effects, client events defined on it are used:
+</para>
+<para>
+ Standart:
+ <itemizedlist>
+ <listitem>onclick</listitem>
+ <listitem>ondblclick</listitem>
+ <listitem>onmouseout</listitem>
+ <listitem>onmousemove</listitem>
+ <listitem>onmouseover</listitem>
+ </itemizedlist>
+</para>
+<para>
+ Special:
+ <itemizedlist>
+ <listitem>onshow - Called after the tooltip is called (some element hovered) but before its request
+ </listitem>
+ <listitem>oncomplete - Called just after the tooltip is shown
+ </listitem>
+ <listitem>onhide - Called after the tooltip is hidden
+ </listitem>
+ </itemizedlist>
+</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>doShow()</entry>
+
+ <entry>Shows the corresponding tooltip</entry>
+ </row>
+
+ <row>
+ <entry>doHide()</entry>
+
+ <entry>Hides the corresponding tooltip</entry>
+ </row>
+
+ <row>
+ <entry>doEnable()</entry>
+
+ <entry>Enables the corresponding tooltip</entry>
+ </row>
+
+ <row>
+ <entry>doDisable()</entry>
+
+ <entry>Disables the corresponding tooltip</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><rich:tooltip></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:tooltip></property>
+ </emphasis> component</para>
+ </listitem>
+ </itemizedlist>
+
+ </section>
+ <section>
+ <title>Skin Parameters Redefinition</title>
+ <table>
+ <title>Skin parameters redefinition for a component</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Skin parameters</entry>
+ <entry>CSS properties</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>tipBackgroundColor</entry>
+ <entry>background-color</entry>
+ </row>
+ <row>
+ <entry>tipBorderColor</entry>
+ <entry>border-color</entry>
+ </row>
+ <row>
+ <entry>generalSizeFont</entry>
+ <entry>font-size</entry>
+ </row>
+ <row>
+ <entry>generalFamilyFont</entry>
+ <entry>font-family</entry>
+ </row>
+ <row>
+ <entry>generalFontColor</entry>
+ <entry>color</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+</section>
+
+
+ <section>
+ <title>Definition of Custom Style Classes</title>
+ <table>
+ <title>Classes names that define a component appearance</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Class name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>rich-tool-tip</entry>
+ <entry>Defines styles for a wrapper <span> or <div> element of a tooltip</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ It depends on <emphasis role="bold"><property><rich:tooltip></property></emphasis> layout what a wrapper element <emphasis><property><span></property></emphasis> or <emphasis><property><div></property></emphasis>to choose.
+ </para>
+ <para>In order to redefine styles for all <emphasis role="bold">
+ <property><rich:tooltip></property>
+ </emphasis> components on a page using CSS, it's enough to create class with the
+ same name and define necessary properties in it.</para>
+
+ <para>To change styles of particular <emphasis role="bold">
+ <property><rich:tooltip></property>
+ </emphasis> components define your own style class in the corresponding <emphasis
+ role="bold">
+ <property><rich:tooltip></property>
+ </emphasis>attributes</para>
+</section>
+ <section>
+ <title>Relevant Resources Links</title>
+ <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/toolTip.jsf?c=toolTip"
+ >Here</ulink> you can see the example of <emphasis role="bold"
+ ><property><rich:toolTip></property></emphasis> usage and sources for the given example. </para>
+ </section>
+</section>
+
\ No newline at end of file
More information about the richfaces-svn-commits
mailing list