Menu

API Reference

Overview

UI-related pull-down Menu inherits from list and lets users select the necessary item from the list of grouped items (sub-menus). Each element of a submenu can start its own sub-menu.
A dynamic Submenu becomes visible only when you put a mouse pointer over the corresponding item of the main menu (on 'onMouseOver' event) and hides as soon as you remove mouse pointer ("onMouseOut").



Initialization

Menu object is stored in the data property.

webix.ui({
    view:"menu",
    id:"my_menu",
    subMenuPos:"right",
    layout:"y",
    data:[ //menu data
        { value:"Translate...", submenu:["English", "Slavic...", "German"]},
        { $template:"Separator" },
        { value:"Post...", submenu:[ "Facebook", "Google+", "Twitter" ]}
    ],
    type:{
        subsign:true,
        height:50
    }           
});

Related sample:  Basic Menu

Submenu configuration may include:

  • subMenuPos (string) - sets position of pull-down sub-menus that will appear on mouse over;
  • submenuConfig (object) - sets common configuration for all the sub-menus in this menu regardless of their nesting level;
  • layout (string) - sets the arrangement of menu items: x (default) for a horizontal menu, y for a vertical one;
  • $template (string) - flag that indicates a separator between groups of menu items. Possible types are as follows:
    • "Separator" - a gray separating line;
    • "Spacer" - an empty item with white background that doesn't change on mouse over.
  • type - object that contains setting for menu items, namely:
    • subsign (boolean) - sets an arrow for an item containing a submenu;
    • height and width (number) of each item;
  • openAction (string) - alters the way of submenu opening - "click". If set, you should first click a menu item to enable submenu opening and hiding on "onMouseOver" and "onMouseOut" events. To hide sub-menus, you need to click somewhere outside the menu;
  • template - (string, function) - rules of data presentation. See Data templates article for details;
  • data (object) - the inline data desired format. See Loading data article for details
  • autowidth - (boolean) adjusts the width of pull-down sub-items according to the length of their text, false by default

Related sample:  Showing Menu on Mouse Click (dropping down on hover is disabled)

Working with Menu Items

Configuring Menu Items

A menu/submenu item can be a text item including the one that starts its own submenu and any Webix component specified by ID.

Menu items are stored in the data array, each item being an object. Submenu items are stored in the submenu array. Each menu item may have the following attributes:

  • id - item id.If omitted, it's given an auto-generated one;
  • value - defines text value for an item;
  • href - defines a link for an item;
  • config - defines configuration of a child submenu popup (if any). The configuration overrides the one defined via submenuConfig;
  • badge - sets an orange information circle that notifies about the number of new activities for this menu item (e.g. messages).

The easiest way to define menu items is to pass them as a simple array:

{ view:"menu", data:["Google", "Facebook", "Twitter"] }

Or an associative one:

{ view:"menu", data:[
    { id:1, value:"Google"}, 
    { id:2, value:"Facebook"}, 
    { id:3, value:"Twitter"}
]}

Links in Menu Items

Each menu and submenu item can be supplied with a link specified in the data object by the href and target (optional) attributes:

view:"menu",
data:[
    { id:"1", value:"Imitation of Spenser", href: "#verse1", target:"_blank"},
    { id:"2", value:"The Human Seasons", href: "#verse2"}
]

If not specified, target will be set as an empty string.

Related sample:  Menu hrefs

Badges in Menu Items

Badges add info circles to menu items with the number of entities you'd like to associate with this or that item (e.g. messages):

view:"menu", 
data:[
    { id:"1",value:"Translations", badge:"1"},
    { id:"2",value:"Posts", badge:"12" },
    { id:"3",value:"Info", badge:"24" }
]

Related sample:  Menu with Badges

Separators in Menu

To separate one group of items from another one in vertical menu, use the property $template with one the possible values:

  • "Spacer" - adds horizontal space between menu items;
  • "Separator" - add a horizontal gray line between menu items.

Spacer in vertical menu

view:"menu",
layout:"y",
data:[
    { id:"1", value:"Translations", icon:"qrcode", badge:20 },
    { id:"2", value:"Posts", icon:"file-word-o", badge:3 },
    { $template:"Spacer" },
    { id:"3", value:"Help", icon:"support"},
]

Related sample:  Vertical Menu

Separator in vertical menu

view:"menu",
layout:"y",
data:[
    { value:"Translate..." },
    { value:"Post...", submenu:[ "Facebook", "Google+", "Twitter" ]},
    { $template:"Separator" },
    { value:"Info" }
]

Related sample:  Basic Menu

Customizing Submenus

Submenu items can be set as an array of values:

{ id:"2",value:"Translate...", submenu:[ "English", "Slavic", "German" ]},

Or, as an array of menu objects:

{ id: "1.2", value:"Slavic...", submenu:[
    {id: "1.2.1", value:"Belarusian"},
    {id: "1.2.2", value:"Russian"},
    {id: "1.2.3", value:"Ukrainian"}
]}

Any nested submenu (a popup) can be configured separately with the help of a config attribute of its parent:

