<?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.ModalPanel</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 href="javascript:RichFaces.hideModalPanel('form:panel')">Hide</a>
    </rich:modalpanel>
...
    <a href="javascript:RichFaces.showModalPanel('form:panel')">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>New:</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. </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[...
    <form jsfc="h:form" id="form">
        <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.gif"/>
        <a href="javascript:Richfaces.hideModalPanel('form:panel')">Close</a>
        </rich:modalPanel>
        <a href="javascript:Richfaces.showModalPanel('form:panel');">Open</a>
    </form>
...
]]></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>ModalPanel with links</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/modalpanel2.gif"/>
        </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="panel">
        <f:facet name="header"><h:outputText value="Modal Panel"/></f:facet>
        <f:facet name="controls">
            <a href="javascript:Richfaces.hideModalPanel('form:panel')">X</a>
        </f:facet>
        <h:graphicImage value="/pages/california_large.gif"/>
    </rich:modalPanel>
]]></programlisting>

    <para>The result displays like this:</para>

    <figure>
      <title>ModalPanel with control element</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/modalpanel3.gif"/>
        </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 <emphasis><property>&quot;true&quot;</property></emphasis> or <emphasis><property>&quot;false&quot;</property></emphasis> 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="JAVA"><![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="JAVA"><![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 'showWhenRendered' and 'keepVisualState'. </para>
    <para> showWhenRendered - This boolean attribute is used if modalPanel should be rendered after
      first page loading. </para>
    <para> keepVisualState - Used if modalPanel should save state after submission. If
      keepVisualState=true 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="JAVA"><![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 will be restored. </para>
    <para>if you need the content of the modalPanel to be submitted - you need to remember two important rules: </para>
      <itemizedlist>
      <listitem>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) </listitem>
      <listitem>modalPanel must not be included into the form (on any level up) if it has the
        form inside.</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> 
                        <t: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>
  </section>

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

    <para>For implementing skinnability 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 modal panels at once:</para>

    <itemizedlist>
      <listitem>Redefine the corresponding skin parameters</listitem>

      <listitem>Add <emphasis>
          <property>style classes</property>
        </emphasis> used by modalPanel to your page style sheets</listitem>
    </itemizedlist>
  </section>

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

    <table>
      <title>Panel skin parameters</title>

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

            <entry>Properties corresponding to CSS parameter</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>Header parameters</title>

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

            <entry>Properties corresponding to CSS parameter</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>Header content parameters</title>

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

            <entry>Properties corresponding to CSS parameter</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>Body parameters</title>

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

            <entry>Properties corresponding to CSS parameter</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 custom style classes</title>

    <figure>
      <title>Modal Panel class names</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/modalpanel4.gif"/>
        </imageobject>
      </mediaobject>
    </figure>

    <para>The screenshot shows the classes names for defining different elements.</para>

    <table>
      <title>Class names</title>

      <tgroup cols="2">
        <tbody>
          <row>
            <entry>rich-mpnl-pnl-h</entry>

            <entry>This class defines the header style. It&apos;s applied to the header elements
              of all panels.</entry>
          </row>

          <row>
            <entry>rich-mpnl-pnl-text</entry>

            <entry>This class defines the header content style. It&apos;s applied to the header
              elements of all panels.</entry>
          </row>

          <row>
            <entry>rich-mpnl-pnl-body</entry>

            <entry>This class defines the style for the content inside a panel. It&apos;s
              applied to the elements inside panels.</entry>
          </row>

          <row>
            <entry>generalFamilyFont</entry>

            <entry>font-family</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </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"
        >&lt;rich:modalPanel&gt;</emphasis> usage and sources for the given example. </para>
    <para>Information about wizards using the <emphasis role="bold"
      >&lt;rich:modalPanel&gt;</emphasis> component could be found in the <ulink
        url="http://labs.jboss.com/wiki/ModalPanelWizards">Wiki article</ulink> and in the <link
        linkend="Organizewizards">FAQ</link> chapter of the guide. </para>
    <para>Examples of validation in <emphasis role="bold">&lt;rich:modalPanel&gt;</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>
  </section>
  

</section>
