From richfaces-svn-commits at lists.jboss.org Sun Nov 28 18:10:44 2010
Content-Type: multipart/mixed; boundary="===============5160703214208830340=="
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: r20203 -
modules/docs/trunk/Component_Reference/src/main/docbook/en-US.
Date: Sun, 28 Nov 2010 18:10:44 -0500
Message-ID: <201011282310.oASNAipE000568@svn01.web.mwc.hst.phx2.redhat.com>
--===============5160703214208830340==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Author: SeanRogers
Date: 2010-11-28 18:10:43 -0500 (Sun, 28 Nov 2010)
New Revision: 20203
Modified:
modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Compo=
nent_Reference-Panels_and_containers.xml
Log:
Rearranged panels sections
Modified: modules/docs/trunk/Component_Reference/src/main/docbook/en-US/cha=
p-Component_Reference-Panels_and_containers.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
--- modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Comp=
onent_Reference-Panels_and_containers.xml 2010-11-28 14:57:39 UTC (rev 2020=
2)
+++ modules/docs/trunk/Component_Reference/src/main/docbook/en-US/chap-Comp=
onent_Reference-Panels_and_containers.xml 2010-11-28 23:10:43 UTC (rev 2020=
3)
@@ -101,158 +101,6 @@
=
-
-
- <rich:popupPanel>
-
- The <rich:popupPanel> component provides a pop=
-up panel or window that appears in front of the rest of the application. T=
he <rich:popupPanel> component functions either as=
a modal window which blocks interaction with the rest of the application w=
hile active, or as a non-modal window. It can be positioned on the screen, =
dragged to a new position by the user, and re-sized.
-
- =
-
- Basic usage
-
- The <rich:popupPanel> does not require any co=
mpulsory attributes, though certain use cases require different attributes.
-
-
- =
-
- Showing and hiding the pop-up
-
- If show=3D"true" then the pop-up panel will display when =
the page is first loaded.
-
-
- The <rich:popupPanel> component can be shown =
and hidden manually using the show() and hide() m=
ethods from the JavaScript API. These can be implemented using two differen=
t approaches:
-
-
-
-
- Using the <rich:componentControl> component=
. For details on the component, refer to .
-
-
-
-
- Using the rich:component function. For details on the f=
unction, refer to .
-
-
-
-
- For explicit referencing when using the functions, the component can b=
e given an id identifier. The component can, however, be=
referenced using other means, such as through a selector.
-
-
- demonstrates basic use of both the <rich:componen=
tControl> component and the rich:component functi=
on to show and hide the <rich:popupPanel> componen=
t.
-
-
- <rich:popupPanel> example
-
-
-
- Placement
-
- The <rich:popupPanel> component should usual=
ly be placed outside the original form, and include its own form if perform=
ing submissions. An exception to this is when using the domElement=
Attachment attribute, as described in .
-
-
-
- =
-
- Modal and non-modal panels
-
- By default, the <rich:popupPanel> appears as =
a modal window that blocks interaction with the other objects on the page. =
To implement a non-modal window instead, set modal=
=3D"false". This will allow interaction with other objects outside t=
he pop-up panel.
-
-
- =
-
- Size and positioning
-
- The pop-up panel can be both re-sized and re-positioned by the user. T=
he minimum possible size for the panel can be set with the minWith=
and minHeight attributes. These abilities can=
be deactivated by setting resizable or movable t=
o false as necessary.
-
-
-
- The pop-up panel can be automatically sized when it is shown if the autosized attribute is set to true.
-
-
- The <rich:popupPanel> component is usually re=
ndered in front of any other objects on the page. This is achieved by attac=
hing the component to the <body> element of the pa=
ge, and setting a very high "z-index" (the stack order=
of the object). This approach is taken because relatively-positioned eleme=
nts could still overlap the pop-up panel if they exist at higher levels of =
the DOM hierarchy, even if their z-index is less than th=
e <rich:popupPanel> component. However, to avoid f=
orm limitation of the pop-up panel on pages where no such elements exist, t=
he <rich:popupPanel> component can be reattached t=
o its original DOM element by setting domElemen=
tAttachment to either parent or form<=
/literal>.
-
-
- Embedded objects inserted into the HTML with the <embed> tag will typically be rendered in front of a=
<rich:popupPanel> component. The <ric=
h:popupPanel> component can be forcibly rendered in front of t=
hese objects by setting overlapEmbedObjects=3D"tru=
e".
-
-
- Using overlapEmbedObjects
-
- Due to the additional script processing required when using the overlapEmbedObjects attribute, applications can suffer from d=
ecreased performance. As such, overlapEmbedObjects shoul=
d only be set to true when <embed> tags are being used. Do not set it to true for appli=
cations that do not require it.
-
-
-
- =
-
- Contents of the pop-up
-
- The <rich:popupPanel> component can contai=
n any other rich component just like a normal panel.
-
-
- Contents of the <rich:popupPanel> component w=
hich are positioned relatively may be trimmed if they extend beyond the bor=
ders of the pop-up panel. For certain in-line controls this behavior may be=
preferable, but for other dynamic controls it could be undesirable. If the=
trimOverlayedElements attribute is set to fals=
e then child components will not be trimmed if they extend beyond=
the borders of the pop-up panel.
-
-
- =
-
- Header and controls
-
- A panel header and associated controls can be added to the &l=
t;rich:popupPanel> component through the use of facets. The header facet displays a title for the panel, and the controls facet can be customized to allow window controls suc=
h as a button for closing the pop-up. demonstrates the use of the fac=
ets.
-
-
- Header and controls
-
-
-
- Header and controls
-
-
-
-
-
-
- The <rich:popupPanel> component, rendere=
d with a title header and a button control for closing the pop-up.
-
-
-
-
-
-
-
- =
-
- Reference data
-
-
-
- component-type: org.richfaces.popu=
pPanel
-
-
-
-
- component-class: org.richfaces.com=
ponent.html.HtmlpopupPanel
-
-
-
-
- component-family: org.richfaces.po=
pupPanel
-
-
-
-
- renderer-type: org.richfaces.popup=
PanelRenderer
-
-
-
-
- tag-class: org.richfaces.taglib.po=
pupPanelTag
-
-
-
-
-
- =
<rich:accordion>
@@ -385,87 +233,75 @@
-
- =
-
-
- <rich:accordionItem>
-
- The <rich:accordionItem> component is a panel =
for use with the <rich:accordion> component. Refer=
to for details on the <rich:accordion> com=
ponent.
-
-
- A <rich:accordion> component containing=
three <rich:accordionItem> components
-
-
-
-
-
-
- A <rich:accordion> component containing thr=
ee <rich:accordionItem> components. Only the first=
panel is expanded.
-
-
-
-
=
-
- Basic usage
+
+
+ <rich:accordionItem>
- Basic usage of the <rich:accordionItem> compo=
nent requires the label attribute, which provides the te=
xt on the panel header. The panel header is all that is visible when the ac=
cordion item is collapsed.
+ The <rich:accordionItem> component is a panel=
for use with the <rich:accordion> component.
-
- Alternatively the header facet could be used in pla=
ce of the label attribute. This would allow for addition=
al styles and custom content to be applied to the tab.
-
-
=
-
- <rich:accordionItem> client-side events=
-
- In addition to the standard HTML events, the <rich:accordi=
onItem> component uses the client-side events common to all sw=
itchable panel items:
-
-
-
-
- The onenter event points to the function to perfo=
rm when the mouse enters the panel.
-
-
-
-
- The onleave attribute points to the function to p=
erform when the mouse leaves the panel.
-
-
-
-
+
+ Basic usage
+
+ Basic usage of the <rich:accordionItem> comp=
onent requires the label attribute, which provides the t=
ext on the panel header. The panel header is all that is visible when the a=
ccordion item is collapsed.
+
+
+ Alternatively the header facet could be used in pl=
ace of the label attribute. This would allow for additio=
nal styles and custom content to be applied to the tab.
+
+
=
-
- Reference data
-
-
-
- component-type: org.richfaces.acco=
rdionItem
-
-
-
-
- component-class: org.richfaces.com=
ponent.html.HtmlAccordionItem
-
-
-
-
- component-family: org.richfaces.ac=
cordionItem
-
-
-
-
- renderer-type: org.richfaces.accor=
dionItemRenderer
-
-
-
-
- tag-class: org.richfaces.taglib.ac=
cordionItemTag
-
-
-
+
+ <rich:accordionItem> client-side event=
s
+
+ In addition to the standard HTML events, the <rich:accord=
ionItem> component uses the client-side events common to all s=
witchable panel items:
+
+
+
+
+ The onenter event points to the function to perf=
orm when the mouse enters the panel.
+
+
+
+
+ The onleave attribute points to the function to =
perform when the mouse leaves the panel.
+
+
+
+
+ =
+
+ Reference data
+
+
+
+ component-type: org.richfaces.acc=
ordionItem
+
+
+
+
+ component-class: org.richfaces.co=
mponent.html.HtmlAccordionItem
+
+
+
+
+ component-family: org.richfaces.a=
ccordionItem
+
+
+
+
+ renderer-type: org.richfaces.acco=
rdionItemRenderer
+
+
+
+
+ tag-class: org.richfaces.taglib.a=
ccordionItemTag
+
+
+
+
+ =
=
@@ -617,128 +453,152 @@
=
=
-
-
- <rich:tab>
+
+
+ <rich:popupPanel>
- The <rich:tab> component represents an individ=
ual tab inside a <rich:tabPanel> component, includ=
ing the tab's content. Clicking on the tab header will bring its correspond=
ing content to the front of other tabs. Refer to for details on the <=
sgmltag><rich:tabPanel> component.
+ The <rich:popupPanel> component provides a pop=
-up panel or window that appears in front of the rest of the application. T=
he <rich:popupPanel> component functions either as=
a modal window which blocks interaction with the rest of the application w=
hile active, or as a non-modal window. It can be positioned on the screen, =
dragged to a new position by the user, and re-sized.
=
-
- A <rich:tabPanel> component containing =
three <rich:tab> components
-
-
-
-
-
+
+ Basic usage
+
+ The <rich:popupPanel> does not require any co=
mpulsory attributes, though certain use cases require different attributes.
+
+
+ =
+
+ Showing and hiding the pop-up
+
+ If show=3D"true" then the pop-up panel will display when =
the page is first loaded.
+
+
+ The <rich:popupPanel> component can be shown =
and hidden manually using the show() and hide() m=
ethods from the JavaScript API. These can be implemented using two differen=
t approaches:
+
+
+
- A <rich:tabPanel> component containing thre=
e <rich:tab> components.
+ Using the <rich:componentControl> component=
. For details on the component, refer to .
-
-
-
+
+
+
+ Using the rich:component function. For details on the f=
unction, refer to .
+
+
+
+
+ For explicit referencing when using the functions, the component can b=
e given an id identifier. The component can, however, be=
referenced using other means, such as through a selector.
+
+
+ demonstrates basic use of both the <rich:componen=
tControl> component and the rich:component functi=
on to show and hide the <rich:popupPanel> componen=
t.
+
+
+ <rich:popupPanel> example
+
+
+
+ Placement
+
+ The <rich:popupPanel> component should usual=
ly be placed outside the original form, and include its own form if perform=
ing submissions. An exception to this is when using the domElement=
Attachment attribute, as described in .
+
+
+
=
-
- Basic usage
+
+ Modal and non-modal panels
- Basic usage of the <rich:tab> component requi=
res the name attribute to uniquely identify the tab with=
in the parent <rich:tabPanel> component. As the ta=
bs are switched, the name identifier of the currently se=
lected tab is stored in the activeItem attribute of the =
parent <rich:tabPanel> component.
+ By default, the <rich:popupPanel> appears as =
a modal window that blocks interaction with the other objects on the page. =
To implement a non-modal window instead, set modal=
=3D"false". This will allow interaction with other objects outside t=
he pop-up panel.
-
-
- Header labeling
+ =
+
+ Size and positioning
- In addition to the name identifier, the he=
ader attribute must be defined. The header att=
ribute provides the text on the tab header. The content of the tab is then =
detailed inside the <rich:tab> tags.
+ The pop-up panel can be both re-sized and re-positioned by the user. T=
he minimum possible size for the panel can be set with the minWith=
and minHeight attributes. These abilities can=
be deactivated by setting resizable or movable t=
o false as necessary.
+
- Alternatively, the header facet could be used in pl=
ace of the header attribute. This would allow for additi=
onal styles and custom content to be applied to the tab. The component also=
supports three facets to customize the appearance depending on the current=
state of the tab:
+ The pop-up panel can be automatically sized when it is shown if the autosized attribute is set to true.
-
-
- headerActive facet
-
-
- This facet is used when the tab is the currently active tab.
-
-
-
-
- headerInactive facet
-
-
- This facet is used when the tab is not currently active.
-
-
-
-
- headerDisabled facet
-
-
- This facet is used when the tab is disabled.
-
-
-
-
- The header facet is used in place of any state-base=
d facet that has not been defined.
+ The <rich:popupPanel> component is usually re=
ndered in front of any other objects on the page. This is achieved by attac=
hing the component to the <body> element of the pa=
ge, and setting a very high "z-index" (the stack order=
of the object). This approach is taken because relatively-positioned eleme=
nts could still overlap the pop-up panel if they exist at higher levels of =
the DOM hierarchy, even if their z-index is less than th=
e <rich:popupPanel> component. However, to avoid f=
orm limitation of the pop-up panel on pages where no such elements exist, t=
he <rich:popupPanel> component can be reattached t=
o its original DOM element by setting domElemen=
tAttachment to either parent or form<=
/literal>.
+
+ Embedded objects inserted into the HTML with the <embed> tag will typically be rendered in front of a=
<rich:popupPanel> component. The <ric=
h:popupPanel> component can be forcibly rendered in front of t=
hese objects by setting overlapEmbedObjects=3D"tru=
e".
+
+
+ Using overlapEmbedObjects
+
+ Due to the additional script processing required when using the overlapEmbedObjects attribute, applications can suffer from d=
ecreased performance. As such, overlapEmbedObjects shoul=
d only be set to true when <embed> tags are being used. Do not set it to true for appli=
cations that do not require it.
+
+
=
-
- Switching tabs
+
+ Contents of the pop-up
- The switching mode for performing submissions can be inherited from th=
e switchType attribute of the parent <rich:t=
abPanel> component, or set individually for each <=
rich:tab> component. Refer to for details on the switchType attribute.
+ The <rich:popupPanel> component can contai=
n any other rich component just like a normal panel.
- An individual tab can be disabled by setting disabled=
varname>=3D"true". Disabled tabs cannot be activated or switched to.
+ Contents of the <rich:popupPanel> component w=
hich are positioned relatively may be trimmed if they extend beyond the bor=
ders of the pop-up panel. For certain in-line controls this behavior may be=
preferable, but for other dynamic controls it could be undesirable. If the=
trimOverlayedElements attribute is set to fals=
e then child components will not be trimmed if they extend beyond=
the borders of the pop-up panel.
=
-
- <rich:tab> client-side events
+
+ Header and controls
- In addition to the standard HTML events, the <rich:tab>=
component uses the client-side events common to all switchable p=
anel items:
+ A panel header and associated controls can be added to the &l=
t;rich:popupPanel> component through the use of facets. The header facet displays a title for the panel, and the controls facet can be customized to allow window controls suc=
h as a button for closing the pop-up. demonstrates the use of the fac=
ets.
-
-
-
- The onenter event points to the function to perfo=
rm when the mouse enters the tab.
-
-
-
-
- The onleave attribute points to the function to p=
erform when the mouse leaves the tab.
-
-
-
+
+ Header and controls
+
+
+
+ Header and controls
+
+
+
+
+
+
+ The <rich:popupPanel> component, rendere=
d with a title header and a button control for closing the pop-up.
+
+
+
+
+
+
=
-
+ Reference data
- component-type: org.richfaces.tab<=
/classname>
+ component-type: org.richfaces.popu=
pPanel
- component-class: org.richfaces.com=
ponent.html.HtmlTab
+ component-class: org.richfaces.com=
ponent.html.HtmlpopupPanel
- component-family: org.richfaces.ta=
b
+ component-family: org.richfaces.po=
pupPanel
- renderer-type: org.richfaces.tabRe=
nderer
+ renderer-type: org.richfaces.popup=
PanelRenderer
- tag-class: org.richfaces.taglib.ta=
bTag
+ tag-class: org.richfaces.taglib.po=
pupPanelTag
@@ -964,71 +824,123 @@
-
- =
-
-
- <rich:toggleControl>
-
- The <rich:toggleControl> behavior can be attac=
hed to any interface component. It works with a <rich:togglePan=
el> component to switch between different <rich:to=
gglePanelItem> components.
-
-
- Refer to and for details on how to use the compon=
ents together.
-
=
-
- Basic usage
+
+
+ <rich:tab>
- The <rich:toggleControl> can be used to switc=
h through <rich:togglePanelItem> components in a <=
sgmltag><rich:togglePanel> container. If the <r=
ich:toggleControl> component is positioned inside a &=
lt;rich:togglePanel> component, no attributes need to be defin=
ed, as the control is assumed to switch through the <rich:toggl=
ePanelItem> components of its parent.
+ The <rich:tab> component represents an indivi=
dual tab inside a <rich:tabPanel> component, inclu=
ding the tab's content. Clicking on the tab header will bring its correspon=
ding content to the front of other tabs.
-
- A <rich:toggleControl> component can be locat=
ed outside the <rich:togglePanel> component it nee=
ds to switch. Where this is the case, the <rich:togglePanel>=
is identified using the activePanel attribute=
. the Cycling through components requires the for attri=
bute, which points to the id identifier of the =
<rich:togglePanel> that it controls.
-
-
+ =
+
+ Basic usage
+
+ Basic usage of the <rich:tab> component requ=
ires the name attribute to uniquely identify the tab wit=
hin the parent <rich:tabPanel> component. As the t=
abs are switched, the name identifier of the currently s=
elected tab is stored in the activeItem attribute of the=
parent <rich:tabPanel> component.
+
+
+
+
+ Header labeling
+
+ In addition to the name identifier, the h=
eader attribute must be defined. The header at=
tribute provides the text on the tab header. The content of the tab is then=
detailed inside the <rich:tab> tags.
+
+
+ Alternatively, the header facet could be used in p=
lace of the header attribute. This would allow for addit=
ional styles and custom content to be applied to the tab. The component als=
o supports three facets to customize the appearance depending on the curren=
t state of the tab:
+
+
+
+ headerActive facet
+
+
+ This facet is used when the tab is the currently active tab.
+
+
+
+
+ headerInactive facet
+
+
+ This facet is used when the tab is not currently active.
+
+
+
+
+ headerDisabled facet
+
+
+ This facet is used when the tab is disabled.
+
+
+
+
+
+ The header facet is used in place of any state-bas=
ed facet that has not been defined.
+
+
=
-
- Specifying the next state
-
- The <rich:toggleControl> component will cycle=
through <rich:togglePanelItem> components in the =
order they are defined within the view. However, the next item to switch to=
can be explicitly defined by including a <rich:toggleControl&g=
t; component within a <rich:togglePanelItem> and using the targetItem attribute. The ta=
rgetItem attribute points to the <rich:togglePanelIte=
m> to switch to when the state is next changed. demonstrates how to specify the next switchable state in this way.
-
-
- <rich:toggleControl> example
-
-
-
+
+ Switching tabs
+
+ The switching mode for performing submissions can be inherited from t=
he switchType attribute of the parent <rich:=
tabPanel> component, or set individually for each <=
;rich:tab> component. Refer to for details on the switchType attribute.
+
+
+ An individual tab can be disabled by setting disabled<=
/varname>=3D"true". Disabled tabs cannot be activated or switched to.
+
+
=
-
- Reference data
-
-
-
- component-type: org.richfaces.Togg=
leControl
-
-
-
-
- component-class: org.richfaces.com=
ponent.html.HtmlToggleControl
-
-
-
-
- component-family: org.richfaces.To=
ggleControl
-
-
-
-
- renderer-type: org.richfaces.Toggl=
eControlRenderer
-
-
-
-
- tag-class: org.richfaces.taglib.To=
ggleControlTag
-
-
-
+
+ <rich:tab> client-side events
+
+ In addition to the standard HTML events, the <rich:tab>=
; component uses the client-side events common to all switchable =
panel items:
+
+
+
+
+ The onenter event points to the function to perf=
orm when the mouse enters the tab.
+
+
+
+
+ The onleave attribute points to the function to =
perform when the mouse leaves the tab.
+
+
+
+
+ =
+
+ Reference data
+
+
+
+ component-type: org.richfaces.tab=
+
+
+
+
+ component-class: org.richfaces.co=
mponent.html.HtmlTab
+
+
+
+
+ component-family: org.richfaces.t=
ab
+
+
+
+
+ renderer-type: org.richfaces.tabR=
enderer
+
+
+
+
+ tag-class: org.richfaces.taglib.t=
abTag
+
+
+
+
+ =
-
+ =
<rich:togglePanel>
@@ -1115,48 +1027,109 @@
-
- =
-
-
- <rich:togglePanelItem>
-
- The <rich:togglePanelItem> component is a swit=
chable panel for use with the <rich:togglePanel> c=
omponent. Switching between <rich:togglePanelItem>=
components is handled by the <rich:toggleControl>=
behavior.
-
-
- Refer to and for details on how to use the componen=
ts together.
-
=
-
- Reference data
-
-
-
- component-type: org.richfaces.Togg=
lePanelItem
-
-
-
-
- component-class: org.richfaces.com=
ponent.html.HtmlTogglePanelItem
-
-
-
-
- component-family: org.richfaces.To=
gglePanelItem
-
-
-
-
- renderer-type: org.richfaces.Toggl=
ePanelItemRenderer
-
-
-
-
- tag-class: org.richfaces.taglib.To=
gglePanelItemTag
-
-
-
+
+
+ <rich:toggleControl>
+
+ The <rich:toggleControl> behavior can be atta=
ched to any interface component. It works with a <rich:togglePa=
nel> component to switch between different <rich:t=
ogglePanelItem> components.
+
+
+ Refer to and for details on how to use the compo=
nents together.
+
+ =
+
+ Basic usage
+
+ The <rich:toggleControl> can be used to swit=
ch through <rich:togglePanelItem> components in a =
<rich:togglePanel> container. If the <=
rich:toggleControl> component is positioned inside a =
<rich:togglePanel> component, no attributes need to be defi=
ned, as the control is assumed to switch through the <rich:togg=
lePanelItem> components of its parent.
+
+
+ A <rich:toggleControl> component can be loca=
ted outside the <rich:togglePanel> component it ne=
eds to switch. Where this is the case, the <rich:togglePanel>=
; is identified using the activePanel attribut=
e. the Cycling through components requires the for attr=
ibute, which points to the id identifier of the <rich:togglePanel> that it controls.
+
+
+ =
+
+ Specifying the next state
+
+ The <rich:toggleControl> component will cycl=
e through <rich:togglePanelItem> components in the=
order they are defined within the view. However, the next item to switch t=
o can be explicitly defined by including a <rich:toggleControl&=
gt; component within a <rich:togglePanelItem> and using the targetItem attribute. The t=
argetItem attribute points to the <rich:togglePanelIt=
em> to switch to when the state is next changed. demonstrates how to specify the next switchable state in this way.
+
+
+ <rich:toggleControl> example
+