Overview

Smart.ListMenu represents a custom element which can be used to choose an option from a nested list of items. Navigation through the nested list is done in a single view.

To initialize a list menu, the user has to include the following files to the head of the page:

  • smart.base.css - the CSS file containing the styles for the element
  • smart.element.js - the base class
  • smart.button.js - this file contains the smart-repeat-button custom element. The scroll buttons of Smart.ListMenu are instances of smart-repeat-button.
  • smart.menu.js - this file defines the main functionality of the Smart.Menu custom element which Smart.ListMenu extends.
  • smart.listmenu.js - this file defines the main functionality of the Smart.ListMenu custom element.

The following code adds an empty list menu to the page.

<!DOCTYPE html>
<html lang="en">
<head>
 <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />
 <script type="text/javascript" src="webcomponents-lite.js">
</script> <script type="text/javascript" src="../../source/smart.element.js"></script> <script type="text/javascript" src="../../source/smart.button.js"></script> <script type="text/javascript" src="../../source/smart.menu.js"></script> <script type="text/javascript" src="../../source/smart.listmenu.js"></script> </head> <body> <smart-list-menu></smart-list-menu> </body> </html>

Note how smart.element.js and webcomponents.min.js are declared before everything else. This is mandatory for all custom elements.

Appearance

The list menu structure contains smart-menu-item and smart-menu-items-group elements.

The following attributes are available for these custom elements.

  • label - the label to be displayed in the list menu
  • separator - if present, a visual separator (horizontal line) is added after the item
  • disabled - disables the selection of an item

The following attributes are only available for smart-menu-item.

  • value - a custom value that is not displayed, but is passed as an argument to the itemClick event (called when an item is chosen).
  • shortcut - a helper text/icon that can represent a keyboard shortcut that activates the item. The shortcut is not displayed for top-level items in horizontal and vertical modes.

Animated list menu could be achieved when animation class is added .

 <smart-list-menu class="animation"></smart-list-menu>

Demo

The list menu and its items can have checkbox or radio button selection. To allow this the user has to set element's checkboxes property to true and checkable for the particular items or group.

 <smart-list-menu checkboxes checkable></smart-list-menu>

Demo

Data Biding

To initialize a populated Smart.ListMenu custom element, insert the required inner structure consisting of the auxiliary custom elements smart-menu-item and smart-menu-items-group, e.g.:

<!DOCTYPE html>
<html lang="en">
<head>
 <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />
 <script type="text/javascript" src="webcomponents-lite.js">
</script> <script type="text/javascript" src="../../source/smart.element.js"></script> <script type="text/javascript" src="../../source/smart.button.js"></script> <script type="text/javascript" src="../../source/smart.menu.js"></script> <script type="text/javascript" src="../../source/smart.listmenu.js"></script> </head> <body> <smart-list-menu> <smart-menu-items-group> File <smart-menu-item shortcut="Ctrl+N">New</smart-menu-item> <smart-menu-item shortcut="Ctrl+0">Open</smart-menu-item> <smart-menu-items-group> Open Containing Folder <smart-menu-item>Explorer</smart-menu-item> <smart-menu-item>cmd</smart-menu-item> </smart-menu-items-group> <smart-menu-item shortcut="Ctrl+S" disabled>Save</smart-menu-item> <smart-menu-item shortcut="Ctrl+Alt+S" separator>Save As...</smart-menu-item> <smart-menu-item shortcut="Alt+F4">Exit</smart-menu-item> </smart-menu-items-group> <smart-menu-items-group> Help <smart-menu-item>About</smart-menu-item> <smart-menu-item>Help center</smart-menu-item> <smart-menu-item>Feedback</smart-menu-item> </smart-menu-items-group> </smart-list-menu> </body> </html>

Demo

Populating from UL :

<!DOCTYPE html>
<html lang="en">
<head>
 <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />
 <script type="text/javascript" src="webcomponents-lite.js">
</script> <script type="text/javascript" src="../../source/smart.element.js"></script> <script type="text/javascript" src="../../source/smart.button.js"></script> <script type="text/javascript" src="../../source/smart.menu.js"></script> </head> <body> <smart-list-menu id="menu"> <ul> <li><a href="#Home">Home</a></li> <li> Solutions <li><a href="#Education">Education</a></li> <li><a href="#Financial">Financial services</a></li> <li> Software Solutions <ul> <li><a href="#ConsumerPhoto">Consumer photo and video</a></li> <li><a href="#Mobile">Mobile</a></li> <li><a href="#RIA">Rich Internet applications</a></li> </ul> </li> <li><a href="#">All industries and solutions</a></li> </ul> </li> <li> Products <ul> <li><a href="#PCProducts">PC products</a></li> <li><a href="#MobileProducts">Mobile products</a></li> <li><a href="#AllProducts">All products</a></li> </ul> </li> <li> Support <ul> <li><a href="#SupportHome">Support home</a></li> <li><a href="#CustomerService">Customer Service</a></li> <li><a href="#KB">Knowledge base</a></li> <li><a href="#Books">Books</a></li> </ul> </li> </ul> </smart-list-menu> </body> </html>

