From richfaces-svn-commits at lists.jboss.org Thu Sep 10 09:39:11 2009 Content-Type: multipart/mixed; boundary="===============2803053979080073302==" MIME-Version: 1.0 From: richfaces-svn-commits at lists.jboss.org To: richfaces-svn-commits at lists.jboss.org Subject: [richfaces-svn-commits] JBoss Rich Faces SVN: r15525 - branches/community/3.3.X/docs/userguide/en/src/main/docbook/included. Date: Thu, 10 Sep 2009 09:39:11 -0400 Message-ID: <200909101339.n8ADdBdV024304@svn01.web.mwc.hst.phx2.redhat.com> --===============2803053979080073302== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Author: atsebro Date: 2009-09-10 09:39:11 -0400 (Thu, 10 Sep 2009) New Revision: 15525 Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ric= h_modalPanel.xml Log: RF-7804: Rich Output component group description review --> rich:modalPanel Modified: branches/community/3.3.X/docs/userguide/en/src/main/docbook/inclu= ded/rich_modalPanel.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ri= ch_modalPanel.xml 2009-09-10 11:58:32 UTC (rev 15524) +++ branches/community/3.3.X/docs/userguide/en/src/main/docbook/included/ri= ch_modalPanel.xml 2009-09-10 13:39:11 UTC (rev 15525) @@ -1,624 +1,519 @@
- - < - rich:modalPanel - > - <emphasis role=3D"since"> - <superscript> available since <emphasis role=3D"version">3.0.0</e= mphasis> - </superscript> - </emphasis> - -
- Description - The component implements a modal dialog window. All operations= in - the main application window are locked out while this window is active. - Opening and closing the window is done through client JavaScript - code. - -
- The <emphasis role=3D"bold"> - <property><rich:modalPanel></property> - </emphasis> component opens in closest to observer layer. = - All other layers are dimmed by blocking <code><div></code> elemen= t (gray on the picture). - - - - - - -
-
-
- Key Features - - - - Highly customizable look and feel - - - Support of draggable operations and size changes by you<= /para> - - - Easy positioning for the modal dialog window - - - Possibility to restore of the previous component state o= n a page (including position on the screen) after submitting and reloading<= /para> - - -
-
- Details of Usage - - The component is defined as a panel with some co= ntent inside that displays - its content as a modal dialog. To call it an= d to close it, the client - API for the window is used. - - - Functions description - - - - - Function - - Description - - - - - - Richfaces.showMod= alPanel (client - Id) - - Opens a window wi= th a specified client - Id - - - - Richfaces.hideMod= alPanel (client - Id) - - Closes a window w= ith a specified client - Id - - = - - Richfac= es.hideTopModalPanel () - = - Closes = the current visible window at the top - - - -
- - - Important: - To work properly the <rich:modalPan= el> should - always be placed outside the origi= nal <h:form> - and must include its own <h:for= m> for such - cases like performing submissions = from within the - <rich:modalPanel>. - - - Note: - In order to avoid a bug in IE, the roo= t node of the dialog is - moved on the top of a DOM tree. - - - - It's possible to add a - "header" - facet to the component to set th= e content for the - header. - - - - Example: - - Show ModalPanel + <rich:modalPanel> <emphasis role=3D"since"><superscript= > available since <emphasis role=3D"version">3.0.0</emphasis></superscript>= </emphasis> +
+ Description + + The component implements a modal window that blocks user= interaction with the main application while active. = + + = +
+ The <emphasis role=3D"bold"><property><rich:mo= dalPanel></property></emphasis> is opened in "closest" to an o= bserver layer. = + Other layers are dimmed by blocking <code><div&= gt;</code> (gray on the picture). + = + + + + + +
+
+ = +
+ Key Features + + + Easy positionable on th=D0=B5 screen + + + Resizable by end user + + = + Supports drag operations + + + Restores it's state including position after= submitting and reloading + + + Has customizable look and feel + + = +
+ = +
+ Details of Usage + = + + Important: + + + To work properly, the <= rich:modalPanel> should always be placed outside the original= <h:form>. = + For performing submits from within the <rich:modalPanel> it must include its own <h:form>. + + = + + In order to avoid a bug in IE, the root node of th= e dialog is moved on the top of a DOM tree. + + + = + + Position the <rich:= modalPanel> on the screen by specifying coordinate= s of it's top-left corner. = + Set values for "top" and "left" attributes in pixels for Y and X coordinates correspondingly. = + By default the component is autopositionable. + + = + + The modal window can be moved and resized by the end use= r. = + To disable those features (which are enabled by default)= set "moveable" = + and "resizeable" attributes to false. = + Resizing may be limited by specifying window's minimal s= izes with the "minWidth" and "minHeight" attri= butes. + + = + + To open and close the = <rich:modalPanel> use one of three JS API functions (offset to the "Reference Data&= quot; below in this chapter): = + + Show ModalPanel - - - - = -

The &lt;rich:modalPanel&gt; accepts different types of inform= ation: = - from simple text to iterative components such as &lt;rich:dataTable&= amp;gt;, etc. -

- Hide - + + Hid= e ModalPanel + ]]> - - Here is what happening on the page: - -
- - <emphasis role=3D"bold"> - <property><rich:modal= Panel></property> - </emphasis> with links - - - - - - -
- - A facet named - "controls" - can be added to the component to= place control elements on - a header. - - - - Example: - - Show ModalPanel - - - - - = - - - -

