altersoftware.IT
altersoftware.IT

:: libs :: js-as-amenu

AS.amenu

Create smart cascade application-style menus.

Version: 1.7, released on 2020-11-07

Key advantages:

See it in action here.

Developed and maintained by balestra

Licensed under Creative Commons Attribution 4.0 License for free personal/professional/commercial use, with attribution.

Index

  1. AS.amenu static methods
  2. asAmenu object methods
  3. asAmenuitem object methods
  4. Extensions to AS methods

Requires

Requires js-as-core before loading as-amenu.js

Example of basic usage, loading from Altersoftware CDN:

<script type="text/javascript" src="https://cdn.altersoftware.org/js-as-core/as-core.js" charset="UTF-8"></script>
<script type="text/javascript" src="https://cdn.altersoftware.org/js-as-amenu/as-amenu.js" charset="UTF-8"></script>

In a easier way, using js-as-core tag modules attribute:

<script type="text/javascript" modules="amenu" src="https://cdn.altersoftware.org/js-as-core/as-core.js" charset="UTF-8"></script>

Downloads

All downloads are refreshed daily from the latest stable branch of Altersoftware GIT repository.

Static methods

Static methods act on the AS.amenu code itself, not on the AS.amenu object(s) created.

AS.amenu.deselect( [asAmenu] )

Deselects and closes all menu items of asAmenu, if provided.

Invoked without parameters deselects and closes all menu items of every asAmenu in the current window.

AS.amenu.destroy( [asAmenu] )

Deletes asAmenu, if provided.

Invoked without parameters deletes all existing asAmenu objects in the current window.

AS.amenu.enable( asAmenu )

Enables an asAmenu object rendered yet, hiding all the other of the same type (if any).

  1. asAmenu.enable() can be used as well.
  2. Calling the asAmenu.render() method on a asAmenu object already rendered has the same effect of:
    • AS.amenu.enable( asAmenu )
    • asAmenu.enable()

AS.amenu.getMenu( index )

Returns the indexth AS.amenu object created, starting from 0.

AS.amenu.version()

Returns version number.

asAmenu object methods

A new asAmenu object is created with new AS.amenu( options ).

new

new AS.menu( options )

Creates the asMenu object.

options is an optional parameter, a javascript object like: new AS.menu({ style: 'mac' })

options

The optional options parameter for AS.amenu creation can have only the keys style and clock.

style

style value can be one of the available styles:

Defaults to mac.

clock

clock option activates a clock on the menu, by appending a asAmenuitem of type clock to the first level menu (the menu bar).

clock can be simply the boolean true, or an object with keys:

add

asAmenu.add( object )

Adds a menu item (or an array of menu items) to the asAmenu object.

The parameter can be an object or an array of objects, with these properties:

Notes:

  1. Menu items can be of type node (with children), sep (menu separators) leaf or clock.
  2. Menu items are of type node when they contain the items array.
  3. A leaf without action/uri/area will be marked as deadend, and won’t be clickable.
  4. To create a menu separator use { label: '-' } or simply the string '-' instead of the object.
  5. Only menu items of type leaf can have action, area or in alternative uri (optionally with target).
  6. When action method is invoked it recives as first parameter the reference to the asAmenuitem menu item, you can the use the asAmenuitem.getData() method to retrieve your custom data.
  7. All menu items can store custom data, see below: asAmenuitem.getData() and asAmenuitem.setData()

action

By passing a function object or a function reference to action parameter, when the menu item is clicked this function is invoked. The parameter passed will be the reference to the asAmenuitem object, that can be also used to retrieve associated custom data — see: asAmenuitem.getData()

area

When area is true the clicked menu item will open a dialog area ready for your use.

The area is a dialog opened with its closer button in the title bar.
If you want to prevent such button and result into a modal dialog, use: area: 'modal'.

Using area together with action is very useful: in case of area the function in action will receive 3 parameters:

  1. A reference to the clicked asAmenuitem object
  2. A reference to the DOM node of the dialog, ready for your use
  3. A function object that you can use to close the dialog area.

E.g:

let myMenu = new AS.menu();
myMenu.add([{ label: 'Choose…', area: true, action: (...p)=>{ console.log(p); } }]);
myMenu.render();

// the same example without arrow function and rest parameter:
let myMenu = new AS.menu();
myMenu.add([{ label: 'Choose…', area: true, action: function(){ console.log(arguments); } }]);
myMenu.render();

areaClose

asAmenu.areaClose()

Closes the currently open dialog area of the menu, if any.

deselect

asAmenu.deselect()

Deselects and closes all menu items of asAmenu - includes areaClose()

enable

asAmenu.enable()

Enables (shows) an asAmenu object already rendered, hiding others (if any).

getArea

asAmenu.getArea()

Returns the currently open dialog area, if any, false otherwise.

getWrap

asAmenu.getWrap()

Returns the nav DOM node wrapping the whole menu.

item

asAmenu.item( param )