Demo

Populating from dataSource.

<!DOCTYPE html>
<html lang="en">
<head>
 <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />
 <script type="text/javascript" src="webcomponents-lite.js">
</script> <script type="text/javascript" src="../../source/smart.element.js"></script> <script type="text/javascript" src="../../source/smart.button.js"></script> <script type="text/javascript" src="../../source/smart.menu.js"></script> <script> window.onload = function () { document.querySelector('smart-list-menu').dataSource = [ { label: 'File', items: [ { label: 'New', shortcut: 'Ctrl+N' }, { label: 'Open', shortcut: 'Ctrl+0' }, { label: 'Open Containing Folder', items: [ { label: 'Explorer' }, { label: 'cmd' } ] }, { label: 'Save', shortcut: 'Ctrl+S', disabled: true, separator: true }, { label: 'Exit', shortcut: 'Alt+F4' } ] } ]; } </script> </head> <body> <smart-list-menu></smart-list-menu> </body> </html>

Demo

Behavior

Smart.ListMenu could be minimized/maximized. The element has minimizeWidth property. It determines the minimum width of the ListMenu at which it will switch from normal to minimized mode. If set to null, the ListMenu does not minimize automatically.

<!DOCTYPE html>
<html lang="en">
<head>
 <link rel="stylesheet" href="../../source/styles/smart.base.css" type="text/css" />
 <script type="text/javascript" src="webcomponents-lite.js">
</script> <script type="text/javascript" src="../../source/smart.element.js"></script> <script type="text/javascript" src="../../source/smart.button.js"></script> <script type="text/javascript" src="../../source/smart.menu.js"></script> <script> window.onload = function () { document.querySelector('smart-list-menu').minimizeWidth = 1000; } </script> </head> <body> <smart-list-menu></smart-list-menu> </body> </html>

User can switch between few drop down positions. The value of dropDownPosition could be:

  • top-left
  • top-right
  • bottom-left
  • bottom-right
  • auto

The element supports filtering and grouping. The following filter modes are allowed:

  • contains
  • containsIgnoreCase
  • doesNotContain
  • doesNotContainIgnoreCase
  • equals
  • equalsIgnoreCase
  • startsWith
  • startsWithIgnoreCase
  • endsWith
  • endsWithIgnoreCase
<smart-list-menu filterable filter-mode="startsWith" filter-mode grouped></smart-list-menu>

Manipulating the content

The element offers the following methods:

  • addItem - adds new item to the list menu.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.addItem(document.createElement('smart-menu-item'), '0');
         }
     </script>
    
  • back - navigates to the previous page (smart-menu-items-group).
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.back();
         }
     </script>
    
  • changePage - navigates to a particular page (smart-menu-items-group).
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.changePage(0.0);
         }
     </script>
    
  • checkItem - checks an item.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.checkItem(0.0);
         }
     </script>
    
  • getItem - gets an item by its id or numeric path.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.getItem(0.0);
         }
     </script>
    
  • maximize - maximizes the list menu.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.maximize();
         }
     </script>
    
  • minimize - minimizes the list menu.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.minimize();
         }
     </script>
    
  • removeItem - removes an item.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.removeItem(0.0);
         }
     </script>
    
  • setFocusable - sets whether the element can be focused or not.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.setFocusable(false);
         }
     </script>
    
  • uncheckItem - unchecks an item. The id or the path to the item is passed in as the method argument.
     <script>
         window.onload = function () {
             var listMenu = document.querySelector('smart-list-menu');
             listMenu.uncheckItem('0.0');
         }
     </script>
    

Keyboard Support

KeyAction
TabThe list menu receives focus by tabbing into it.
Arrow Up / Arrow DownNavigates to the previous/next item in the current view.
Arrow Left / Arrow RightNavigates to the previous/next view.
HomeNavigates to the "back" button or the first enabled item (for the top-level view).
EndNavigates to the last enabled item in the current view.
EnterSelects an item/opens an items group (new view). If the list menu is minimized and the minimized pop-up is closed, opens the pop-up.
EscapeNavigates to the previous view. If the top-level view is reached and the list menu is minimized, closes the minimized pop-up.
SpaceToggles an item's checked state.

Styling

smartListMenu uses the following CSS variables for styling:

  • --smart-menu-scroll-button-size: used to set the height of the scroll buttons of smartListMenu. Default value is 20px.
  • --smart-list-menu-header-height: used to set the height of the smartListMenu header. Default value is 40px.
  • --smart-list-menu-drop-down-width: used to set the width of the smartListMenu pop-up (dropdown) when the element is minimized. Default value is 300px.
  • --smart-list-menu-drop-down-height: used to set the height of the smartListMenu pop-up (dropdown) when the element is minimized. Default value is 200px.
  • --smart-list-menu-filter-input-size: used to set the height of the smartListMenu filter input. Default value is 35px.