The &lt;rich:modalPanel&gt; accepts different types of inform= ation: = - from simple text to iterative components such as &lt;rich:dataTable&= amp;gt;, etc. -

- -]]> - - The result: - -
- - <emphasis role=3D"bold"> - <property><rich:modal= Panel></property> - </emphasis> with 'Close' control</= title> - - <mediaobject> - <imageobject> - <imagedata fileref=3D"im= ages/modalPanel3.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>To understand the sence of "<emphasis> - <property>domElementAttachment</pr= operty> - </emphasis>" attribute you should understand= the - <emphasis>stacking context</emphas= is> in the division - element (<code><div></code>) HTML make= up. Since each - positioned or z-indexed element (in CSS <cod= e>position: - absolute</code> or <code>relative<= /code> or <code>z-index: - [any integer value different from = 0]</code>) form their own - stacking context the <emphasis role=3D"bold"> - <property><rich:modalPanel><= /property> - </emphasis> nested into such element may be = overlapped with another - elements, which appear later in HTML hierarc= hy and assimilated with - basic stacking context (HTML <body>). = To make the panel - rendered in closest to the observer layer an= d avoid such overlapping, - the component was designed in way when it is= always being - automatically assimilated with <code><bod= y></code> and - with a very high rendering layer (<code>z-in= dex</code>). Due to some - side effects the <emphasis role=3D"bold"> - <property><rich:modalPanel><= /property> - </emphasis> should not always be assimilated= with - <code><body></code> stacking= context. The "<emphasis> - <property>domElementAttachment</pr= operty> - </emphasis>" attribute helps to reassign the= panel to it - '<emphasis>parent</emphasis>' or - '<emphasis>form</emphasis>' elemen= t. If - '<emphasis>form</emphasis>' is use= d and no - parent form is available the panel is functi= oning as if it is - assimilated with <code><body></code>. = </para> - - <note> - <title>Note: - If " - domElementAtta= chment - " value is not - 'body' then - some overlapping may occur. - - - To manage window placement relative to the compo= nent, there are - "left" - and - "top" - attributes defining a window shi= fting relative to the - top-left corner of the window. - - Modal windows can also support resize and move o= perations on the client - side. To allow or disallow these operations,= set the - "resizeable" - and - "moveable" - attributes to "true" or - "false" values. Window resizing is also limi= ted by - "minWidth" - and - "minHeight" - attributes specifying the minima= l window sizes. - Also you can use - "minWidth" - and - "minHeight" - attributes used as showMod= alPanel() arguments - in JavaScript options. - You can pass your parameters during modalPanel = opening or closing. This - passing could be performed in the following = way: - - - Example: - - - Thus, except the standard modalPanel parameters= you can pass any of your - own parameters. - Also modalPanel allows to handle its own openin= g and closing events on - the client side. The - "onshow" - attribute is used in this case. = - The following example shows how on the client s= ide to define opening and - closing event handling in such a way that yo= ur own parameters could - also be obtained: - - - Example: - - - - - Here, during modalPanel opening the value of a = passing parameter is - output. - More information about this problem could be fo= und on the RichFaces Development Forum. - There is a possibility to restore of the previo= us component state on a - page (including position on the screen) afte= r submitting and - reloading. The modalPanel has some special a= ttributes like - "showWhenRendered" - and - "keepVisualState" - . - - - "showWhenRendered" - - This boolean attribute is used= if modalPanel should be - rendered after first page loading. - - - "keepVisualState" - - Used if modalPanel should save= state after submission. - If keepVisualState=3D"true" then - parameters which modalPanel has during openi= ng should be submitted and - passed to new page. - - - Example: - - - Show]]> - - Here, if you open modal dialog window using cur= rent link and after - submits data then modalPanel destination and= height on new loaded page - is restored. - if you need the content of the modalPanel to be = submitted - you need to - remember two important rules: - - - modalPanel must have its own= form if it has form - elements (input or/and c= ommand components) inside - (as it was shown in the = example above) - - - modalPanel must not be inclu= ded into the form (on any - level up) if it has the = form inside. - - - Simple example of using commandButton within mod= alPanel is placed - below. - - Example: - - - - - - - - - - - - - + = + The result: + = +
+ + The panel is opened with "Richfaces.showModal= Panel();" JS API function. = + Clicking 'Hide ModalPanel' will call &qu= ot;Richfaces.hideModalPanel();" function. = + + + + + + +
+ = + + Besides client ID it is possible to pass other parameter= s while opening and closing the <rich:= modalPanel> with the JS API function. = + For example, you can pass top and left indents or panel = size: + + Show Mod= alPanel]]> + = + + Also the <rich:moda= lPanel> allows to handle its own opening and closi= ng events on the client side. = + Custom parameters passed with JS API are also obtained i= n this case: + + + ... ]]> - - - - See also discussion about this problem on the RichFaces Users Forum. - The - "label" - attribute is a generic attribute= . The - "label" - attribute provides an associatio= n between a component, and - the message that the component (indirectly) = produced. This attribute - defines the parameters of localized error an= d informational messages - that occur as a result of conversion, valida= tion, or other application - actions during the request processing lifecy= cle. With the help of this - attribute you can replace the last parameter= substitution token shown - in the messages. For example, {1} for - "DoubleRangeValidator.MAXIMU= M", - {2} for "ShortConverter.SHORT".= - In RichFaces Cookbook article about - Modal Panel there = is information for those of you who - would like to click on a details link in tab= le and have it show a - modal panel with information loaded from the= server. - = - - To avoid overlapping of the - <rich:modalPanel> - component on the page by any embed objects (inserted = with HTML <EMBED> tag) set the - "overlapEmbedObjects" - attribute to "true". - - = - = + = + = + + The component can restore it's previous state (including= position on the screen) after submitting and reloading. = + Set "keepVisualState" to true to submit and pass <rich:modalPanel> current para= meters to a new page. + The "showWhenRendered" bolean attribute is used in cases when component should = be rendered after first page loading. = + + = + + To understand sence of the "dom= ElementAttachment" attribute it is necessary to = understand = + what is stacking context and how it= works in the HTML makeup. = + Since each positioned or = z-indexed element (CSS position:absolute or r= elative and z-index:*any integer different from 0*) = + form their own stacking context the <rich:modalPanel> rendered as a c= hild of such element may be overlapped with an element = + that appears later in HTML hierarchy or assimilated with= <body> stacking context (basic for HTML page). = + Not so fast! + To make the <rich:m= odalPanel> rendered in "closest" to an o= bserver layer and avoid such overlapping, = + the component was designed in way when it is always bein= g automatically assimilated with <body> with a very high= rendering layer (z-index). = + But our panel should be assimilated with <body&= gt; not always, because of some side effects that take place in this= case. + The "domElementAttachment"= attribute helps to reassign the panel to it parent or form element. = + If form is used and no parent form = is available the panel is functioning as if it is assimilated with &l= t;body>. + + = + + Notes: + + If the "domElementAttachm= ent" value is not body then some ov= erlapping may occur. + + + To avoid overlapping by an embed object (inserted = with HTML <embed> tag) = + set the "overlapEmbedObje= cts" to true. + + + = + + The "label" attribute is a generic one. = + It provides an association between a component and messa= ge the component produces. = + This attribute defines 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 this attribute you can replace the last parameter s= ubstitution token shown in the message. = + For example, DoubleRangeValidator.MAXIMUM o= r ShortConverter.SHORT. + + = + + The <rich:modalPane= l> supports two facets. = + The header facet defines header and text la= bel on it: + + + + + +

