<?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><para>It&apos;s ajaxRendered. It means that the component is reRendered after Ajax request
          automatically without outputPanel usage</para></listitem>
        <listitem><para>The component optionally provides "passed" state which will be shown if no message is displayed</para></listitem>
        <listitem><para>Provides possibility to add some marker to message. By default  a marker element
          isn't shown</para></listitem>
      </itemizedlist>
    </para>
    <para> A set of facets which can be used for marker defining: <itemizedlist>
        <listitem><para><emphasis><property>&quot;passedMarker&quot;</property></emphasis>. This facet is provided to allow setting a marker to display if
          there is no message</para></listitem>
      <listitem><para><emphasis><property>&quot;errorMarker&quot;</property></emphasis>. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "ERROR"</para></listitem>
      <listitem><para><emphasis><property>&quot;fatalMarker&quot;</property></emphasis>. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "FATAL"</para></listitem>
      <listitem><para><emphasis><property>&quot;infoMarker&quot;</property></emphasis>. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "INFO"</para></listitem>
      <listitem><para><emphasis><property>&quot;warnMarker&quot;</property></emphasis>. This facet is provided to allow setting a marker to display if there
          is a message with a severity class of "WARN"</para></listitem>
      </itemizedlist>
    </para>

    <para> The following example shows different variants for component customization. The
      attribute <emphasis><property>&quot;passedLabel&quot;</property></emphasis> 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 <emphasis><property>&quot;errorMarker&quot;</property></emphasis> and <emphasis><property>&quot;passedMarker&quot;</property></emphasis> 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>Facets</title>
    <table>
      <title>Facets</title>
      <tgroup cols="2">
        <thead>
          <row>
            <entry>Facet</entry>
            <entry>Description</entry>
          </row>
        </thead>
        <tbody>
          <row>
            <entry>errorMarker</entry>
            <entry>Redefines the content for the marker if there is message with a severity class of &quot;ERROR&quot;</entry>
          </row>
          <row>
            <entry>fatalError</entry>
            <entry>Redefines the content for the marker if there is message with a severity class of &quot;FATAL&quot;</entry>
          </row>
          <row>
            <entry>infoError</entry>
            <entry>Redefines the content for the marker if there is message with a severity class of &quot;INFO&quot;</entry>
          </row>
          <row>
            <entry>warnError</entry>
            <entry>Redefines the content for the marker if there is message with a severity class of &quot;WARN&quot;</entry>
          </row>
          <row>
            <entry>passedError</entry>
            <entry>Redefines the content for the marker if there is no message</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></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/message_cn.png"/>
        </imageobject>
      </mediaobject>
    </figure>

    <table id="mC">
      <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 (possible classes could be found in the tables <link linkend="mC"> above</link>) and define necessary properties in them. </para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-message-label{
    font-style:italic
}
...]]></programlisting>  
    
    <para>This is a result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/message_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>In the example the font style for message was changed.</para>
    
    <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
      ><property>&lt;rich:message&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
        ><property>&lt;rich:message&gt;</property></emphasis> <property>styleClass</property> attributes. An example is placed below:</para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.myClass{
    font-weight:bold;
}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;styleClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:message&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:message ... styleClass="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/message_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above, the font weight for message was changed.</para>
    
    
    
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para><ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/message.jsf?c=message"
      >On the component LiveDemo page</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>
