Overview

Smart.ListBox represents a box that contains a list of items that can be selected.

To initialize a list box element the user has to include the following files to the head of the page:

  • smart.base.css - the CSS file containing the styles for element
  • smart.element.js - the base class
  • smart.button.js - the JS file containing the definition for the buttons inside the Scroll Bars.
  • smart.scrollbar.js - the JS file containing the definition for the ScrollBars of the listBox popup.
  • smart.listbox.js - the JS file containing the definition for the listBox popup.

The following code adds a empty list box element to the page.

<!DOCTYPE html>
<html>
<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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> </head> <body> <smart-list-box></smart-list-box> </body> </html>

Demo

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

Appearance

Smart.ListBox allows to completely customize the content of the list items.

In order to change the content of an item, itemTemplate property has to be applied by assigning the id of an HTML Template element that's located inside the DOM. Here's an example:

<!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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> </head> <body> <template id="template"> <span class="glyphicon glyphicon-ok"></span> <span>{{label}}</span> </template> <smart-list-box item-template="template"> <smart-list-item selected value="1">Item 1</smart-list-item> <smart-list-item value="2">Item 2</smart-list-item> <smart-list-item value="3">Item 3</smart-list-item> </smart-list-box> </body> </html>

The template contains a binding field surrounded by curly braces {{ label }}. The text between the breckets can be random.

Demo

Data Biding

Adding data to the list box can be accomplished in a few ways:

  • Nesting Smart.ListItem elements inside the list box's body in the HTML:
     <smart-list-box>
         <smart-list-item value="value1">Item1</smart-list-item>
         <smart-list-item selected value="value2">Item2</smart-list-item>
         <smart-list-item value="value3">Item3</smart-list-item>
     </smart-list-box>

    Demo

    Smart.ListItem has a label and a value property. The value property can have a separate value from the label or no value at all. The user can prefer to apply a value only to the label and it will be automatically assigned to value as well.

    The text inside the list item represents the value of the label property. It can also be set in the HTML code like shown in the example above.


  • Nesting smartListItemGroup elements inside the list box's body in the HTML:
    <smart-list-box>
        <smart-list-items-group label="Group 1">
            <smart-list-item>Item 1</smart-list-item>
            <smart-list-item>Item 2</smart-list-item>
            <smart-list-item>Item 3</smart-list-item>
        </smart-list-items-group>
        <smart-list-items-group label="Group 2">
            <smart-list-item>Item 4</smart-list-item>
            <smart-list-item>Item 5</smart-list-item>
            <smart-list-item>Item 6</smart-list-item>
        </smart-list-items-group>
        <smart-list-items-group label="Group 3">
            <smart-list-item>Item 7</smart-list-item>
            <smart-list-item>Item 8</smart-list-item>
            <smart-list-item>Item 9</smart-list-item>
        </smart-list-items-group>
    </smart-list-box>
    

    Demo

    Smart.ListItemGroup represents a group of items.


  • Nesting HTML list elements inside the list box's body in the HTML:
    <smart-list-box>
         <ul label="Group 1">
             <li>Item 1</li>
             <li>Item 2</li>
             <li>Item 3</li>
             <li>Item 4</li>
             <li>Item 5</li>
         </ul>
         <ul label="Group 2">
             <li>Item 6</li>
             <li>Item 7</li>
             <li>Item 8</li>
             <li>Item 9</li>
             <li>Item 10</li>
         </ul>
     </smart-list-box>
    

    List items can be added without the ul tag. The grouping can be added at a later stage by setting the grouped property to the element.

    Demo

  • Nesting optgroup elements inside the list box's body in the HTML:
    <smart-list-box>
         <optgroup label="Group 1">
             <option value="1">Item 1</option>
             <option value="2">Item 2</option>
         </optgroup>
         <optgroup label="Group 2">
             <option value="3">Item 3</option>
             <option value="4">Item 4</option>
         </optgroup>
     </smart-list-box>
    

    optgroups are the items of an HTML select element. As usual the value attribute can be applied to each list item to assign a specific value that can differ from the label.

    Demo

  • Setting the dataSource property of the element to a new value of type Array.

    The property can be changed dynamically via javascript after the element has been initialized:

    <!DOCTYPE html>
    <html>
    <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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <script> window.onload = function () { document.querySelector('smart-list-box').dataSource = [ "Item 1", "Item 2", "Item 3" ]; } </script> </head> <body> <smart-list-box></smart-list-box> </body> </html>

    Demo

    dataSource accepts Arrays of strings or Objects. An object can contain more specific data for the items. For example:

    <!DOCTYPE html>
    <html>
    <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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <script> window.onload = function () { var listBox = document.querySelector('smart-list-box'); listBox.dataSource = [ { label: 'Item 1', value: 1 }, { label: 'Item 2', value: 2 }, { label: 'Item 3', value: 3, disabled: true }, { label: 'Item 4', value: 4 }, { label: 'Item 5', value: 5 }, ]; } </script> </head> <body> <smart-list-box></smart-list-box> </body> </html>

    Demo

    Like every other custom element property, dataSource can also be set from the HTML in the tag of the element, like so:

    <smart-list-box data-source='["Item1", "Item2", "Item3"]'></smart-list-box>

    Demo