The accepts different types of information: fro= m simple text to iterative components such as , etc. +

+ Hide Moda= lPanel + +...]]> + = + The result: +
+ + The <emphasis role=3D"bold"><property><rich:mod= alPanel></property></emphasis> with header. + = + + + + + +
+ = + + The controls facet places any control on a = header, defines image, style and function for it. For example, "Close&= quot; control: + + + ... + + + + ... +]]> + = + The result: +
+ + The <emphasis role=3D"bold"><property><rich:mod= alPanel></property></emphasis> with "Close" control. + + + + + + +
+ = + + An example of using &l= t;h:commandButton> within the <rich: modalPanel>: + + + + + + + +]]> + = +
+ = +
+ Reference Data + + Table of <= ;rich:modalPanel> attributes. + + = + + Component Identification Parameters + + + + Name + Value + + + + + component-type + org.richfaces.ModalPanel + + + component-class + org.richfaces.component.html.Ht= mlModalPanel + + + component-family + org.richfaces.ModalPanel + + + renderer-type + org.richfaces.ModalPanelRendere= r + + + tag-class + org.richfaces.taglib.ModalPanel= Tag + + + +
+ = + + JavaScript API functions + + + + Function = = + Description + + = + + + Richfaces.showModalPanel('ID'); = + Opens the modal panel with specifi= ed ID + + + Richfaces.hideModalPanel('ID'); = + Closes the modal panel with specif= ied ID + + + Richfaces.hideTopModalPanel('ID');= + Closes the current top visible mod= al panel with specified ID + + + +
+ = + + Facets + + + + Facet + Description + + + + + header + Defines header content + + + controls + Defines a control on the header= + + + +
+ = + + Style classes (selectors) and mapped skin paramet= ers + + + + Class name (selector) + Description + Skin Parameter + CSS property + + + + + .rich-mpnl-body<= /entry> + Defines styles f= or modalPanel content + generalSizeFont + font-size + + + generalFamilyFont + font-family = = + + + generalTextColor + color = = + + + .rich-mpnl-conte= nt + Defines style fo= r modalPanel content area + generalBackgroundColor + background-color + + + panelBorderColor + border-color + + + .rich-mpnl-heade= r + Defines styles f= or modalPanel header + headerBackgroundColor + background-color + + + headerBackgroundColor + border-color + + + .rich-mpnl-shadow + Defines styles for a modalPanel= shadow + shadowBackgroundColor + background-color + + + .rich-mpnl-text<= /entry> + Defines styles f= or a wrapper <div> element of a header text + headerSizeFont + font-size + + + headerWeightFont + font-weight + + + headerFamilyFont + font-family + + + headerTextColor + color + + + +
+ = + = + + Internal style classes (selectors) + + + + Class name (selector) + Description + + + + + .rich-modalpanel + Defines styles for a wrapper <= ;div> element of a modalPanel + + + .rich-mpnl-body + Defines styles for modalPanel c= ontent + + + .rich-mpnl-button + Defines styles for modalPanel bu= tton + = + + .rich-mpnl-controls + Defines styles for a wrapper <= ;div> element of a modalPanel control + + + .rich-mpnl-header-cell + Defines styles for a header cell= + + + .rich-mpnl-header + Defines styles for modalPanel h= eader + + + .rich-mpnl-iframe + Defines styles for modalPanel &l= t;iframe> container + + + .rich-mpnl-mask-div + Defines styles for blocking <= div> element + + + .rich-mpnl-mask-div-opaque + Defines opacity for blocking <= ;div> element + + + .rich-mpnl-mask-div-transparent<= /entry> + Defines transparency for blockin= g <div> element + + + rich-mpnl-ovf-hd + Defines style for block element = content + + = + .rich-mpnl-panel + Defines styles for a modalPanel<= /entry> + = + + .rich-mpnl-trim + Defines styles for a modalPanel<= /entry> + + + .rich-mpnl-resizer + Defines styles for a wrapper <= ;div> where cursor changes it state for resizing + + + .rich-mpnl-shadow + Defines styles for a modalPanel = shadow + + = + = + + = + + +
+ = + + You can find all necessary information about style class= es redefinition in Definition of Custom Styl= e Classes section. + +
+ = +
+ Relevant Resources Links + + Visit ModalPanel page at = RichFaces Livedemo for examples of component usage and their sources. + + = + + Useful articles: + + = + + + + "ModalPanelWizards" — describes ho= w to create a wizard using <rich:modal= Panel> = + (the same in the RichFaces FAQ "section"); + + + = + + + "An Introduction To J= Boss RichFaces" — by Max Katz describes the way = + the <ri= ch:modalPanel> edits and saves changes for table e= ntries; + + + = + + + "How to do a detail view modalPanel in a table" describes how to load an information from a table to the modal pane= l; + + + = + + + "ModalPanelValidation" gives examples of= validation in the <rich:modalPanel>= ; (the same in the RichFaces UsersForum topic); + + + = + + + "RichFacesPleaseWaitBox" describes how t= o show "Please wait" box and block the input = + while an Ajax request is being processed usi= ng the combination of <a4j:status><= /property> and <rich:modalP= anel>; + + + = + + = + + If you have any questions or ideas regarding the <rich:modalPanel> te= ll about them at the RichFaces Users Forum. + = + = + =
-
- Reference Data - - Table of = - <rich:modalPanel> = - attributes. - - - Component Identification Parameters - - - - - Name - - Value - - - - - - component-type - - org.richfaces.Mod= alPanel - - - - component-class - - org.richfaces.com= ponent.html.HtmlModalPanel - - - - component-family<= /entry> - - org.richfaces.Mod= alPanel - - - - renderer-type - - org.richfaces.Mod= alPanelRenderer - - - - tag-class - - org.richfaces.tag= lib.ModalPanelTag - - - -
- - JavaScript API - - - - - Function - - Description - - - - - - - show() - Opens the corresp= onding modalPanel - - - - hide() - Closes the corres= ponding modalPanel - - - - -
- - Facets - - - - Facet - Description - - - - - header - Define the header= content - - - controls - Defines the contr= ol elements on the - header - - - -
- - Classes names that define a component= appearance - - - - - Class name - - Description - - - - - - rich-modalpanel - - Defines styles fo= r a wrapper - <div> element of a - modalPanel - - - - rich-mpnl-mask-di= v - - Defines styles fo= r a wrapper - <div> element of a= mask - - - - rich-mpnl_panel - - Defines styles fo= r a modalPanel - - - - rich-mp-container= - - Defines styles fo= r a modalPanel - container - - - - rich-mpnl-resizer= - - Defines styles fo= r a wrapper - <div> element of a= resizing - element - - - - rich-mpnl-shadow<= /entry> - - Defines styles fo= r a modalPanel - shadow - - - - rich-mp-content-t= able - - Defines styles fo= r a <table> - element of a modalPanel<= /entry> - - - - rich-mpnl-header<= /entry> - - Defines styles fo= r a modalPanel - header - - - - rich-mpnl-header-= cell - - Defines styles fo= r a header cell - - - - rich-mpnl-text - - Defines styles fo= r a wrapper - <div> element of a= header - text - - - - rich-mpnl-body - - Defines styles fo= r a content inside a - modalPanel - - - - rich-mpnl-control= s - - Defines styles fo= r a wrapper - <div> element of a= modalPanel - control - - - -
- You can find all necessary information about style classes redefini= tion in = - Definition of Custom Style Classes = - section. -
-
- Relevant Resources Links - Visit ModalPanel page at RichFaces Livedemo for examples - of component usage and their sources. - - Read the " An Introduction To = JBoss RichFaces" - tutorial by Max Katz to find out how the - <rich:modalPanel><= /property> - helps to edit and save changes f= or table entries. - - Some articles at JBoss portal describing differe= nt aspects of - <rich:modalPanel><= /property> - usage: - - - - "ModalPanelWizards" article - describes how to create = a typical wizard with the - help of - <rich:modal= Panel> - component (t= he same could also be - found in the " H= ow to organize wizards using the - <rich:modalPanel> - component?" chap= ter of RichFaces - FAQ guide); - - - Refer to the "How to do a detail view moda= lPanel in a - table" article i= n the RichFaces cookbook at JBoss Portal to find out how to - build a table with detai= ls link clicking on which - will display a modal pan= el with information loaded from the server. - - - "ModalPanelValidation" article - gives examples of valida= tion in - <rich:modal= Panel> - (the same in= the corresponding topic at RichFaces Users - Forum); - - - "RichFacesPleaseWaitBox" article - describes how to show a = "Please - wait" box and block the = input while the - Ajax request is being pr= ocessed using combination - of - <a4j:status= > - and - <rich:modal= Panel> - components. = - - - -
\ No newline at end of file --===============2803053979080073302==--