controllerMenu

Description

Adds cascading menu functionality to an element and its DOM descendants, which together form the menu, its sub-menus and their items. The submenus will have menu() controllers automatically created.

Every menu, i.e. an element with a menu() controller, has the following structure:

A menu() controller can be assigned to any element, not only an <ul>. Note that the menu items (as elements) are not direct children of the menu element - they are the first child elements within the children of the menu element.

If a child of the menu element contains two (or more) elements, then the first one is considered a menu item, and the second one - a submenu, which is opened on clicking the menu item.

Does not apply any transforms.

Parameters

Visit page Controller # Common Parameters for documentation on the parameters, common to all controllers: id, paused and disabled.

Parameters of menu():

parent_menu

A reference to an eventual parent menu. If such reference is not supplied, the menu is considered a 'top menu'. Since building a menu structure requires creating a menu controller only on the top menu (and the controllers on the submenus are created automatically), this parameter is rarely needed to be supplied. Default value: null

show_button

A DOM id or reference to an element which upon clicking must open the menu. Within a menu structure, this parameter is automatically set for submenus to point to the menu items in the parent menus that open the submenus. While a menu is opened, its show_button (if such is defined) has its style changed. What styling class to apply can be set via attribute with name highlight_class on the the show_button, or if such is not present and the show_button is a menu item of a parent menu - via the same attribute set on the parent menu's element. Default value: null

align

Tells how to align (horizontally and vertically) a menu relative to its show_button. The alignment is performed on each showing of the menu. Supply a value of "none" if the menu does not need alignment.
Format of the parameter: "hhvv", where h can be "l", or "c" or "r" (standing for left/center/right), and v can be "t", or "m" or "b" (standing for top/medium/bottom). The first h and v are about the show_button, the second ones - about the element.
For example, a value of "lrmt" means that the menu's right corner should be the same as the show_button's left corner, and the menu's top corner should be the same as the show_button's medium of height. Default value: "rltt"

submenus_align

When creating a menu with submenus and you want all the submenus to have the same align parameter which is different than the top menu's align parameter, supply the submenus' align value in the top menu's submenus_align parameter. If every submenu should have a different align value, then set these values via a callback supplied with parameter for_each_menu (see bellow). Default value: "same"

collapse_subs

If true, then all-submenus will be ordered to hide upon hiding of this one. Default value: true

hide_on_blur

If true, then the menu will automatically hide when focus is lost. Default value: true

highlight_class

Style class to be applied on active menu items, i.e. on items that link to currently-open submenus. Default value: ""

for_each_menu

Supply the name of, or reference to, a function that will be called for every submenu upon its creation. This function can set parameters unique to this submenu, as well as add controllers performing animations upon the menu's events.
If the function is in a different namespace than window, supply the namespace chain. For example,
"window.namesp.namesp2.function_name".
The callback will receive no parameters, but this will be set to the newly-created submenu's menu() controller. Default value: ""

for_each_item

Supply the name of, or reference to, a function that will be called for every (sub-)menu item upon its creation. This function can add controllers performing animations on the item upon the menu's event item_clicked or inner_item_clicked.
If the function is in a different namespace than window, supply the namespace chain. For example,
"window.namesp.namesp2.function_name".
Format of the callback:
callback(parent_menu, item_index, item_link, sub_menu)

• parent_menu - a reference to the menu containing the item,
• item_index - zero-based index of the menu item within the menu,
• item_link - a reference to the menu item,
• sub_menu - a reference to the submenu which this menu item opens (if such).

Within the callback, this will be set to the menu item's container (the <li> tags in the example above). Default value: ""

Accepted Messages

Visit page Controller # Common Messages for documentation on the messages, accepted by all controllers: pause, unpause, enable, disable, params and remove.

Messages accepted by menu():

show

Tells the controller to open the menu. If the menu is in the process of opening or is already opened, this message will have no effect. If there are no controllers listening to this element's show action (and animating the element), then the "showing" of the element will be performed by setting its style.display property to "block". Message params: none

show_immediately

Same as message show, but tells the animating controllers that the transition should be made immediately, without animations. Message params: none

hide

Tells the controller to close the menu. If the menu is in the process of closing or is already closed, this message will have no effect. If parameter collapse_subs is true, then all submenus will also receive message hide. If there are no controllers listening to this element's hide action (and animating the element), then the "hiding" of the element will be performed by setting its style.display property to "none". Message params: none

hide_immediately

Same as message hide, but tells the animating controllers that the transition should be made immediately, without animations. Message params: none

button_clicked

Tells the controller that its show_button is clicked. This will cause the opening of the menu if it's closed, or its closing if it's open. Message params: none

Generated Events

Visit page Controller # Common Events for documentation on the events, generated by all controllers: frame, remove, paused, unpaused enabled and disabled.

Events fired by menu():

button_clicked

Fired upon receiving message button_clicked (when the menu's show_button is clicked). Event params: none

item_clicked

Fired upon clicking of a menu item. The event's params contain information about which item is clicked and its index in the menu's items list. Event params: {pos: <index of clicked item>, item: <reference to item's element>}

inner_item_clicked

Fired upon clicking of a menu item which belongs to this menu or any of its submenus. The event's params contain information about which item in which menu is clicked and its index in the menu's items list. Event params: {menu: <reference to menu controller>, pos: <index of clicked item>, item: <reference to item's element>}

focus

Fired upon the menu (or any of its items or submenus) gaining DOM focus or being clicked. Event params: none

blur

Fired upon the menu losing focus, which means that an element outside the menu has been focused or clicked. Event params: none

mousein

Fired upon the mouse entering the menu (or any of its submenus). Event params: none

mouseout

Fired upon the mouse leaving the menu (and its submenus). Event params: none

Interaction with DOM

• Transforms: Does not apply any CSS transforms.
• CSS: Works with any styling, though in order for menu aligning to work, the menu element's style.position should be set to "absolute". Sets the following properties:
  
  • style.top and style.left (when aligning),
  • style.display (when showing/hiding the menu without other controllers animating it),
  • style.pointer-events (when showing/hiding the menu).
• Events: Sets the following event listeners:
  • For each item's click event,
  • For the menu's show_button's click event,
  • If this is the top menu, for the document's click and focus events.

Changes Log

1. Controller introduced in v.0.80

See Also