[richfaces-svn-commits] JBoss Rich Faces SVN: r4903 - in branches/3.1.x/docs/userguide/en/src/main: resources/images and 1 other directory.
richfaces-svn-commits at lists.jboss.org
richfaces-svn-commits at lists.jboss.org
Tue Dec 18 12:24:47 EST 2007
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.jsf?c=contextMenu"
- >Here</ulink> you can see an example of <emphasis role="bold">
+ <para><ulink
+ url="http://livedemo.exadel.com/richfaces-demo/richfaces/contextMenu.jsf?c=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)
More information about the richfaces-svn-commits
mailing list