Activated Menu Component

Category: Editor | JavaScript | Components

Wrapper around a jQueryUI menu widget that allows more preferable interaction without having to write the core widget code from scratch (reason for basing on a widget).

new ActivatedMenu(jQuery wrapped UL node [, configurable options ]);

Code: javascript/src/component_activated_menu.js
JS test: test/component_activated_menu_test.js

ActivatedMenu

To add ActivatedMenu component functionality to your HTML you simply need to create an instance by passing, as a minimum, your target <ul> element.

Code Examples:

var menu = new ActivatedMenu($("ul.menu"));

var menu = new ActivatedMenu($("ul.menu"), {
  container_id: "special-menu-for-some-use"
});

For information relating to the underlying jQueryUI menu widget also read the menu widget api documentation

Options

To customise the ActivatedMenu output and/or functionality you can pass in a configuration object. The configurable options feature below.

activator

Specify a particular jQuery object to enhance with ActivatedMenuActivator functionality. If nothing is provided a <button> element will be created and inserted directly before the targeted menu element.

Type	Default	Optional
jQuery node	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  activator: $("#target-activator")
});

activator_classname

When an activator has not been specified in the configuration options, a <button> element is created. The activator_classname option can be used to inject a class (or classes) of your choosing to that created element.

Type	Default	Optional
String	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  activator_classname: "menuActivator"
});

activator_text

When an activator has not been specified in the configuration options, a <button> element is created. The activator_text is used to apply content to that created element.

Type	Default	Optional
String	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  activator_text: "Open menu"
});

container_id

As part of the Activated Menu creation process and resulting component composition an ActivatedMenuContainer (sub) component is created. You can specify an HTML ID attribute value to be applied to this created element by using the configuration option container_id.

Note: If no ID value is passed one is automatically generated and applied. This is done each time the component is created so cannot be referenced from within any applied CSS.

Type	Default	Optional
String	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  container_id: "menu-container"
});

container_classname

As part of the Activated Menu creation process and resulting component composition an ActivatedMenuContainer (sub) component is created. You can specify an HTML class attribute value to be applied to this created element by using the configuration option container_classname. This might be required to help reference a particular menu from within any applied CSS.

Type	Default	Optional
String	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  container_classname: "special-activated-menu"
});

position

You can pass in your own position properties to pre-set the component with a specific positional outcome when opened. This can also be done on-the-fly by passing a position object directly to the Open() method, if preferred.

Type	Default	Optional
Object	see below	Yes

new ActivatedMenu($("ul.menu"), {
      my: "right top",
      at: "left bottom",
      of: $("#someDesiredElement")
    });

new ActivatedMenu($("ul.menu"), {
      my: "right top"
    });

For more detailed information about jQueryUI position objects visit the jQueryUI documentation on position

// Default setting

{
  my: "left top",
  at: "left bottom",
  of: menu.activator.$node
}

prevent_default

The jQueryUI menu widget triggers selected items via a menuselect event attached to the initially passed <ul> node. Each descendant <li> element has the potential to contain one or more hyperlink (<a>) or <button> elements, depending on the markup. It can sometimes be desirable to silence the default event handlers for these descendant elements. You can try to do that by passing the prevent_default option.

Type	Default	Optional
String	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  prevent_default: true
});

selection_event

Inside the menuselect event listener already in place on the initial <ul> element, the ActivatedMenu component will trigger a selection event on to the parent $(document) element. This can allow for other separate areas of functionality to listen for such events and act according to their own design without the ActivatedMenu needing to know about them, or them needing to be part of the inner working for any such ActivatedMenu. You simply pass an event label and setup a separate listener, wherever you need it.

Type	Default	Optional
String	undefined	Yes

new ActivatedMenu($("ul.menu"), {
  selection_event: "label-to-identify-menu-selection-event"
});

$(document).on("label-to-identify-menu-selection-event", function(data) {
  console.log("The menu with a selecion was: ", data.menu);
});

When the passed selection event is triggered, the ActivatedMenu functionality also makes available certain data that relates to the menu item being selected. Data takes this form:

// Event data available

{
  activator: <the item that was clicked>,
  menu: <the original UL element>,
  component: <the actual ActivatedMenu instance>,
  original: {
    element: event.target, // Browser event element
    event: e // Browser event object
  }
}

Getters and Setters

Using JavaScript (ES6) we can get and set values by public getters and setters. This may or may not be intended for public use but there are limitations to privacy support when using such syntax in current JavaScript. Any such interaction that is available and inteded for use will be detailed here.

No getters or setters available on this component.

Methods

Public methods for component interaction

open([position])

Opens the menu

position
Object containing properties related to jQuery positioning.
These properties are configurable on menu creation so passing new values will override those set.

// Uses the default settings.

var menu = new ActivatedMenu($("#target-ul-element"));
menu.open();

// Overrides the default settings when passed to the open() method.

var menu = new ActivatedMenu($("#target-ul-element"));
menu.open({
  my: "left bottom"
});

For more detailed information read the jQueryUI documentation on position.

close()

Closes the menu

This method does not accept any arguments.

Code example:

var menu = new ActivatedMenu($("#target-ul-element"));
menu.close();

Events

You can tap into the events triggered as part of the original jQueryUI menu widget and learn more about that in the menu widget api documentation or, read what is available in the configurable selection_event option of the ActivatedMenu component.

Private Class

ActivatedMenuContainer

Wrapper element to provide the boundary parent of any created ActivatedMenu instance. This class is internal to the process of creating an Activated Menu Component and is not made public for individual instantiation.

new ActivatedMenuContainer( (ActivatedMenu) menu, (Object) config );

Params

menu (ActivatedMenu instance)
The main instance wrapping the original <ul> menu element.
config (Object)
This object is the same configuration object that is constructed within an ActivatedMenu instance. Anything passed to the ActivatedMenu will be available within the ActivatedMenuContainer constructor but not necessarily used.

Properties

$node (jQuery object)
Returns the HTML element (wrapped in jQuery functionality) for the container element.
menu (ActivatedMenu instance)
Returns the connected ActivatedMenu instance.

var container = new ActivatedMenuContainer(menu, config);

// HTML container element
container.$node;

// Access the ActivatedMenuContainer instance
container.$node.data("instance");

// Access the parent ActivatedMenu instance
container.menu;

Private Class

ActivatedMenuActivator

Functionality to enhance a targeted HTML element or, one that is created by the parent ActivatedMenu instance.

new ActivatedMenuActivator( (ActivatedMenu) menu, (Object) config );

Params

menu (ActivatedMenu instance)
The main instance wrapping the original <ul> menu element.
config (Object)
This object is the same configuration object that is constructed within an ActivatedMenu instance. Anything passed to the ActivatedMenu will be available within the ActivatedMenuContainer constructor but not necessarily used.

Properties

$node (jQuery object)
Returns the HTML element (wrapped in jQuery functionality) for the container element.
menu (ActivatedMenu instance)
Returns the connected ActivatedMenu instance.

var activator = new ActivatedMenuActivator(menu, config);

// HTML activator element
activator.$node;

// Access the ActivatedMenuActivator instance
activator.$node.data("instance");

// Access the parent ActivatedMenu instance
activator.menu;

This page was last reviewed on 10 March 2022. It needs to be reviewed again on 10 June 2022 .

This page was set to be reviewed before 10 June 2022. This might mean the content is out of date.