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.

Files

  • CSS files
    • smart.default.css - the CSS file containing the styles for the element.
  • Javascript module
    • smart.listmenu.js - the JS module which is in the source/modules/ folder and loads all script dependencies.
  • Javascript files
    • smart.element.js - the base class.
    • smart.button.js - this file contains the smart-repeat-button custom element. The scroll buttons of smartListMenu are instances of smart-repeat-button.
    • smart.menu.js - this file defines the main functionality of the smartMenu custom element which smartListMenu extends.
    • smart.listmenu.js - this file defines the main functionality of the smartListMenu custom element.

    Usage

    • Import a module

      With this approach, we import a module and create the web component by using the Smart function. The #listmenu is a smart-list-menu tag.

      import {smartListMenu} from "../../../source/modules/smart.listmenu.js";
      
      Smart('#listmenu', class {
      get properties() {
      	return {
      		checkboxes: true,
      		checkable: true
      	}
      }
      });
      
      document.readyState === 'complete' ? init() : window.onload = init;
      
      function init() { 
      
      }
      
      Using the Smart function is optional. You can use const listmenu = document.querySelector("#listmenu"); and set the properties like that:
      const listmenu = document.querySelector("#listmenu");
      
      listmenu.checkboxes = true;
      listmenu.checkable = true;
      
      

    • Import a module, Init on Demand

      The following imports the web component's module and creates it on demand, when the document is ready. The #listmenu is a DIV tag.

      import {smartListMenu} from "../../../source/modules/smart.listmenu.js";
      
      document.readyState === 'complete' ? init() : window.onload = init;
      
      function init() { 
      const gauge = new smartListMenu('#listmenu', {
         value: 25
      });
      }
      
    • Load scripts

      The following code adds the custom element to the page.

      <!DOCTYPE html>
      <html lang="en">
      <head>
       <link rel="stylesheet" href="../../source/styles/smart.default.css" type="text/css" />
       <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>
      

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

Create, Append, Remove, Get/Set Property, Invoke Method, Bind to Event


Create a new element:
const listmenu = document.createElement('smart-list-menu');

Append it to the DOM:
document.body.appendChild(listmenu);

Remove it from the DOM:
listmenu.parentNode.removeChild(listmenu);

Set a property:
listmenu.propertyName = propertyValue;

Get a property value:
const propertyValue = listmenu.propertyName;

Invoke a method:
listmenu.methodName(argument1, argument2);

Add Event Listener:
const eventHandler = (event) => {
// your code here.
};

listmenu.addEventListener(eventName, eventHandler);

Remove Event Listener:
listmenu.removeEventListener(eventName, eventHandler, true);

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.default.css" type="text/css" />
 <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.default.css" type="text/css" />
 <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.default.css" type="text/css" />
 <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.default.css" type="text/css" />
 <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

Key Action
Tab The list menu receives focus by tabbing into it.
Arrow Up / Arrow Down Navigates to the previous/next item in the current view.
Arrow Left / Arrow Right Navigates to the previous/next view.
Home Navigates to the "back" button or the first enabled item (for the top-level view).
End Navigates to the last enabled item in the current view.
Enter Selects 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.
Escape Navigates to the previous view. If the top-level view is reached and the list menu is minimized, closes the minimized pop-up.
Space Toggles an item's checked state.