<?xml version="1.0" encoding="UTF-8"?>
<section>
  <sectioninfo>
    <keywordset>
      <keyword>rich:modalPanel</keyword>

      <keyword>HtmlModalPanel</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.ModalPanel</entry>
        </row>

        <row>
          <entry>component-class</entry>

          <entry>org.richfaces.component.html.HtmlModalPanel</entry>
        </row>

        <row>
          <entry>component-family</entry>

          <entry>org.richfaces.ModalPanel</entry>
        </row>

        <row>
          <entry>renderer-type</entry>

          <entry>org.richfaces.ModalPanelRenderer</entry>
        </row>

        <row>
          <entry>tag-class</entry>

          <entry>org.richfaces.taglib.ModalPanelTag</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[...
<rich:modalPanel id="panel">
    <f:facet name="header">
        <h:outputText value="header" />
    </f:facet>
    ...
    <!--Any Content inside-->
    ...
<a onclick="Richfaces.hideModalPanel('modalPanelID');" href="#">Hide</a> 
</rich:modalPanel>
<a onclick="Richfaces.showModalPanel('modalPanelID');" href="#">Show</a> 
...
]]></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.HtmlModalPanel;
...
HtmlModalPanel myPanel = new HtmlModalPanel();
...
]]></programlisting>
  </section>

  <section>
    <title>Details of Usage</title>

    <para>The component is defined as a panel with some content inside that displays its content as
      a modal dialog. To call it and to close it, the client API for the window is used.</para>

    <table>
      <title>Functions description</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Function</entry>

            <entry>Description</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>RichFaces.showModalPanel (client Id)</entry>

            <entry>Opens a window with a specified client Id</entry>
          </row>

          <row>
            <entry>RichFaces.hideModalPanel (client Id)</entry>

            <entry>Closes a window with a specified client Id</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <important>
      <title>Important:</title>
      <para>In order to avoid a bug in IE, the root node of the dialog is moved on the top of a DOM
        tree. However, you should have a separate form inside the modal panel if you want to perform
        submits from this panel (so, no form should be around the modal panel in this case).</para>
    </important>

    <para>It&apos;s possible to add a <emphasis><property>&quot;header&quot;</property></emphasis> facet to the component to set
      the content for the header.</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
    <rich:modalPanel id="panel" width="400" height="300">
        <f:facet name="header">
            <h:outputText value="Modal Panel"/>
        </f:facet>
        <h:graphicImage value="/pages/california_large.png"/>
        <a href="javascript:Richfaces.hideModalPanel('form:panel')">Close</a>
    </rich:modalPanel>
    <a href="javascript:Richfaces.showModalPanel('form:panel');">Open</a>
