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>&quot;oncontextmenu&quot; 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>&lt;rich:contexMenu&gt;</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>&lt;rich:contextMenu&gt;</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>&quot;event&quot;</property> + </emphasis> attribute. The component uses <emphasis> + <property>&quot;oncontextmenu&quot;</property> + </emphasis> event by default to call a context menu by clicking on the right mouse + button.</para> + + <para><property> + <link linkend="menuGroup">&lt;rich:menuGroup&gt;</link> + </property>, <property> + <link linkend="menuItem">&lt;rich:menuItem&gt;</link> + </property> and <property> + <link linkend="menuSeparator">&lt;rich:menuSeparator&gt;</link> + </property> components are used as nested elements for <emphasis role="bold"> + <property>&lt;rich:contextMenu&gt;</property> + </emphasis>in the same way as for <emphasis role="bold"> + <property>&lt;rich:dropDownMenu&gt;</property> + </emphasis>. </para> + + <para>If a value of the <emphasis> + <property>&quot;attached&quot;</property> + </emphasis> attribute is defined as <property>&quot;true&quot;</property>, + component is attached to the parent component. An example is placed below.</para> <para> - The <emphasis><property>&quot;attached&quot;</property></emphasis> attribute defines the state of the component. - If the value of the <emphasis><property>&quot;attached&quot;</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>&quot;attached&quot;</property></emphasis> attribute is false, - component activates by JavaScript API or with assistance of <emphasis role="bold"><property>&lt;rich:componentControl&gt;</property></emphasis>. + <para>The <property>&quot;enlarge()&quot;</property> and + <property>&quot;decrease()&quot;</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>&lt;rich:contextMenu&gt;</property> + </emphasis> component usage was shown. The picture is placed on the <emphasis + role="bold"> + <property>&lt;h:panelGroup&gt;</property> + </emphasis> component. The <emphasis role="bold"> + <property>&lt;rich:contextMenu&gt;</property> + </emphasis> component is defined as nested to <emphasis role="bold"> + <property>&lt;h:panelGroup&gt;</property> + </emphasis> one and has a value of the<emphasis> + <property>&quot;attached&quot;</property> + </emphasis> attribute defined as <property>&quot;true&quot;</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>&quot;onclick&quot;</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>&quot;oncontextmenu&quot;</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>&lt;h:panelGroup&gt;</property> + </emphasis> component with a value of <emphasis> + <property>&quot;id&quot;</property> + </emphasis> attribute equal to <property>&quot;picture&quot;</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&apos;t encode an Id on a client, it can&apos;t be found by the <emphasis + role="bold"> + <property>&lt;rich:contextMenu&gt;</property> + </emphasis> and it&apos;s attached to its closest parent in a DOM tree.</para> + + <para> If the <emphasis> + <property>&quot;attached&quot;</property> + </emphasis> attribute has <property>&quot;false&quot;</property> value, + component activates via JavaScript API with assistance of <emphasis role="bold"> + <property>&lt;rich:componentControl&gt;</property> + </emphasis>. In this case there is no need to use <emphasis> + <property>&quot;oncontextmenu&quot;</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>&quot;attached&quot;</property></emphasis> attribute</title> + <title> </title> <mediaobject> <imageobject> <imagedata fileref="images/contextMenu_attached.png" scalefit="1"/> </imageobject> </mediaobject> </figure> - <para> - The <emphasis><property>&quot;event&quot;</property></emphasis> attribute defines the event on the parent element - that triggers the menu&apos;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>&lt;rich:componentControl&gt;</property> + </emphasis>. The attribute <emphasis> + <property>&quot;for&quot;</property> + </emphasis> contains a value of the <emphasis role="bold"> + <property>&lt;rich:contextMenu&gt;</property> + </emphasis> Id. For menu appearance Java Script API function + <property>&quot;Show&quot;</property> is used. It is defined with <emphasis> + <property>&quot;operation&quot;</property> + </emphasis> attribute for the <emphasis role="bold"> + <property>&lt;rich:componentControl&gt;</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>&lt;rich:contextMenu&gt;</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>&lt;rich:dropDownMenu&gt;</property> + </emphasis> component). It&apos;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>&lt;rich:componentControl&gt;</property> + </emphasis>.</para> + + <para>The <emphasis role="bold"> + <property>&lt;rich:contextMenu&gt;</property> </emphasis> <emphasis> <property>&quot;submitMode&quot;</property> @@ -164,20 +285,16 @@ <property>&quot;action&quot;</property> </emphasis> and <emphasis> <property>&quot;actionListener&quot;</property> - </emphasis> item&apos;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&apos;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>&lt;rich:contextMenu&gt;</property> </emphasis> component doesn't provide its own form, use it between &lt;h:form&gt; and &lt;/h:form&gt; tags.</note> - <para><property><link linkend="menuGroup">&lt;rich:menuGroup&gt;</link></property>, - <property><link linkend="menuItem">&lt;rich:menuItem&gt;</link></property> - and <property><link linkend="menuSeparator">&lt;rich:menuSeparator&gt;</link></property> - components is used as nested elements for <emphasis role="bold"><property>&lt;rich:contextMenu&gt;</property></emphasis>. - </para> + <!-- Will be done for latest version --> <!--para> It&apos;s possible to define the direction for list appear in the <emphasis> <property>&quot;direction&quot;</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>&lt;rich:contextMenu&gt;</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>&lt;rich:contextMenu&gt;</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>&lt;rich:contextMenu&gt;</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 &lt;div&gt; element for a strut of a popup list</entry> + <entry>Defines styles for a wrapper &lt;div&gt; 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>&lt;rich:contextMenu&gt;</property> - </emphasis> components on a page using CSS, it's enough to create classes with the same + <property>&lt;rich:contextMenu&gt;</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>&lt;rich:contextMenu&gt;</property> - </emphasis> components, define your own style classes in the corresponding <emphasis - role="bold"> - <property>&lt;rich:contextMenu&gt;</property> - </emphasis> component attributes.</para> + <property>&lt;rich:contextMenu&gt;</property> + </emphasis> components, define your own style classes in the corresponding <emphasis + role="bold"> + <property>&lt;rich:contextMenu&gt;</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>&lt;rich:contextMenu&gt;</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)