view:"menu",
submenuConfig:{
    width:400
},
data:[
    { id:"2",value:"Custom...", 
        config:{
            width:500,
            on:{ 
                onItemClick:function(id){
                    webix.message("Submenu click: "+id);
                }
            }
        },
        submenu:[ "Facebook", "Google+", "Twitter" ]
     }
]

This configuration overrides common configuration for sub-menus defined by submenuConfig.

Related sample:  Configuring Submenus

Automatic setting of Submenus' width

To change the width of Submenus automatically, according to the length of their labels, use the autowidth property with the true value in the menu's configuration:

webix.ui({
    container:"areaA",
    view:"menu",
    autowidth:true,
    data:[
        { id:"1",value:"Short...",
            submenu:[ "FB", "G+", "TW" ]},
        { id:"2",value:"Medium...",
            submenu:[ "Facebook", "Google+", "Twitter" ]},
        ...
    ]
});

Related sample:  Autowidth for Submenus

Webix Component as Menu Item

Submenu parameter may point as well to any Webix component that has been initialized previously:

webix.ui({
    id:"details1",
    view:"context", width:300, height:200,
    body:{ content:"html1" }
});
 
webix.ui({
    view:"menu",
    data:[
        { value:"HTML 4", submenu:"details1" },
        { value:"HTML 5", submenu:"details2" }
    ]
});

Related sample:  HTML Elements as Menu Items

The same way you can initialize Webix submenu component separately and then point to it within submenu property:

webix.ui({
    view:"submenu", id:"test", data:[
        { id:"1.1", value:"English"},
        { id:"1.3", value:"German"}
    ]
});
 
webix.ui({
    view:"menu",
    data:[
        { id:"1", value:"Translate...", submenu:"test"},
        { id:"2", value:"Post..."
    ]
});

Each submenu item can take its own submenu component.

MenuBar

Menu takes after a toolbar in appearance, so the best way to create a menubar is to initialize menu and toolbar in neighboring columns:

webix.ui({
    cols:[ menu, toolbar ] 
});

Related sample:  Menu in Toolbar

Hiding and Disabling Menu Items

Hiding

To hide and show menu item, you should apply hideItem() and showItem() to the menu component while specifying item ID as function parameter.

The event that triggers function execution can be checkbox state change in the Webix tree populated with the same data as menu, provided that checkbox item ID = related menu item ID.

$$("tree1").attachEvent("onItemCheck",function(id,state){
    if (state) //if checked
        $$("top_menu").hideItem(id);
    else
        $$("top_menu").showItem(id);
});

As a result, only "unchecked" menu items are shown.

Related sample:  Hiding Menu Items

Disabling

To disable menu item, you should apply special disableItem() and enableItem() functions to menu passing ID of the necessary item into them. The methods can be triggered by changing the state of a checkbox the ID of which equals the ID of the corresponding menu item.

$$("tree1").attachEvent("onItemCheck",function(id,state){
    if(state) //if checked
        $$("top_menu").disableItem(id);
    else
        $$("top_menu").enableItem(id);
});

Disabling a menu item from JSON

You can also specify an item as disabled in the menu data configuration. For this purpose you should set the disabled:true attribute in the related item object:

webix.ui({
    view:"menu",
    data:[
        { id:"1",value:"Translate...", submenu:[
            {id: "1.1", value:"English"},
            { id: "1.2", value:"Slavic...", submenu:[
                {id: "1.2.1", value:"Belarusian"},
                {id: "1.2.2", value:"Russian", disabled:true },
                {id: "1.2.3", value:"Ukrainian"}
            ]}          
        ]}
    ]
});

In essence, disabling and enabling is performed via CSS classes, that's why menu items get a template that helps display normal and disabled item differently:

view:"menu", 
template:function(obj){
    if(obj.disabled)
        return "<span class='disabled'>"+obj.value+"</span>";
    return obj.value;
}

Related sample:  Disabling Menu Items

Event Handling with Menu and Submenu Items

All menu and submenu items can be accessed by their IDs.

1 . Any item can be accessed directly with the getMenuItem() method that takes item ID as parameter and returns item object:

//getting menu item value by its ID
$$('menu1').getMenuItem(id).value;

Related sample:  Basic Menu

2 . At the same time, menu items can be derived through submenu object returned by the getSubMenu() method for an item with the specified ID. If there's no submenu for an item - an object of the calling component will be returned.

var menu = $$("menu1").getSubMenu(id);
var item = menu.getItem(id).value;

Related sample:  HTML Elements as Menu Items

Both methods can be used in either of menu inner events, for instance, click events:

  • onMenuItemClick - fires on clicking all menu items regardless of hierarchy level. Ignores disabled items;
  • onItemClick - standard event that fires on clicking any item of the same hierarchy level. Fires for disabled item as well.

General "onMenuItemClick" handler

view:"menu",
data:[...],
on:{
    onMenuItemClick:function(id){
        webix.message("Click: "+this.getMenuItem(id).value);
    }
}

Related sample:  Basic Menu

Submenu specific "onItemClick" handler

view:"menu",
data:[
    { id:"1",value:"Custom...",
        config:{
            width:250,
            on: { onItemClick:function(id){
                webix.message("Submenu click: "+id);
            }}
        },
        submenu:{...}
    }
]

Related sample:  Configuring Submenus

Related Articles

Back to top