Created <div class="wiki-content" style="margin-right:10px;"> <!-- wiki content --> <p>TOCSTART</p> <div> <ul> <li><a href="#PopupLayer2.x-KeyFeatures">Key Features</a></li> <li><a href="#PopupLayer2.x-BasicConfiguration">Basic Configuration</a></li> <li><a href="#PopupLayer2.x-AutoHiding">Auto-Hiding</a></li> <li><a href="#PopupLayer2.x-PositioningonthePage">Positioning on the Page</a></li> <li><a href="#PopupLayer2.x-SpecifyingtheSize">Specifying the Size</a></li> <li><a href="#PopupLayer2.x-DefiningModality">Defining Modality</a></li> <li><a href="#PopupLayer2.x-DraggingSupport">Dragging Support</a></li> <li><a href="#PopupLayer2.x-CustomizingStyles">Customizing Styles</a></li> <li><a href="#PopupLayer2.x-ClientSideEvents">Client-Side Events</a></li> <li><a href="#PopupLayer2.x-ClientSideAPI">Client-Side API</a></li> </ul> </div> <p>TOCEND</p> <p>The <cite>PopupLayer</cite> component is a container for other JSF components that is displayed over the page contents. The size, placement, timeout value, and modality of the component can be easily customized. A convenient API lets you manage the display behavior of the <cite>PopupLayer</cite> component on the client side.</p> <p><span class="image-wrap" style=""><img src="/download/attachments/1703957/popupLayer.png?version=1&modificationDate=1290511121607" style="border: 0px solid black"></span><br> <a href="http://www.openfaces.org/demo/popuplayer/" class="external-link" rel="nofollow">Online Demo</a> </p> <h4><a name="PopupLayer2.x-KeyFeatures"></a>Key Features</h4> <ul> <li><a href="#PopupLayer2.x-BasicConfiguration">Ability to embed JSF components</a></li> <li><a href="#PopupLayer2.x-SettingModality">Support for modality</a></li> <li><a href="#PopupLayer2.x-DraggingSupport">Dragging Support</a></li> <li><a href="#PopupLayer2.x-ClientSideAPI">Client-side API</a></li> <li><a href="#PopupLayer2.x-AutoHiding">Auto-hiding by timeout</a></li> <li><a href="#PopupLayer2.x-CustomizingStyles">Style customization</a></li> <li><a href="#PopupLayer2.x-ClientSideEvents">Standard and component-specific client-side events</a></li> </ul> <h4><a name="PopupLayer2.x-BasicConfiguration"></a>Basic Configuration</h4> <p>To add the <cite>PopupLayer</cite> component to a page, use the <u><o:popupLayer></u> tag. As a container, the <cite>PopupLayer</cite> lets you place any kind of JSF components inside it to build its content. The display behavior of the <cite>PopupLayer</cite> component can be managed in two ways:</p> <ul> <li>Showing and hiding the <cite>PopupLayer</cite> component without reloading the page using the <tt>show()</tt> and <tt>hide()</tt> JavaScript functions. </li> </ul> <p>In the following example, when a user clicks the button, a <cite>PopupLayer</cite> component is shown. It contains a text and a button, which hides the <cite>PopupLayer</cite> when clicked.</p> <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><h:form id=<span class="code-quote">"form1"</span>> <input type=<span class="code-quote">"button"</span> id=<span class="code-quote">"popupInvoker"</span> value=<span class="code-quote">"Show PopupLayer"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').show();"</span>/> <o:popupLayer id=<span class="code-quote">"popupLayer1"</span>> <f:verbatim> Click here to hide <span class="code-keyword">this</span> PopupLayer:<br/> <input type=<span class="code-quote">"button"</span> value=<span class="code-quote">"Hide"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').hide();"</span>/> </f:verbatim> </o:popupLayer> </h:form> </pre> </div> </div> <ul> <li>Showing and hiding the <cite>PopupLayer</cite> component using the <b>visible</b> server-only boolean attribute, which you can bind to a boolean property in the backing bean, like shown in the example below: <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><o:popupLayer id=<span class="code-quote">"popupLayer1"</span> visible=<span class="code-quote">"#{TestBean.popupLayerIsVisible}"</span>> <h:outputText value=<span class="code-quote">"Some text"</span>/> </o:popupLayer> </pre> </div> </div> </li> </ul> <h4><a name="PopupLayer2.x-AutoHiding"></a>Auto-Hiding</h4> <p>The <cite>PopupLayer</cite> component can be automatically hidden after a timeout. You can specify the timeout value in milliseconds in the <b>hidingTimeout</b> attribute. If the <b>hidingTimeout</b> attribute is <i>"0"</i> (default), the <cite>PopupLayer</cite> component will not be hidden automatically.</p> <p>The <cite>PopupLayer</cite> component can be automatically dismissed when the user clicks outside of the component. You can define this behavior by setting the <b>hideOnOuterClick</b> attribute to <i>"true"</i> (by default, it is <i>"false"</i>).</p> <p>In the example below, if the user doesn't click the <u><i>Hide</i></u>button, the <cite>PopupLayer</cite> is hidden in 10000 milliseconds (or 10 seconds).</p> <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><o:popupLayer id=<span class="code-quote">"popupLayer1"</span> hidingTimeout=<span class="code-quote">"10000"</span>> <f:verbatim> Click here to hide <span class="code-keyword">this</span> PopupLayer:<br/> <input type=<span class="code-quote">"button"</span> value=<span class="code-quote">"Hide"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').hide();"</span>/> </f:verbatim> </o:popupLayer> </pre> </div> </div> <h4><a name="PopupLayer2.x-PositioningonthePage"></a>Positioning on the Page</h4> <p>By default, the <cite>PopupLayer</cite>'s position is not defined and it is displayed as any other DHTML element with the absolute position: its placement may depend on CSS styles applied to it and/or the position on the page.</p> <p>You can position the <cite>PopupLayer</cite> component explicitly by specifying its <b>left</b> and <b>top</b> attributes in pixels. These attributes define the <b>x</b> and <b>y</b> coordinates of the component's upper-left corner relative to the upper-left corner of the document or an absolutely positioned immediate container of the <cite>PopupLayer</cite> component. Note that the <b>left</b> and <b>top</b> attributes should indicate the number of pixels, without the postfix <i>"px"</i>, like shown in the following example:</p> <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><o:popupLayer id=<span class="code-quote">"popupLayer1"</span> left=<span class="code-quote">"300"</span> top=<span class="code-quote">"200"</span>> <f:verbatim> Click here to hide <span class="code-keyword">this</span> PopupLayer:<br/> <input type=<span class="code-quote">"button"</span> value=<span class="code-quote">"Hide"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').hide();"</span>/> </f:verbatim> </o:popupLayer> </pre> </div> </div> <h4><a name="PopupLayer2.x-SpecifyingtheSize"></a>Specifying the Size</h4> <p>By default, the <cite>PopupLayer</cite> component is adjusted to accommodate its content. However, you can set fixed width and height in any units (px, mm, em, etc) by using the <b>width</b> and <b>height</b> attributes.</p> <p>The following example shows a fixed-sized <cite>PopupLayer</cite> component:</p> <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><o:popupLayer id=<span class="code-quote">"popupLayer1"</span> width=<span class="code-quote">"200px"</span> height=<span class="code-quote">"100px"</span>> <f:verbatim> Click here to hide <span class="code-keyword">this</span> PopupLayer:<br/> <input type=<span class="code-quote">"button"</span> value=<span class="code-quote">"Hide"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').hide();"</span>/> </f:verbatim> </o:popupLayer> </pre> </div> </div> <h4><a name="PopupLayer2.x-DefiningModality"></a>Defining Modality</h4> <p>You can specify whether the <cite>PopupLayer</cite> component is shown in a modal state using the <b>modal</b> attribute (set to <i>"false"</i> by default). When a modal <cite>PopupLayer</cite> is displayed, all other components on the page are inaccessible until the <cite>PopupLayer</cite> component is hidden.</p> <p>You can apply a style to the visible part of the page which is not covered by a modal <cite>PopupLayer</cite> by using the <b>modalLayerStyle</b> and <b>modalLayerClass</b> attributes. Note that this style is applied <em>only</em> if the <b>modal</b> attribute is set to <i>"true"</i>. The following example shows a modal <cite>PopupLayer</cite>: </p> <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><o:popupLayer id=<span class="code-quote">"popupLayer1"</span> modal=<span class="code-quote">"<span class="code-keyword">true</span>"</span> modalLayerStyle=<span class="code-quote">"background-color:silver;"</span>> <f:verbatim> Click here to hide <span class="code-keyword">this</span> PopupLayer:<br/> <input type=<span class="code-quote">"button"</span> value=<span class="code-quote">"Hide"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').hide();"</span>/> </f:verbatim> </o:popupLayer> </pre> </div> </div> <p>By default, the modal <cite>PopupLayer</cite> can can be closed by pressing the Esc key. This behavior can be turned off by setting the <b>hideOnEsc</b> attribute to <i>false</i>.</p> <p>Note that modality is provided by covering the page by a <u><div></u> element that is placed under a modal <cite>PopupLayer</cite>. By default, this <div> has the z-index equal to 300 and a modal <cite>PopupLayer</cite> has the z-index equal to 301. While this configuration works fine in the most cases, you can tune the z-indexes using the <b>style</b> and <b>modalLayerStyle</b> attributes, if needed.</p> <h4><a name="PopupLayer2.x-DraggingSupport"></a>Dragging Support</h4> <p>The <cite>PopupLayer</cite> component supports dragging. By default, the dragging feature is turned off. Turning this feature on by setting the <b>draggable</b> attribute to <i>"true"</i> allows the user to drag the <cite>PopupLayer</cite> component by its content area.</p> <p>The following example shows a draggable <cite>PopupLayer</cite> component:</p> <div class="code panel" style="border-width: 1px;"> <div class="codeContent panelContent"> <pre class="code-java"><o:popupLayer id=<span class="code-quote">"popupLayer1"</span> left=<span class="code-quote">"300"</span> top=<span class="code-quote">"200"</span> draggable=<span class="code-quote">"<span class="code-keyword">true</span>"</span>> <f:verbatim> Click here to hide <span class="code-keyword">this</span> PopupLayer:<br/> <input type=<span class="code-quote">"button"</span> value=<span class="code-quote">"Hide"</span> onclick=<span class="code-quote">"O$('form1:popupLayer1').hide();"</span>/> </f:verbatim> </o:popupLayer> </pre> </div> </div> <p>It is possible to restrict the area where the <cite>PopupLayer</cite> can be moved using the <b>containment</b> attribute. This attribute can take the following values:</p> <ul class="alternate" type="square"> <li><i>"document"</i> – doesn't allow to move the <cite>PopupLayer</cite> across document's boundaries;</li> <li><i>"viewport"</i> – doesn't allow to move the <cite>PopupLayer</cite> out of the current viewport (the currently visible portion of the document); </li> <li><i>"containingBlock"</i> – doesn't allow to move the <cite>PopupLayer</cite> out of its containing block (the nearest parent node which has its <tt>position</tt> CSS property equal to <tt>"absolute"</tt> or <tt>"relative"</tt>; </li> <li><i>"#clientSideId"</i>, where the clientSideId part is an arbitrary client-side element id – doesn't allow to move the <cite>PopupLayer</cite> out of the element with the specified id. </li> </ul> <h4><a name="PopupLayer2.x-CustomizingStyles"></a>Customizing Styles</h4> <p>You can customize a style for the <cite>PopupLayer</cite> component in the normal and rollover states using the <b>style</b> and <b>styleClass</b> and the <b>rolloverStyle</b> and <b>rolloverClass</b> attributes respectively.</p> <h4><a name="PopupLayer2.x-ClientSideEvents"></a>Client-Side Events</h4> <p>The <cite>PopupLayer</cite> component supports a set of standard client-side events such as <b>onclick</b>, <b>ondblclick</b>, <b>onmousedown</b>, <b>onmouseover</b>, <b>onmouseup</b>, <b>onmouseout</b>, <b>onmousemove</b>, <b>onkeydown</b>, <b>onkeypress</b>, <b>onkeyup</b>.</p> <blockquote> <img src="/images/icons/emoticons/warning.gif" width="16" height="16" align="absmiddle" alt="" border="0"> Note that the keyboard events such as <b>onkeydown</b>, <b>onkeypress</b>, and <b>onkeyup</b> are fired only if the <cite>PopupLayer</cite> component contains elements that provide these events, for example <cite>HTMLInputText</cite> . </blockquote> <p>In addition, it provides a number of component-specific client-side events:</p> <ul> <li><b>onshow</b> - Occurs when the <cite>PopupLayer</cite> component is displayed on the client side.</li> <li><b>onhide</b> - Occurs when the <cite>PopupLayer</cite> component is hidden on the client side.</li> <li><b>ondragstart</b> - Occurs when the user starts dragging the <cite>PopupLayer</cite> component.</li> <li><b>ondragend</b> - Occurs when user finishes dragging the <cite>PopupLayer</cite> component.</li> </ul> <h4><a name="PopupLayer2.x-ClientSideAPI"></a>Client-Side API</h4> <p>All client-side API methods are listed in the following table:</p> <div class="table-wrap"> <table class="confluenceTable"> <tbody> <tr> <th class="confluenceTh"> Method</th> <th class="confluenceTh"> Description</th> </tr> <tr> <td class="confluenceTd"><tt>show()</tt></td> <td class="confluenceTd"> Makes the <cite>PopupLayer</cite> component visible. This method is described in the <a href="#PopupLayer2.x-BasicConfiguration">Basic Configuration</a> section. </td> </tr> <tr> <td class="confluenceTd"><tt>showAtXY(x, y)</tt></td> <td class="confluenceTd"> Shows the <cite>PopupLayer</cite> component at the specified absolute <font color="orange">x</font> and <b>y</b> coordinates </td> </tr> <tr> <td class="confluenceTd"><tt>showCentered()</tt></td> <td class="confluenceTd"> Shows the <cite>PopupLayer</cite> component in the center of the browser window. </td> </tr> <tr> <td class="confluenceTd"><tt>hide()</tt></td> <td class="confluenceTd"> Hides the <cite>PopupLayer</cite> component.</td> </tr> <tr> <td class="confluenceTd"><tt>setLeft(x)</tt></td> <td class="confluenceTd"> Sets the x coordinate that will be used by the <tt>show()</tt> function.</td> </tr> <tr> <td class="confluenceTd"><tt>setTop(y)</tt></td> <td class="confluenceTd"> Sets the y coordinate that will be used by the <tt>show()</tt> function.</td> </tr> <tr> <td class="confluenceTd"><tt>isVisible()</tt></td> <td class="confluenceTd"> Returns <i>true</i> if the <cite>PopupLayer</cite> is visible.</td> </tr> <tr> <td class="confluenceTd"><tt>getLeft()</tt></td> <td class="confluenceTd"> Returns the <tt>x</tt> coordinate of the top-left corner of the <cite>PopupLayer</cite> in pixels. </td> </tr> <tr> <td class="confluenceTd"><tt>getTop()</tt></td> <td class="confluenceTd"> Returns the <tt>y</tt> coordinate of the top-left corner of the <cite>PopupLayer</cite> in pixels. </td> </tr> </tbody> </table> </div> </div> (markdown)