Create smart cascade application-style menus.
Version: 1.7, released on 2020-11-07
Key advantages:
Developed and maintained by balestra
Licensed under Creative Commons Attribution 4.0 License for free personal/professional/commercial use, with attribution.
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>All downloads are refreshed daily from the latest stable branch of Altersoftware GIT repository.
Static methods act on the AS.amenu code itself, not on the AS.amenu object(s) created.
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.
Deletes asAmenu, if provided.
Invoked without parameters deletes all existing asAmenu objects in the current window.
Enables an asAmenu object rendered yet, hiding all the other of the same type (if any).
asAmenu.enable() can be used as well.asAmenu.render() method on a asAmenu object already rendered has the same effect of:
asAmenu )asAmenu.enable()Returns the indexth AS.amenu object created, starting from 0.
index if omitted defaults to 0 (the first AS.amenu, if any).index starts from end, e.g.: AS.amenu.getMenu(-1) returns the last AS.amenu, if any.Returns version number.
asAmenu object methodsA new asAmenu object is created with new AS.amenu( options ).
Creates the asMenu object.
options is an optional parameter, a javascript object like: new AS.menu({ style: 'mac' })
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:
mac is Mac-style: fixed on the top of the document, activated at rollover or on click (on touch devices)tabs is a multilevel flexible set of tabs: can be rendered in every DOM node (e.g. a DIV), activated on click, rendered by default in document.bodyx : is X-Windows style: can be rendered in every DOM node (e.g. a DIV), activated on click, rendered by default in document.bodyDefaults 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:
name (String), used in .item() methods, defaults to asAmenuclockseconds (boolean), if seconds are inclued, defaults to falsestyle (string), the optional additional class, defaults to quickasAmenu.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:
label (String, mandatory): the label of the menu.name (String): the name (unique in the same menu) identifying the node, ragardless of label. Defaults to label.icon (String): use if you want to replace the label (still mandatory) with an SVG or an image.<img src="…" alt="…" /> or of a SVG XML.items (Array of menu items): the children of the object, generates a node menu (with children).action (A javascript function): alternative to children and uri, the javascript function when menu is selected (see below).area (Boolean or string, optional): if evaluated to true the menu will open a dialog area (see below).data (Your custom data): the user custom data you want to attach to the menu item.uri (String, a URI): alternative to children and action, the URI will be opened when menu is selected.target (String, window name): used with URI opens the link in the target window.observeAttr (Array): triggers on creation the definition of method aMenuitem.observeAttr() (see below), with the same parameters.observeDisabled (Array): triggers on creation the definition of method aMenuitem.observeDisabled() (see below), with the same parameters.Notes:
node (with children), sep (menu separators) leaf or clock.node when they contain the items array.leaf without action/uri/area will be marked as deadend, and won’t be clickable.{ label: '-' } or simply the string '-' instead of the object.leaf can have action, area or in alternative uri (optionally with target).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.asAmenuitem.getData() and asAmenuitem.setData()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()
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:
asAmenuitem objectE.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();asAmenu.areaClose()Closes the currently open dialog area of the menu, if any.
asAmenu.deselect()Deselects and closes all menu items of asAmenu - includes areaClose()
asAmenu.enable()Enables (shows) an asAmenu object already rendered, hiding others (if any).
asAmenu.getArea()Returns the currently open dialog area, if any, false otherwise.
asAmenu.getWrap()Returns the nav DOM node wrapping the whole menu.
asAmenu.item( param )A versatile method to retrieve menu item objects.
paramth (0-based) first-level menu item object (on the menu bar).asAmenu.item( 0, 'File', 1 ):: separator it acts like the above example: asAmenu.item( '0::File::1' )See also: asAmenuitem.item()
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.
asAmenu.hide()Hides (disables) the whole menu. Show it again with asAmenu.enable()
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 methodsA menu item (asAmenuitem object) is returned using e.g.: asAmenu.item( name )
asAmenuitem.getChildNode()Returns the UL DOM node where menu item children, if any, were rendered.
asAmenuitem.getData()Returns custom user data associated to the menu item object, if any.
asAmenuitem.getLabel()Returns the innerHTML of label DOM node of the menu item.
asAmenuitem.getLabelNode()Returns the label DOM node of the menu item.
asAmenuitem.getMenu()Returns the asAmenu object the item belongs to.
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()
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.
asAmenuitem.getWrap()Returns the LI DOM node where the menu item was rendered.
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)
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.
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:
node, the DOM node(s) as Node, array of Nodes, NodeList or CSS selector string.attribute, a string or an array of strings with the name of the observed attribute(s).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:
class becomes className.attribute, the attribute name (in this case className remains class)mutation, the MutationRecord objectWhen 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).
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:
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).
asAmenuitem.setData( customData )Sets and returns custom user data that is associated to the menu item object.
asAmenuitem.setLabel( newHTML )Sets the innerHTML of label DOM node of the menu item.
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:
AS.test.asAmenu( var ) — is var an asAmenu object?AS.test.asAmenubar( var ) — is var an asAmenubar object?AS.test.asAmenuitem( var ) — is var an asAmenuitem object?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.
js-as-core tag modules attributeobserveAttr and observeDisabledtabsx theme.tabs theme.