A versatile method to retrieve menu item objects.

See also: asAmenuitem.item()

list

asAmenu.list( [fullFlag] )

Returns an array.

Without fullFlag (or with a false fullFlag) returns a list of labels of first-level asAmenuitems.
Separator fields type sep are not included.

With a true fullFlag returns the collection of first-level asAmenuitems.

hide

asAmenu.hide()

Hides (disables) the whole menu. Show it again with asAmenu.enable()

render

asAmenu.render()

Renders and appends to the document the asAmenu, shows it and hides others (if any).

It the asAmenu is already rendered has the same effect of asAmenu.enable()

asAmenuitem object methods

A menu item (asAmenuitem object) is returned using e.g.: asAmenu.item( name )

getChildNode

asAmenuitem.getChildNode()

Returns the UL DOM node where menu item children, if any, were rendered.

getData

asAmenuitem.getData()

Returns custom user data associated to the menu item object, if any.

getLabel

asAmenuitem.getLabel()

Returns the innerHTML of label DOM node of the menu item.

getLabelNode

asAmenuitem.getLabelNode()

Returns the label DOM node of the menu item.

getMenu

asAmenuitem.getMenu()

Returns the asAmenu object the item belongs to.

getName

asAmenuitem.getName()

Returns the name the menu item.

If no nameoption was provided, it’s by default creation label attribute.

name is also the value used by asAmenu.item() and asAmenuitem.item()

getParent

asAmenuitem.getParent()

Returns the parent object of current menu item.

Note

Using asAmenuitem.getParent() on first-level menu items doesn’t return the asAmenu, there is one more intermediate step - the asAmenuitem.getParent().getParent() will return the asAmenu object.

This intermediate step is the asAmenubar (AS.amenu.bar), the container of first-level menu items, actually associated to the top-level nav DOM node.

getWrap

asAmenuitem.getWrap()

Returns the LI DOM node where the menu item was rendered.

item

asAmenuitem.item( param )

param is mandatory, can be a string or an integer.

Returns:

See also asAmenu.item() to crawl the whole menu.

E.g: asAmenuitem.getMenu().item('File::New::3') or asAmenuitem.getMenu().item(1,0,3)

list

asAmenuitem.list( [fullFlag] )

Returns an array or false.

Without fullFlag (or with a false fullFlag) returns a list of labels of children asAmenuitems if asAmenuitem is type node, false otherwise.
Separator fields type sep are not included.

With a true fullFlag returns the collection of children asAmenuitems if asAmenuitem is type node, false otherwise.
Separator fields type sep are included.

observeAttr

asAmenuitem.observeAttr( DOMnode, attribute, callback )

The menu item will observe the DOM node for attribute change, and in this case callback will be invoked.

The parameters, all mandatory, are:

  1. node, the DOM node(s) as Node, array of Nodes, NodeList or CSS selector string.
  2. attribute, a string or an array of strings with the name of the observed attribute(s).
  3. callback, a function object (or the name of a global function) that will be invoked on attributes mutations.

When attribute changes on DOMnode a notification is sent back to callback, with 3 parameters:

  1. The DOM node that was changed
  2. An object with mutated attribute:
    • the key is the name of the attribute — note that class becomes className.
    • the value is an object with attributes:
      • attribute, the attribute name (in this case className remains class)
      • mutation, the MutationRecord object
    • In case of multiple mutations on the same attribute only reports the last occurrence.
  3. The observer object

When observeAttr is a property defined at menu item creation time, it’s also executed on creation (don’t neeed to wait for attribute change to take effect).

observeDisabled

asAmenuitem.observeDisabled( DOMnode )

A convenient shortcut: the menu item will observe the DOM node for disabled attribute change, and will disable/enable accordingly.

The parameter, mandatory, is:

  1. node, the DOM node(s) as Node, array of Nodes, NodeList or CSS selector string.

In case multiple nodes are observed the last checked (changed) will determine the actual attribute value.

When observeDisabled is a property defined at menu item creation time, it’s also executed on creation (don’t neeed to wait for attribute change to take effect).

setData

asAmenuitem.setData( customData )

Sets and returns custom user data that is associated to the menu item object.

setLabel

asAmenuitem.setLabel( newHTML )

Sets the innerHTML of label DOM node of the menu item.

Extensions to AS methods

AS.test.xxx( obj )

AS.test.xxx() is a collection of methods to tests if a variable is a specific format, returning a Boolean. See more on js-as-core.

When loaded js-as-amenu also provides:

Note

The asAmenubar (AS.amenu.bar) is the container of first-level menu items, actually associated to the top-level nav DOM node.
It’s created automatically together with new AS.amenu().

Its methods asAmenubar.getParent() and asAmenubar.getMenu() return both the asAmenu object.

asAmenubar has also the methods asAmenubar.getWrap(), asAmenubar.item() and asAmenubar.list(), actually matching the corresponding methods of asAmenu.

Version history