Javascript popupmenu

Introduced in eZ publish 3.5.

The file ezpopupmenu.js located in design/standard/javascript/popupmenu provides a very cool and flexible DHTML popupmenu. In order to use this javascript you must also include design/standard/javascript/lib/ezjslibdomsupport.js and design/standard/javascript/lib/ezjslibmousetracker.js

Features

• Multilevel popupmenu
• Supports all major browsers
• All HTML code in template
• Supports context sensitivity for eZ publish through:
  - String substitution in the href attribute of menuitems
  - Form submital with string substitution

Public interface

Function name	Description
ezpopmenu_showTopLevel	Display a new top-level popupmenu.
ezpopmenu_showSubLevel	Display a sublevel popupmenu. It does not hide any parent menus.
ezpopmenu_submitForm	Activate a form.
ezpopmenu_mouseOver	This method should be called by all menuitems when a mouseover event occurs. It currently hides and submenus that should not be shown.
ezpopmenu_initOffsets	Controls the popup offsets of new menus relative to the mouse position or parent item. Typically called once right after the inclusion of the javascript.
ez_createAArray	Helper method to create associative arrays (really an object). It takes an array with an even number of elements and makes a associate element out of every two array elements.

ezpopmenu_showTopLevel( event, menuID, substituteValues, menuHeader )

Display a new top-level popupmenu. Other visible top-level menus will be hidden.
Calling this method automatically invokes string substitution for the elements in the new menu.
The following steps are executed for each menu item present in the menuArray configuration:

1. The values of the substituteValues parameter is used to do search and replace on the url string provided in the menuArray for this item.
2. The href value of the menuitem is replaced with the computed value.

Parameter	Description
event	The mouse event triggering the call to this method. Putting "event" here does the trick
menuID	The identification of the menu to display
substituteValues	An associative array containing the substitute values to use.
menuHeader	If the menu has a header, the contents are replaced with this value.

ezpopmenu_showSubLevel( event, menuID, overItem )

Display a sublevel popupmenu. It does not hide any parent menus. Substitute values are taken from the last call to showTopLevel.

Parameter	Description
event	The mouse event triggering the call to this method. Putting "event" here does the trick
menuID	The identification of the menu to display
overItem	The id of the HTML item triggering the call to showSubLevel. The new menu is positioned relative to this item.

submitForm( formID )

Activate a form. All fields of type hidden within this form are target to string substitution.

Parameter	Description
formID	The identification of the form to activate.

ezpopmenu_mouseOver( id )

This method should be called by all menuitems when a mouseover event occurs. It currently hides and submenus that should not be shown.

Parameter	Description
id	The identification of the HTML element triggering the call to mouseOver

ezpopmenu_initOffsets( offsetX, offsetY )

Controls the popup offsets of new menus relative to the mouse position or parent item. Typically called once right after the inclusion of the javascript.
The default values are 8 for the x axis and 4 for the Y axis.

Parameter	Description
offsetX	The offset of the new menu on the X axis. Both positive and negative values are allowed
offsetY	The offset of the new menu on the Y axis. Both positive and negative values are allowed

Creating your own popupmenu

In order to use the popupmenu javascript you need to provide:

1. The HTML/CSS structure for you menu(s)
2. The menuArray javascript array containing the configuration of your popupmenu(s).

eZ publish provides a default template for this purpose. It is located in popupmenu/popup_menu.tpl. You are encouraged to override this file in the siteacess where you want to use the menu.

1. Setting up the HTML/CSS structure for your popup menu(s)

Your menu should be set up completely with all elements. The following requirements apply:

• The outer element should be a "div"
• The css of the outer div should (other alternatives are possible) have the following CSS attributes set:
  position: absolute;
  z-index: +1;
  visibility: hidden;
• The menuitems must be of type "a"
• Both the menu and the menuitems must be given and "id". This id is used in the menuArray to set up that menu/item.
• Each menuitem must call ezpopmenu_mouseOver or one of the methods spawning a metnu on the mouseover event. The name of the enclosing menu must be given as parameter.
• The menus should be defined in the order they will be shown. In other words, the mainmenu first and then any submenus. This is to ensure the correct visible stack order.

Example

example with a main menu and a submenu:

<!-- The main menu -->

 <div class="menu" id="mainmenu">

  <a id="menu-main" href="http://www.ez.no" onmouseover="ezpopmenu_mouseOver( 'mainmenu' )" >ez.no</a>

  <a id="menu-substitute" href="#" onmouseover="ezpopmenu_mouseOver( 'mainmenu' )" >Dynamic node view</a>

  <a id="menu-spawn" href="#" onmouseover="ezpopmenu_showSubLevel( event, 'submenu', 'menu-spawn' )" >Show submenu</a>

 </div>

<!-- The submenu -->

 <div class="menu" id="submenu">

  <a id="submenu-item" href="#" onmouseover="ezpopmenu_submitForm( 'myform' )">Form submitter</a>

 </div>

2. Setting up the menuArray array containing the popupmenu configuration

The menuArray is a multilevel array describing the features of your menus. The structure of the menuArray array is flat. This means that each menu is described in the first level of the array.
Each menu can have the following properties set:

• "depth" [required]: The depth of the menu. Toplevel menus have depth 0. Menus appearing from a toplevel menu have depth 1 etc.
• "elements": The elements property must be yet another array containing all the menuitems that require string substitution. The name of the element must match the "id" attribute set for the element in the HTML code.

Each element is again, an array. Currently we only support one option (may change in the future):

• "url": The URL that this element should point at. Put the part that should be substituted within "%" symbols.

The following example configures the menu created in step 1.

<script language="JavaScript1.2" type="text/javascript">

 

var menuArray = new Array();

<!-- main menu -->

menuArray['mainmenu'] = new Array();

menuArray['mainmenu']['depth'] = 0;

menuArray['mainmenu']['elements'] = new Array();

menuArray['mainmenu']['elements']['menu-substitute'] = new Array();

menuArray['mainmenu']['elements']['menu-substitute']['url'] = {'/content/view/%nodeID%'|ezurl};

 

<!-- submenu -->

menuArray['submenu'] = new Array();

menuArray['submenu']['depth'] = 1; // this is a first level submenu of ContextMenu

 

</script>

 

 <!-- The form submitted by the submenu -->

 {* Remove a node. *}

<form id="myform" method="post" action="someactionhere">

  <!-- Notice that there is autoamatic string translation for the contents of value -->

  <input type="hidden" name="example" value="%nodeID%" />

</form>

Activating the toplevel menus

Finally you will need to activate the "mainmenu" menu somehow. This is achieved through a call to ezpopmenu_showToplevel. In the eaxample case links in the setup array containing the string %nodeID% will be substituted by 42.

example:

<a onmouseclick="ezpopmenu_showTopLevel( event, 'ContextMenu', ez_createAArray( array( %nodeID%, 42) ) ); return false;">show</a><br />