Manipulating the content

The element offers the following methods:

  • Insert method can create and insert new list items into the element.

    The insert method can be called at any time after the element has been initialized.

    The method accepts two arguments:

    1. The index at which the item will be inserted.
    2. An array of strings or a single string representing the labels of the items to be inserted.

    <!DOCTYPE html>
    <html>
    <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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <script> window.onload = function () { var listBox = document.querySelector('smart-list-box'); listBox.insert(0, ["Item1", "Item2", "Item3"]); listBox.insert(2, 'Item4'); } </script> </head> <body> <smart-list-box></smart-list-box> </body> </html>

    Demo

  • Update method allow List items to be modified after creation.

    Update method accepts two arguments:
    1. The index of the item to be updated.
    2. Details for the item. This argument can be an object containing properties of Smart.ListItem, e.g. label, value, disabled. It can also be a simple string that represents the new label of the item that will be updated.

    <!DOCTYPE html>
    <html>
    <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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <script> window.onload = function () { var listBox = document.querySelector('smart-list-box'); //Create items listBox.insert(0, ["Item1", "Item2", "Item3"]); listBox.insert(2, 'Item4'); //Update items listBox.update(1, 'Item12'); listBox.update(2, { label: 'Item13', value: '13', disabled: true }); } </script> </head> <body> <smart-list-box></smart-list-box> </body> </html>

    Demo

  • Remove deletes an item from the element. The method accepts a single argument - the index of the item to be removed.

    Here's an example:

    <!DOCTYPE html>
    <html>
    <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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <script> window.onload = function () { var listBox = document.querySelector('smart-list-box'); //Create items listBox.insert(0, ["Item1", "Item2", "Item3"]); listBox.insert(2, 'Item4'); //Update items listBox.update(1, 'Item12'); listBox.update(2, { label: 'Item13', value: '13', disabled: true }); //Remove items listBox.remove(2); listBox.remove(0); } </script> </head> <body> <smart-list-box></smart-list-box> </body> </html>

    Demo

  • clearItems removes all items from the element. Take no arguments:
    window.onload = function () {
        var listBox = document.querySelector('smart-list-box');
        listBox.clearItems();
    }
    

    Demo

Behavior

Smart.ListBox has multiple selection modes that define it's behavior:

  • none - item selection is disabled
  • default - single selection that allows multiple items to be selected using the keyboard keys : "SHIFT" or "CTRL".
  • zeroOrMany - multiple item selection that allows empty selection.
  • oneOrMany - multiple item selection that allows at least one item to be selected.
  • zeroOrOne - single item selection that allows empty selection as well.
  • one - single item selection. Doesn't allow empty selection. One item must always be selected.
  • checkBox - multiple item selection using check boxes. Allows empty selection.
  • radioButton - single item selection using radio buttons. If grouping is enabled the selection mode allows one selected item per group

Selection mode can be changed using javascript like so:

                    <!DOCTYPE html>
<html>
<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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <script> window.onload = function () { var listBox = document.querySelector('smart-list-box'); listBox.selectionMode = 'checkBox'; } </script> </head> <body> <smart-list-box> <smart-list-item>Item 1</smart-list-item> <smart-list-item>Item 2</smart-list-item> <smart-list-item>Item 3</smart-list-item> </smart-list-box> </body> </html>

Demo

Keyboard Support

The following keys apply to the dropDownList popup when it's opened:

KeyAction
Arrow Up / Arrow LeftNavigate to the previous item.
Arrow Down / Arrow RightNavigate to the next item.
HomeNavigate to the first item.
EndNavigate to the last item.
Page UpNavigate to the first item in the next page.
Page DownNavigate to the last item of the previous page.
Space / EnterSelects / Deselects an item.

Styling

Smart.ListBox uses the following CSS variables for styling:

  • --smart-list-item-inner-container-width - default width of the list item container inside the list box
  • --smart-list-box-scroll-bar-size - default scroll size of the scroll bars inside the list box. Vertical scoll bar's wdith = Horizontal scroll bar's height.
  • --smart-list-box-filter-input-size - default height of the filter input field
  • --smart-loader-size - default size for the loader. The loader is visible when the property displayLoadingIndicator is true.

Here's how to apply the variables:

<!DOCTYPE html>
<html>
<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.scrollbar.js"></script> <script type="text/javascript" src="../../source/smart.listbox.js"></script> <style> smart-list-box { --smart-list-box-filter-input-size: 30px; --smart-list-box-scroll-bar-size: 15px; } </style> </head> <body> <smart-list-box filterable data-source='["Item1", "Item2", "Item3"]'></smart-list-box> </body> </html>

Demo