Overview

Smart.DropDownList represents a selection field that acts as a button and when clicked it opens/closes a list of selectable items.

To initialize a drop down list 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 the 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.
  • smart.dropdownlist.js – the JS file containing the definition for element itself.

The following code creates an empty dropDownList 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> <script type="text/javascript" src="../../source/smart.dropdownlist.js"></script> </head> <body> <smart-drop-down-list></smart-drop-down-list> </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.DropDownList 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> <script type="text/javascript" src="../../source/smart.dropdownlist.js"></script> </head> <body> <template id="template"> <span class="glyphicon glyphicon-ok"></span> <span>{{label}}</span> </template> <smart-drop-down-list 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-drop-down-list> </body> </html>

Demo

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


Smart.DropDownList has the abbility to behave like a single dropDown button or a group of buttons. The dropDownOpenMode property determines how the drop down will open. The element can have two separate buttons: an action and a dropDown button if the property is set to ‘dropDownButton’.

Data Biding

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

  • Nesting smartListItem elements inside the DropDownList’s body in the HTML:
     <smart-drop-down-list>
         <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-drop-down-list>

    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 Smart.ListItemGroup elements inside the DropDownList’s body in the HTML:
    <smart-drop-down-list>
        <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-drop-down-list>
    

    smartListItemGroup represents a group of items.

    Demo

  • Nesting HTML list elements inside the DropDownList’s body in the HTML:
    <smart-drop-down-list>
         <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-drop-down-list>
    

    Demo

    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.


  • Nesting optgroup elements inside the DropDownList’s body in the HTML:
    <smart-drop-down-list>
         <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-drop-down-list>
    

    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 type="text/javascript" src="../../source/smart.dropdownlist.js"></script> <script> window.onload = function () { document.querySelector('smart-drop-down-list').dataSource = [ "Item 1", "Item 2", "Item 3" ]; } </script> </head> <body> <smart-drop-down-list></smart-drop-down-list> </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 type="text/javascript" src="../../source/smart.dropdownlist.js"></script> <script> window.onload = function () { var dropDownList = document.querySelector('smart-drop-down-list'); dropDownList.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-drop-down-list></smart-drop-down-list> </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-drop-down-list data-source='["Item1", "Item2", "Item3"]'></smart-drop-down-list>

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

    Demo

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

    Demo

Behavior

Smart.DropDownList offers different drop down positions: bottom, top, overlay-center, overlay-bottom, overlay-top, center-top, center-bottom and auto. The position of the listBox drop down can be modified via the dropDownPosition property, 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 type="text/javascript" src="../../source/smart.dropdownlist.js"></script> <script> window.onload = function () { var dropDownList = document.querySelector('smart-drop-down-list'); dropDownList.dropDownPosition = 'top'; } </script> </head> <body> <smart-drop-down-list></smart-drop-down-list> </body> </html>

Demo

Similar to any other property dropDownPosition can be set in the HTML with an attribute:

<smart-drop-down-list drop-down-position="bottom"></smart-drop-down-list>

The default value of the property is ‘auto’. This means that the element will automatically determine the position of the drop down depending on the space available. The algorithm always starts by trying to place the drop down below the element. If there’s no space available it moves it above the element.

Demo

Keyboard Support

The following keys apply to the DropDownList element when it’s closed:

Key Action
Space Open / Close the drop down poppup only if the element is focused.
Enter Open / Close the drop down popup if the element or the popup is focused.
Arrow Up Navigate to the previous item from the list.
Arrow Down Navigate to the next item in the list.
Escape Close the drop down popup.

The following keys apply to the dropDownList popup when its opened:

Key Action
Arrow Up / Arrow Left Navigate to the previous item.
Arrow Down / Arrow Right Navigate to the next item.
Home Navigate to the first item.
End Navigate to the last item.
Page Up Navigate to the first item in the next page.
Page Down Navigate to the last item of the previous page.

Styling

Smart.DropDownList uses the following CSS variables for styling:

  • –smart-drop-down-list-default-width – default width of the element
  • –smart-drop-down-list-default-height – default height of the element
  • –smart-drop-down-element-width – default width of the drop down popup
  • –smart-drop-down-element-height – default height of the drop down popup
  • –smart-drop-down-button-width – default width of the drop down button

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> <script type="text/javascript" src="../../source/smart.dropdownlist.js"></script> <style> smart-drop-down-list { --smart-drop-down-list-default-width: 300px; --smart-drop-down-list-default-height: 50px; --smart-drop-down-element-width: 150px; --smart-drop-down-element-height: 350px; } </style> </head> <body> <smart-drop-down-list></smart-drop-down-list> </body> </html>

Demo