Author: lfryc(a)redhat.com Date: 2011-11-07 10:47:57 -0500 (Mon, 07 Nov 2011) New Revision: 22889 Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richnotify.xml Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml Log: RFPL-1580: rich:notify documentation Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml 2011-11-07 01:18:47 UTC (rev 22888) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Component_Reference-Output_and_messages.xml 2011-11-07 15:47:57 UTC (rev 22889) @@ -238,6 +238,108 @@ <xi:include href="skinning/tabl-richmessages.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> </section> </section> + + <section id="sect-Component_Reference-Output_and_messages-richnotify"> + <title><sgmltag>&lt;rich:notify&gt;</sgmltag></title> + <para> + The <sgmltag>&lt;rich:notify&gt;</sgmltag> component serves for advanced user interaction, giving user instant feedback on what's happening in application in form of notifications. + </para> + <para> + Each time this component is rendered, floating notification box is displayed in the selected corner of the browser screen. + </para> + + <section id="sect-Component_Reference-richnotify-Basic_usage"> + <title>Basic usage</title> + <para> + The <sgmltag>&lt;rich:notify&gt;</sgmltag> has two message customization attributes: <parameter>summary</parameter> is short text summarizing the message communicated with user, while <parameter>detail</parameter> configures detailed body of the message. + </para> + <para> + Both attributes have their counterparts in form of facets with same names as respective attributes. + </para> + </section> + + <section id="sect-Component_Reference-richnotify-Customizing_notifications"> + <title>Customizing notifications</title> + <para> + By default, notifications appears immediately after request which renders them in case of AJAX requests or once page is completely loaded in full-page request. + </para> + <para> + They are waiting for 8 seconds and then they disappear. User can close notification with close button in the top-right corner of each notification. + </para> + <para> + But there are several attributes that can change default behavior: + </para> + <itemizedlist> + <listitem> + <para> + <parameter>sticky</parameter>: notifications does not disappear automatically, they needs to be closed explicitly with close button (this attribute can't be used together with <parameter>nonblocking</parameter> and <parameter>stayTime</parameter>) + </para> + </listitem> + <listitem> + <para> + <parameter>stayTime</parameter>: configures how long notification stays on the screen before it disappears (in miliseconds) + </para> + </listitem> + <listitem> + <para> + <parameter>styleClass</parameter>: defines the class customizing the notification + </para> + </listitem> + <listitem> + <para> + <parameter>nonblocking</parameter>: defines notifications which can't be closed manually, user needs to wait before they disappear, but once notification is hovered with mouse, it becomes partially transparent and user can click through + </para> + </listitem> + <listitem> + <para> + <parameter>nonblockingOpacity</parameter>: defines opacity of nonblocking notifications when mouse hovers over notification + </para> + </listitem> + <listitem> + <para> + <parameter>showShadow</parameter>: defines whether shadow will be displayed under the notification + </para> + </listitem> + </itemizedlist> + <para> + Note that nonblocking notifications can be clicked through, but because they are using jQuery mechanism to bypass events, only jQuery event handlers are triggered. It specifically means that standard links won't be triggered. + </para> + </section> + + <section id="sect-Component_Reference-richnotify-Reference_data"> + <title>Reference data</title> + <itemizedlist> + <listitem> + <para> + <parameter>component-type</parameter>: <classname>org.richfaces.Notify</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-class</parameter>: <classname>org.richfaces.component.UINotify</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>component-family</parameter>: <classname>org.richfaces.Notify</classname> + </para> + </listitem> + <listitem> + <para> + <parameter>renderer-type</parameter>: <classname>org.richfaces.NotifyRenderer</classname> + </para> + </listitem> + </itemizedlist> + </section> + + <section id="sect-Component_Reference-richnotify-Style_classes_and_skin_parameters"> + <title>Style classes and skin parameters</title> + <para>Note that skinning is common for both <sgmltag>&lt;rich:notify&gt;</sgmltag>, <sgmltag>&lt;rich:notifyMessage&gt;</sgmltag> and <sgmltag>&lt;rich:notifyMessages&gt;</sgmltag></para> + <xi:include href="skinning/tabl-richnotify.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + </section> + </section> + + <!-- <rich:paint2D> --> <!-- Added: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richnotify.xml =================================================================== --- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richnotify.xml (rev 0) +++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/skinning/tabl-richnotify.xml 2011-11-07 15:47:57 UTC (rev 22889) @@ -0,0 +1,249 @@ +<?xml version='1.0' encoding='utf-8' ?> +<!DOCTYPE table PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ +]> + +<table id="tabl-richnotify-Style_classes_and_corresponding_skin_parameters"> + <title>Style classes (selectors) and corresponding skin parameters</title> + <tgroup cols="3"> + <colspec colname="class"/> + <colspec colname="skin"/> + <colspec colname="css"/> + <spanspec spanname="noskin" namest="skin" nameend="css"/> + <thead> + <row> + <entry>Class (selector)</entry> + <entry>Skin Parameters</entry> + <entry>Mapped <acronym>CSS</acronym> properties</entry> + </row> + </thead> + <tbody> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf</classname></term> + <listitem> + <para> + This class defines styles for notification + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-info</classname></term> + <listitem> + <para> + This class defines styles for an informative message. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry><para><parameter>generalTextColor</parameter></para></entry> + <entry><para><property>color</property></para></entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-warn</classname></term> + <listitem> + <para> + This class defines styles for a warning notifications. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-error</classname></term> + <listitem> + <para> + This class defines styles for a error notifications. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-fatal</classname></term> + <listitem> + <para> + This class defines styles for a fatal notifications. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-info .rf-ntf-ico</classname></term> + <term><classname>.rf-ntf-warn .rf-ntf-ico</classname></term> + <term><classname>.rf-ntf-error .rf-ntf-ico</classname></term> + <term><classname>.rf-ntf-fatal .rf-ntf-ico</classname></term> + <listitem> + <para> + These classes define style for notification icon based on severity of notification message. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry morerows="1"> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-shdw</classname></term> + <listitem> + <para> + This class defines style of the shadow under notification box. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry><para><parameter>headerBackgroundColor</parameter></para></entry> + <entry><para><property>background-color</property></para></entry> + </row> + <row> + <entry><para><parameter>headerTextColor</parameter></para></entry> + <entry><para><property>color</property></para></entry> + </row> + + <row> + <entry morerows="2"> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-cnt</classname></term> + <listitem> + <para> + This class defines style of the content of notification box. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry><para><parameter>panelBorderColor</parameter></para></entry> + <entry><para><property>border-color</property></para></entry> + </row> + <row> + <entry><para><parameter>generalBackgroundColor</parameter></para></entry> + <entry><para><property>background-color</property></para></entry> + </row> + <row> + <entry><para><parameter>panelTextColor</parameter></para></entry> + <entry><para><property>color</property></para></entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-ico</classname></term> + <listitem> + <para> + This class defines style for notification icon. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-tl</classname></term> + <listitem> + <para> + This class defines style for notification message summary. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-txt</classname></term> + <listitem> + <para> + This class defines style for notification message detail. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-cls</classname></term> + <listitem> + <para> + This class defines style for element wrapping close button. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + <row> + <entry> + <variablelist> + <varlistentry> + <term><classname>.rf-ntf-cls-ico</classname></term> + <listitem> + <para> + This class defines style for close button icon. + </para> + </listitem> + </varlistentry> + </variablelist> + </entry> + <entry spanname="noskin">No skin parameters.</entry> + </row> + + </tbody> + </tgroup> +</table>