<?xml version='1.0' encoding='UTF-8'?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>message</keyword>
      <keyword>rich:message</keyword>
      <keyword>HtmlMessage</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.RichMessage</entry>
        </row>
        <row>
          <entry>component-class</entry>
          <entry>org.richfaces.component.html.HtmlRichMessage</entry>
        </row>
        <row>
          <entry>component-family</entry>
          <entry>org.richfaces.component.RichMessage</entry>
        </row>
        <row>
          <entry>renderer-type</entry>
          <entry>org.richfaces.renderkit.html.RichMessagesHtmlBaseRenderer</entry>
        </row>
        <row>
          <entry>tag-class</entry>
          <entry>org.richfaces.taglib.RichMessageTag</entry>
        </row>
      </tbody>
    </tgroup>
  </table>

  <section>
    <title>Creating the Component with a Page Tag</title>
    <para>To create the simplest variant of <property>message</property> on a page, use the
      following syntax:</para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
 	<rich:message for="id"/>
...
]]></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.HtmlRichMessage;
...
HtmlRichMessage myMessage = new HtmlRichMessage();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>
    <para> The component has the same behavior as standard <emphasis role="bold">
        <property>&lt;h:message&gt;</property>
      </emphasis>component except next two features: <itemizedlist>
        <listitem>It's ajaxRendered. It means that the component is reRendered after Ajax request
          automatically without outputPanel usage</listitem>
        <listitem>The component optionally provides "passed" state which will be shown if no message is displayed</listitem>
        <listitem>Provides possibility to add some marker to message. By default  a marker element
          isn't shown</listitem>
      </itemizedlist>
    </para>
    <para> A set of facets which can be used for marker defining: <itemizedlist>
        <listitem>passedMarker. This facet is provided to allow setting a marker to display if
          there is no message</listitem>
        <listitem>errorMarker. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "ERROR"</listitem>
        <listitem>fatalMarker. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "FATAL"</listitem>
        <listitem>infoMarker. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "INFO"</listitem>
        <listitem>warnMarker. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "WARN"</listitem>
      </itemizedlist>
    </para>

    <para> The following example shows different variants for component customization. The
      attribute 'passedLabel' is used for definition of the label to display when no message
      appears. But the message component doesn't appear before the form submission even when 
      state is defined as passed (on initial rendering). Boolean attribute<emphasis><property> &quot;showSummary&quot; </property></emphasis>defines possibility to
      display summary portion of displayed messages. The facets "errorMarker" and 'passedMarker' set
      corresponding images for markers. </para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
      	<rich:message for="id" passedLabel="No errors' showSummary="true">
      		<f:facet name="errorMarker">
      			<h:graphicImage url="/image/error.png"/>
      		</f:facet>
			<f:facet name="passedMarker">
      			<h:graphicImage url="/image/passed.png"/>
      		</f:facet>  	
		</rich:message> 	
...
]]></programlisting>

  </section>

  <section>
    <title>Look-and-Feel Customization</title>

    <para>For skinnability implementation, the components use a <emphasis>
      <property>style class redefinition method.</property>
    </emphasis></para>

    <para>There are no skin parameters and default predefined values. To redefine the appearance of all <emphasis
      role="bold">
      <property>&lt;rich:message&gt;</property>
    </emphasis> components at once, you should only  add to your style sheets <emphasis>
      <property>style classes</property>
    </emphasis> used by a <emphasis
      role="bold">
      <property>&lt;rich:message&gt;</property>
    </emphasis> component.</para>
  </section>

  <section>
    <title>Definition of Custom Style Classes</title>
    
    <para>On the screenshot there are classes names that define styles for component elements.</para>

    <figure>
      <title>Classes names</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/message1.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <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-message</entry>

            <entry>Defines styles for a wrapper element</entry>
          </row>

          <row>
            <entry>rich-message-marker</entry>

            <entry>Defines styles for a marker</entry>
          </row>

          <row>
            <entry>rich-message-label</entry>

            <entry>Defines styles for a label</entry>
          </row>

        </tbody>
      </tgroup>
    </table>

    <para>In order to redefine styles for all <emphasis role="bold">
      <property>&lt;rich:message&gt;</property>
    </emphasis> components on a page using CSS, it&apos;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>&lt;rich:message&gt;</property>
    </emphasis> components, define your own style classes in the corresponding <emphasis
      role="bold">
      <property>&lt;rich:message&gt;</property>
    </emphasis>attributes.</para>
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/message.jsf?c=message"
      >Here</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;rich:message&gt;</property></emphasis> usage and sources for the given example. </para>
  </section>   
</section>