...]]></programlisting>

    <para>This defines a window with a particular size and ID. It includes one "Open" link. Clicking
      on this link makes the modal window content appear.</para>

    <figure>
      <title><emphasis role="bold"><property>&lt;rich:modalPanel&gt;</property></emphasis> with links</title>

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

    <para>A facet named <emphasis><property>&quot;controls&quot;</property></emphasis> can be added to the component to place control
      elements on a header.</para>


    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[...
<rich:modalPanel id="mp">
    <f:facet name="header">
        <h:outputText value="Modal Panel"/>
    </f:facet>
    <f:facet name="controls">
        <h:graphicImage value="/pages/close.png" style="cursor:pointer" onclick="Richfaces.hideModalPanel('mp')" />
    </f:facet>
    <h:graphicImage value="/pages/california_large.png"/>
</rich:modalPanel>
...]]></programlisting>

    <para>The result is displayed here:</para>

    <figure>
      <title><emphasis role="bold"><property>&lt;rich:modalPanel&gt;</property></emphasis> with control element</title>

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

    <para>To manage the placement of inserted windows, use the <emphasis>
        <property>"zindex"</property>
      </emphasis> attribute that is similar to the standard HTML attribute and can specify window
      placement relative to the content.</para>

    <para>To manage window placement relative to the component, there are <emphasis>
        <property>"left"</property>
      </emphasis> and <emphasis>
        <property>"top"</property>
      </emphasis> attributes defining a window shifting relative to the top-left corner of the
      window.</para>

    <para>Modal windows can also support resize and move operations on the client side. To allow or
      disallow these operations, set the <emphasis>
        <property>"resizeable"</property>
      </emphasis> and <emphasis>
        <property>"moveable"</property>
      </emphasis> attributes to &quot;true&quot; or &quot;false&quot; values. Window
      resizing is also limited by <emphasis>
        <property>"minWidth"</property>
      </emphasis> and <emphasis>
        <property>"minHeight"</property>
      </emphasis> attributes specifying the minimal window sizes.</para>
    <para> You can pass your parameters during modalPanel opening or closing. This passing could be
      performed in the following way: </para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="XML"><![CDATA[Richfaces.showModalPanel('panelId', {left: auto}, {param1: value1});]]></programlisting>
    <para> Thus, except the standard modalPanel parameters you can pass any of your own parameters. </para>
    <para> Also modalPanel allows to handle its own opening and closing events on the client side.
      The <emphasis><property>&quot;onshow&quot;</property></emphasis> and <emphasis><property>&quot;onclose&quot;</property></emphasis> attributes are used in this
      case. </para>
    <para> The following example shows how on the client side to define opening and closing event
      handling in such a way that your own parameters could also be obtained: </para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>

    <programlisting role="XML"><![CDATA[onshow="alert(event.parameters.param1)"]]></programlisting>

    <para> Here, during modalPanel opening the value of a passing parameter is output. </para>
    <para> More information about this problem could be found on the <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;t=111804"
        >RichFaces Development Forum</ulink>.</para>
    <para> There is a possibility to restore of the previous component state on a page (including
      position on the screen) after submitting and reloading. The modalPanel has some special
      attributes like <emphasis><property>&quot;showWhenRendered&quot;</property></emphasis> and <emphasis><property>&quot;keepVisualState&quot;</property></emphasis>. </para>
    <para> <emphasis><property>&quot;showWhenRendered&quot;</property></emphasis> - This boolean attribute is used if modalPanel should be rendered after
      first page loading. </para>
    <para><emphasis><property> &quot;keepVisualState&quot;</property></emphasis> - Used if modalPanel should save state after submission. If
      <code>keepVisualState=&quot;true&quot;</code> then parameters which modalPanel has during opening should be submitted
      and passed to new page. </para>

    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>

    <programlisting role="XML"><![CDATA[...
<a href="javascript:Richfaces.showModalPanel('_panel', {top:'10px', left:'10px', height:'400'});">Show</a>
...]]></programlisting>

    <para> Here, if you open modal dialog window using current link and after submits data then
      modalPanel destination and height on new loaded page is restored. </para>
    <para>if you need the content of the modalPanel to be submitted - you need to remember two important rules: </para>
      <itemizedlist>
      <listitem><para>modalPanel must have its own form if it has form elements (input or/and command
        components) inside (as it was shown in the example above) </para></listitem>
      <listitem><para>modalPanel must not be included into the form (on any level up) if it has the
        form inside.</para></listitem>
    </itemizedlist> 
      <para>Simple example of using commandButton within modalPanel is placed below.</para>
    <para><emphasis role="bold">Example:</emphasis></para>

    <programlisting role="XML"><![CDATA[...
<rich:modalPanel> 
    <f:facet name="header"> 
        <h:outputText value="Test" /> 
    </f:facet> 
    <f:facet name="controls"> 
        <h:commandLink value="Close" style="cursor:pointer" onclick="Richfaces.hideModalPanel('mp')" /> 
    </f:facet> 
    <h:form> 
        <h:commandButton value="Test" action="#{TESTCONTROLLER.test}" /> 
    </h:form> 
</rich:modalPanel>
...
<h:form> 
    <!--Some other Page content-->
</h:form>
...]]></programlisting>

  

   <para>See also discussion about this problem on the <ulink
      url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4064191"
      >RichFaces Users Forum</ulink>.</para>
    <para>
      The <emphasis>
        <property>&quot;label&quot;</property>
      </emphasis> attribute is a generic attribute.
      The <emphasis>
        <property>&quot;label&quot;</property>
      </emphasis> attribute provides an association between a component, and the message that the component (indirectly) produced.  
      This attribute defines the parameters of localized error and informational messages that
      occur as a result of conversion, validation, or other application actions during the request
      processing lifecycle. With the help of this attribute you can  replace the 
      last parameter substitution token shown in the messages. For example, {1} for <code>&quot;DoubleRangeValidator.MAXIMUM&quot;</code>, {2}
      for <code>&quot;ShortConverter.SHORT&quot;</code>.
    </para>
	<para>
		<ulink url="http://wiki.jboss.org/auth/wiki/RichFacesCookbook/DetailModalPanelFromTable">
			Here
		</ulink>
		there is information for those of you who would like to click on a details link in table and have it show a modal panel with information loaded from the server.
	</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>show()</entry>
            <entry>Opens the corresponding modalPanel</entry>
          </row>
          
          <row>
            <entry>hide()</entry>
            <entry>Closes the corresponding modalPanel</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>&lt;rich:modalPanel&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:modalPanel&gt;</property>
        </emphasis> component</para>
      </listitem>
    </itemizedlist>
  </section>

  <section>
    <title>Skin Parameters Redefinition</title>

    <table>
      <title>Skin parameters for a component</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>generalBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>panelBorderColor</entry>

            <entry>border-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a header element</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>headerBackgroundColor</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>headerBackgroundColor</entry>

            <entry>border-color</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a header content</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</entry>

            <entry>CSS properties</entry>
          </row>
        </thead>

        <tbody>
          <row>
            <entry>headerSizeFont</entry>

            <entry>background-color</entry>
          </row>

          <row>
            <entry>headerTextColor</entry>

            <entry>font-size</entry>
          </row>

          <row>
            <entry>headerWeightFont</entry>

            <entry>color</entry>
          </row>

          <row>
            <entry>headerFamilyFont</entry>

            <entry>font-family</entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <table>
      <title>Skin parameters redefinition for a body element</title>

      <tgroup cols="2">
        <thead>
          <row>
            <entry>Skin parameters</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>
  </section>

  <section>
    <title>Definition of Custom Style Classes</title>

    <figure>
      <title><emphasis role="bold"><property>&lt;rich:modalPanel&gt;</property></emphasis> class name</title>

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

    <para>The screenshot shows the classes names for defining different elements.</para>
    
    <table id="mPC">
      <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-modalpanel</entry>
            
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a modalpanel</entry>
          </row>
          
          <row>
            <entry>rich-mpnl_panel</entry>
            
            <entry>Defines styles for a modalpanel</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-mask-div</entry>
            
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a mask</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-resizer</entry>
            
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a resizing element</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-shadow</entry>
            
            <entry>Defines styles for a modalpanel shadow</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-header</entry>
            
            <entry>Defines styles for a modalpanel header</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-header-cell</entry>
            
            <entry>Defines styles for a header cell</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-text</entry>
            
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a header text</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-body</entry>
            
            <entry>Defines styles for a content inside a modalpanel</entry>
          </row>
          
          <row>
            <entry>rich-mpnl-controls</entry>
            
            <entry>Defines styles for a wrapper  &lt;div&gt; element of a modalpanel control</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>In order to redefine styles for all <emphasis role="bold">
      <property>&lt;rich:modalPanel&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="mPC"> above</link>) and define necessary properties in them. </para>
    
    <para>
      <emphasis role="bold">Example:</emphasis>
    </para>
    <programlisting role="CSS"><![CDATA[...
.rich-mpnl-mask-div{
    background-color:#fae6b0;
}
...]]></programlisting>  
    
    <para>This is a result:</para>
    
    <figure>
      <title>Redefinition styles with predefined classes</title>
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/modalPanel_pc.png"/>
        </imageobject>
      </mediaobject>
    </figure>
    
    <para>In the example the background color for mask was changed.</para>
    
    <para>Also it&apos;s possible to change styles of particular <emphasis role="bold"
      ><property>&lt;rich:modalPanel&gt;</property></emphasis> component. In this case you should create own style classes and use them in corresponding <emphasis role="bold"
        ><property>&lt;rich:modalPanel&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{
    font-style:italic;
}
...]]></programlisting>  
    <para>The <emphasis><property>&quot;headerClass&quot;</property></emphasis> attribute for <emphasis role="bold"
      ><property>&lt;rich:modalPanel&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:modalPanel ... headerClass="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/modalPanel_oc.png"/>
        </imageobject>
      </mediaobject>
    </figure>  
    
    <para>As it could be seen on the picture above,the font style for header was changed.</para>
    
   
  </section>
  <section>
    <title>Relevant Resources Links</title>
    <para>
      <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/modalPanel.jsf?c=modalPanel"
        >Here</ulink> you can see the example of <emphasis role="bold"
        ><property>&lt;rich:modalPanel&gt;</property></emphasis> usage and sources for the given example. </para>
    <para>Information about wizards using the <emphasis role="bold"
      ><property>&lt;rich:modalPanel&gt;</property></emphasis> component could be found in the <ulink
        url="http://labs.jboss.com/wiki/ModalPanelWizards">Wiki article</ulink> and in the <ulink
        url="http://www.jboss.org/file-access/default/members/jbossrichfaces/freezone/docs/devguide/en/faq/faq.html#Organizewizards">FAQ</ulink> chapter of the guide. </para>
    <para>Examples of validation in <emphasis role="bold"><property>&lt;rich:modalPanel&gt;</property></emphasis>
      could be found in the <ulink url="http://labs.jboss.com/wiki/ModalPanelValidation">Wiki article</ulink> and on the <ulink
        url="http://www.jboss.com/index.html?module=bb&amp;op=viewtopic&amp;p=4061517"
        >RichFaces Users Forum</ulink>. </para>
        <para>
    	<ulink
    		url="http://wiki.jboss.org/wiki/RichFacesPleaseWaitBox">
    		Here
    	</ulink>
    	you can find information on how to show a &quot;Please Wait&quot; box and
    	block the input while the Ajax request is processed using combination of
    	<emphasis role="bold">
    		<property>&lt;a4j:status&gt;</property>
    	</emphasis>
    	and
    	<emphasis role="bold">
    		<property>&lt;rich:modalPanel&gt;</property>
    	</emphasis>
		components
    	.
    </para>
  </section>
  

</section>
