11:24 a.m.
Author: vkorluzhenko
Date: 2007-12-18 12:24:46 -0500 (Tue, 18 Dec 2007)
New Revision: 4903
Modified:
branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.desc.xml
branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.xml
branches/3.1.x/docs/userguide/en/src/main/resources/images/contextMenu1.png
branches/3.1.x/docs/userguide/en/src/main/resources/images/contextMenu_attached.png
branches/3.1.x/docs/userguide/en/src/main/resources/images/contextMenu_classes.png
Log:
http://jira.jboss.com/jira/browse/RF-1298 - rewrote description.
Modified: branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.desc.xml
===================================================================
---
branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.desc.xml 2007-12-18
16:54:49 UTC (rev 4902)
+++
branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.desc.xml 2007-12-18
17:24:46 UTC (rev 4903)
@@ -21,10 +21,11 @@
<section>
<title>Key Features</title>
<itemizedlist>
- <listitem>Skinnable <property>context menu</property> and
child items</listitem>
- <listitem>Highly customizable look and feel</listitem>
+ <listitem>Highly customizable look and feel</listitem>
+ <listitem>"oncontextmenu" event
support</listitem>
<listitem>Disablement support</listitem>
<listitem>Pop-up appearance event customization</listitem>
+ <listitem>Usage of shared instance of a menu on a
page</listitem>
</itemizedlist>
</section>
</section>
Modified: branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.xml
===================================================================
--- branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.xml 2007-12-18
16:54:49 UTC (rev 4902)
+++ branches/3.1.x/docs/userguide/en/src/main/docbook/included/contextMenu.xml 2007-12-18
17:24:46 UTC (rev 4903)
@@ -46,12 +46,7 @@
<emphasis role="bold">Example:</emphasis>
</para>
<programlisting role="XML"><![CDATA[...
-<h:panelGroup id="MyGroup">
- <!-- Panel Content-->
- <rich:contextMenu id="Menu1">
- <!--Nested menu components-->
- </rich:contextMenu>
-</h:panelGroup>
+<rich:contextMenu event="oncontextmenu" attached="true">
...]]></programlisting>
</section>
<section>
@@ -68,71 +63,197 @@
<title>Details of Usage</title>
<para>
<emphasis role="bold">
- <property><rich:contexMenu></property>
- </emphasis> is a support-like component. It is possible to define it as
a child to some component
- and specify some events that trigger the menu.
- </para>
+ <property><rich:contextMenu></property>
+ </emphasis> is a support-like component. Context menu itself is an
invisible panel that
+ appears after a particular client side event (onmouseover, onclick, etc)
occured on a
+ parent component. The event is defined with an <emphasis>
+ <property>"event"</property>
+ </emphasis> attribute. The component uses <emphasis>
+ <property>"oncontextmenu"</property>
+ </emphasis> event by default to call a context menu by clicking on the
right mouse
+ button.</para>
+
+ <para><property>
+ <link
linkend="menuGroup"><rich:menuGroup></link>
+ </property>, <property>
+ <link
linkend="menuItem"><rich:menuItem></link>
+ </property> and <property>
+ <link
linkend="menuSeparator"><rich:menuSeparator></link>
+ </property> components are used as nested elements for <emphasis
role="bold">
+ <property><rich:contextMenu></property>
+ </emphasis>in the same way as for <emphasis
role="bold">
+ <property><rich:dropDownMenu></property>
+ </emphasis>. </para>
+
+ <para>If a value of the <emphasis>
+ <property>"attached"</property>
+ </emphasis> attribute is defined as
<property>"true"</property>,
+ component is attached to the parent component. An example is placed
below.</para>
<para>
- The
<emphasis><property>"attached"</property></emphasis>
attribute defines the state of the component.
- If the value of the
<emphasis><property>"attached"</property></emphasis>
attribute is true,
- component is attached to parent component.
+ <emphasis role="bold">Example:</emphasis>
</para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
<programlisting role="XML"><![CDATA[...
-<rich:dataTable id="table" value="#{bean.model}"
var="row" rows="5">
- <rich:column>
- <f:facet name="header">
- <h:outputText value="Packages" />
- </f:facet>
- <h:outputText value="#{row.first}" />
- <rich:contextMenu id="Menu1" attached="true">
- <rich:menuItem value="Edit package"
action="#{bean.create}" />
- <rich:menuItem value="Delete package"
action="#{bean.edit}" />
- </rich:contextMenu>
- </rich:column>
-</rich:dataTable>
+ <h:panelGrid columns="1" columnClasses="cent">
+ <h:panelGroup id="picture">
+ <h:graphicImage
value="/richfaces/jQuery/images/pic1.jpg" id="pic"/>
+ <rich:contextMenu event="oncontextmenu"
attached="true" submitMode="none">
+ <rich:menuItem value="Zoom In"
onclick="enlarge();" id="zin"></rich:menuItem>
+ <rich:menuItem value="Zoom Out"
onclick="decrease();" id="zout"></rich:menuItem>
+ </rich:contextMenu>
+ </h:panelGroup>
+ </h:panelGrid>
...]]></programlisting>
- <para>
- If the value of the
<emphasis><property>"attached"</property></emphasis>
attribute is false,
- component activates by JavaScript API or with assistance of <emphasis
role="bold"><property><rich:componentControl></property></emphasis>.
+ <para>The <property>"enlarge()"</property>
and
+ <property>"decrease()"</property> functions
definition is placed
+ below.</para>
+ <programlisting role="JAVA"><![CDATA[...
+ <script type="text/javascript">
+ function enlarge(){
+
document.getElementById('pic').width=document.getElementById('pic').width*1.1;
+
document.getElementById('pic').height=document.getElementById('pic').height*1.1;
+ }
+ function decrease(){
+
document.getElementById('pic').width=document.getElementById('pic').width*0.9;
+
document.getElementById('pic').height=document.getElementById('pic').height*0.9;
+ }
+ </script>
+...]]></programlisting>
+
+ <para>In the example a picture zooming possibility with <emphasis
role="bold">
+ <property><rich:contextMenu></property>
+ </emphasis> component usage was shown. The picture is placed on the
<emphasis
+ role="bold">
+ <property><h:panelGroup></property>
+ </emphasis> component. The <emphasis role="bold">
+ <property><rich:contextMenu></property>
+ </emphasis> component is defined as nested to <emphasis
role="bold">
+ <property><h:panelGroup></property>
+ </emphasis> one and has a value of the<emphasis>
+ <property>"attached"</property>
+ </emphasis> attribute defined as
<property>"true"</property>. Thus,
+ the context menu is attached to the parent component. The context menu has
two items to
+ zoom in (zoom out) a picture by
<property>"onclick"</property> event.
+ For earch item corresponding JavaScript function is defined to provide
necessary action
+ as a result of the clicking on it. For the menu is defined an
<emphasis>
+ <property>"oncontextmenu"</property>
+ </emphasis> event to call the context menu on a right click mouse
event.</para>
+
+ <para>In the example the context menu is defined for the parent
<emphasis role="bold">
+ <property><h:panelGroup></property>
+ </emphasis> component with a value of <emphasis>
+ <property>"id"</property>
+ </emphasis> attribute equal to
<property>"picture"</property>. You
+ should be careful with such definition, because a client context menu is
looked for a
+ DOM element with a client Id of a parent component on a server. If a parent
component
+ doesn't encode an Id on a client, it can't be found by the
<emphasis
+ role="bold">
+ <property><rich:contextMenu></property>
+ </emphasis> and it's attached to its closest parent in a DOM
tree.</para>
+
+ <para> If the <emphasis>
+ <property>"attached"</property>
+ </emphasis> attribute has
<property>"false"</property> value,
+ component activates via JavaScript API with assistance of <emphasis
role="bold">
+ <property><rich:componentControl></property>
+ </emphasis>. In this case there is no need to use <emphasis>
+ <property>"oncontextmenu"</property>
+ </emphasis> event. An example is placed below.</para>
+ <para id="ex">
+ <emphasis role="bold">Example:</emphasis>
</para>
- <para>
- <emphasis role="bold">Example:</emphasis>
- </para>
<programlisting role="XML"><![CDATA[...
-<rich:dataTable id="table" value="#{bean.model}"
var="row" rows="5">
- <rich:column id="c1">
- <f:facet name="header">
- <h:outputText value="Packages" />
- </f:facet>
- <h:outputText value="#{row.first}" />
- <rich:componentControl event="oncontextmenu" attachTo="c1"
for=":f:m" operation="Show">
- <f:param name="param" value="#{row.first}" />
- </rich:componentControl>
- </rich:column>
-</rich:dataTable>
-<rich:contextMenu id="Menu1" attached="false">
- <rich:menuItem value="Edit package" action="#{bean.edit}"
/>
- <rich:menuItem value="Delete package"
action="#{bean.delete}" />
- </rich:contextMenu>
+ <h:form id="form">
+ <rich:contextMenu attached="false" id="menu"
submitMode="ajax">
+ <rich:menuItem ajaxSingle="true">
+ <b>{car} {model}</b> details
+ <a4j:actionparam name="det"
assignTo="#{ddmenu.current}" value="{car} {model} details"/>
+ </rich:menuItem>
+ <rich:menuGroup value="Actions">
+ <rich:menuItem ajaxSingle="true">
+ Put <b>{car} {model}</b> To Basket
+ <a4j:actionparam name="bask"
assignTo="#{ddmenu.current}" value="Put {car} {model} To Basket"/>
+ </rich:menuItem>
+ <rich:menuItem value="Read Comments"
ajaxSingle="true">
+ <a4j:actionparam name="bask"
assignTo="#{ddmenu.current}" value="Read Comments"/>
+ </rich:menuItem>
+ <rich:menuItem ajaxSingle="true">
+ Go to <b>{car}</b> site
+ <a4j:actionparam name="bask"
assignTo="#{ddmenu.current}" value="Go to {car} site"/>
+ </rich:menuItem>
+ </rich:menuGroup>
+ </rich:contextMenu>
+
+ <h:panelGrid columns="2">
+ <rich:dataTable
value="#{dataTableScrollerBean.tenRandomCars}" var="car"
id="table"
+
onRowMouseOver="this.style.backgroundColor='#F8F8F8'"
+
onRowMouseOut="this.style.backgroundColor='#{a4jSkin.tableBackgroundColor}'"
rowClasses="cur">
+ <rich:column>
+ <f:facet
name="header">Make</f:facet>
+ <h:outputText
value="#{car.make}"/>
+ </rich:column>
+ <rich:column>
+ <f:facet
name="header">Model</f:facet>
+ <h:outputText
value="#{car.model}"/>
+ </rich:column>
+ <rich:column>
+ <f:facet
name="header">Price</f:facet>
+ <h:outputText value="#{car.price}"
/>
+ </rich:column>
+
+ <rich:componentControl event="onRowClick"
for="menu" operation="show">
+ <f:param value="#{car.model}"
name="model"/>
+ <f:param value="#{car.make}"
name="car"/>
+ </rich:componentControl>
+ </rich:dataTable>
+
+ <a4j:outputPanel ajaxRendered="true">
+ <rich:panel>
+ <f:facet name="header">Last Menu
Action</f:facet>
+ <h:outputText
value="#{ddmenu.current}"></h:outputText>
+ </rich:panel>
+ </a4j:outputPanel>
+ </h:panelGrid>
+ </h:form>
...]]></programlisting>
- <para>This is the result:</para>
+ <para>This is a result:</para>
<figure>
- <title>Using the
<emphasis><property>"attached"</property></emphasis>
attribute</title>
+ <title> </title>
<mediaobject>
<imageobject>
<imagedata fileref="images/contextMenu_attached.png"
scalefit="1"/>
</imageobject>
</mediaobject>
</figure>
- <para>
- The
<emphasis><property>"event"</property></emphasis>
attribute defines the event on the parent element
- that triggers the menu's appearance
(<property>oncontextmenu</property> by default).
- </para>
+
+ <para>In the example the context menu is activated (by clicking on the left
mouse button) on
+ the table via JavaScript API with assistance of <emphasis
role="bold">
+ <property><rich:componentControl></property>
+ </emphasis>. The attribute <emphasis>
+ <property>"for"</property>
+ </emphasis> contains a value of the <emphasis
role="bold">
+ <property><rich:contextMenu></property>
+ </emphasis> Id. For menu appearance Java Script API function
+ <property>"Show"</property> is used. It is
defined with <emphasis>
+ <property>"operation"</property>
+ </emphasis> attribute for the <emphasis role="bold">
+ <property><rich:componentControl></property>
+ </emphasis> component. Context menu is recreated after the every call
on a client and
+ new {car} and {model} values are inserted in it. In the example for a menu
customization
+ macrosubstitutions were used.</para>
+
<para>The <emphasis role="bold">
<property><rich:contextMenu></property>
+ </emphasis> component can be defined once on a page and can be used as
shared for
+ different components (this is the main difference from the <emphasis
role="bold">
+ <property><rich:dropDownMenu></property>
+ </emphasis> component). It's necessary to define it once on a
page (as it was
+ shown in the example <link linkend="ex">above</link>)
and activate it on required
+ components via JavaScript API with assistance of <emphasis
role="bold">
+ <property><rich:componentControl></property>
+ </emphasis>.</para>
+
+ <para>The <emphasis role="bold">
+ <property><rich:contextMenu></property>
</emphasis>
<emphasis>
<property>"submitMode"</property>
@@ -164,20 +285,16 @@
<property>"action"</property>
</emphasis> and <emphasis>
<property>"actionListener"</property>
- </emphasis> item's attributes are ignored. Menu items
don't fire any submits themselves.
- The behavior is fully defined by the components nested inside
items.</para>
+ </emphasis> item's attributes are ignored. Menu items
don't fire any submits
+ themselves. The behavior is fully defined by the components nested inside
items.</para>
<note><title>Note:</title> As the <emphasis
role="bold">
<property><rich:contextMenu></property>
</emphasis> component doesn't provide its own form, use it between
<h:form> and </h:form> tags.</note>
- <para><property><link
linkend="menuGroup"><rich:menuGroup></link></property>,
- <property><link
linkend="menuItem"><rich:menuItem></link></property>
- and <property><link
linkend="menuSeparator"><rich:menuSeparator></link></property>
- components is used as nested elements for <emphasis
role="bold"><property><rich:contextMenu></property></emphasis>.
- </para>
+
<!-- Will be done for latest version -->
<!--para> It's possible to define the direction for list appear in
the <emphasis>
<property>"direction"</property>
@@ -320,18 +437,18 @@
<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>
+ <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><rich:contextMenu></property>
- </emphasis> components at once: <itemizedlist>
- <listitem>Redefine the corresponding skin parameters</listitem>
- <listitem> Add to your style sheets style classes used by a
<emphasis role="bold">
<property><rich:contextMenu></property>
- </emphasis> component</listitem>
- </itemizedlist>
+ </emphasis> components at once: <itemizedlist>
+ <listitem>Redefine the corresponding skin
parameters</listitem>
+ <listitem> Add to your style sheets style classes used by a
<emphasis role="bold">
+
<property><rich:contextMenu></property>
+ </emphasis> component</listitem>
+ </itemizedlist>
</para>
</section>
<section>
@@ -385,20 +502,20 @@
</section>
<section>
<title>Definition of Custom Style Classes</title>
-
+
<para>On the screenshot there are classes names that define styles for
component elements.</para>
-
-
+
+
<figure>
<title>Style classes</title>
-
+
<mediaobject>
<imageobject>
<imagedata fileref="images/contextMenu_classes.png"
scalefit="1"/>
</imageobject>
</mediaobject>
</figure>
-
+
<table>
<title>Classes names that define the contextMenu element</title>
<tgroup cols="2">
@@ -419,29 +536,31 @@
</row>
<row>
<entry>rich-menu-list-strut</entry>
- <entry>Defines styles for a wrapper <div>
element for a strut of a popup list</entry>
+ <entry>Defines styles for a wrapper <div>
element for a strut
+ of a popup list</entry>
</row>
</tbody>
</tgroup>
</table>
<para>In order to redefine styles for all <emphasis
role="bold">
- <property><rich:contextMenu></property>
- </emphasis> components on a page using CSS, it's enough to create
classes with the same
+ <property><rich:contextMenu></property>
+ </emphasis> components on a page using CSS, it's enough to create
classes with the same
names and define necessary properties in them. </para>
<para>To change styles of particular <emphasis
role="bold">
- <property><rich:contextMenu></property>
- </emphasis> components, define your own style classes in the corresponding
<emphasis
- role="bold">
- <property><rich:contextMenu></property>
- </emphasis> component attributes.</para>
+ <property><rich:contextMenu></property>
+ </emphasis> components, define your own style classes in the
corresponding <emphasis
+ role="bold">
+ <property><rich:contextMenu></property>
+ </emphasis> component attributes.</para>
</section>
-
+
<section>
<title>Relevant Resources Links</title>
- <para><ulink
url="http://livedemo.exadel.com/richfaces-demo/richfaces/contextMenu...
- >Here</ulink> you can see an example of <emphasis
role="bold">
+ <para><ulink
+
url="http://livedemo.exadel.com/richfaces-demo/richfaces/contextMenu...
+ >Here</ulink> you can see an example of <emphasis
role="bold">
<property><rich:contextMenu></property>
</emphasis> usage and sources for the given example. </para>
</section>
-
+
</section>
Modified: branches/3.1.x/docs/userguide/en/src/main/resources/images/contextMenu1.png
===================================================================
(Binary files differ)
Modified:
branches/3.1.x/docs/userguide/en/src/main/resources/images/contextMenu_attached.png
===================================================================
(Binary files differ)
Modified:
branches/3.1.x/docs/userguide/en/src/main/resources/images/contextMenu_classes.png
===================================================================
(Binary files differ)