Overview

Smart.DropDownButton represents a button with a placeholder that can convert to an action button, that opens/closes a popup with arbitrary HTML content.

To initialize a drop down button element the user has to include the following files to the head of the page:

Files

  • CSS files
    • smart.default.css - the CSS file containing the styles for the element.
  • Javascript module
    • smart.button.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 - the JS file containing the definition for the buttons inside the Scroll Bars
    • smart.dropdownbutton.js - the JS file containing the definition for element itself.

Usage

  • Import a module

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

    import {smartDropDownButton} from "../../../source/modules/smart.button.js";
    
    Smart('#button', class {
    get properties() {
    	return {
    		disabled: true
    	}
    }
    });
    
    document.readyState === 'complete' ? init() : window.onload = init;
    
    function init() { 
    
    }
    
    Using the Smart function is optional. You can use const button = document.querySelector("#button"); and set the properties like that:
    const button = document.querySelector("#button");
    
    button.disabled = 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 #button is a DIV tag.

    import {smartDropDownButton} from "../../../source/modules/smart.button.js";
    
    document.readyState === 'complete' ? init() : window.onload = init;
    
    function init() { 
    const button = new smartDropDownButton('#button', {
       	disabled: true
    });
    }
    
  • 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.dropdownbutton.js"></script>
    </head>
    <body>
     <smart-drop-down-button></smart-drop-down-button>
    </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 button = document.createElement('smart-drop-down-button');

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

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

Set a property:
button.propertyName = propertyValue;

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

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

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

button.addEventListener(eventName, eventHandler);

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

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

Appearance

  • By default the element appears as a simple button that opens a drop down container:

     <smart-drop-down-button>
        <h3>What is Lorem Ipsum?</h3>
        <strong>Lorem Ipsum</strong> is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
     </smart-drop-down-button>
    
  • The placeholder property must be set in order for the action button / placeholder container to be visible. It can be any string:

     <smart-drop-down-button placeholder="DropDownButton">
        <h3>What is Lorem Ipsum?</h3>
        <strong>Lorem Ipsum</strong> is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
     </smart-drop-down-button>
    
  • The dropDownOpenMode property determines when the drop down opens. The element can have two separate buttons: an action and a dropDown button if the property is set to 'dropDownButton'. The action button can execute some user code while the drop down button opens the drop down.

     <smart-drop-down-button drop-down-open-mode="dropDownButton" placeholder="DropDownButton">
        <h3>What is Lorem Ipsum?</h3>
        <strong>Lorem Ipsum</strong> is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
     </smart-drop-down-button>
    
  • The dropDownButtonPosition property determines the position of the button that opens the drop down. Four positions are available: 'left', 'right', 'top', 'bottom'.

     <smart-drop-down-button drop-down-button-position="left" placeholder="DropDownButton">
        <h3>What is Lorem Ipsum?</h3>
        <strong>Lorem Ipsum</strong> is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
     </smart-drop-down-button>
    

Content

The content of the element can be any HTML. For example, a simple text or a custom element. The content can be set on initialization or dynamically set/removed via the API.

The simplest way of settings the content of the drop down is by settings the innerHTML property:

<!DOCTYPE html>
<html>
<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.dropdownbutton.js"></script>
 <script>
     window.onload = function () {
         const dropDownButton = document.querySelector('smart-drop-down-button');
         
         dropDownButton.innerHTML = 'Simple Text Content';
     }
 </script>
</head>
<body>
 <smart-drop-down-button></smart-drop-down-button>
</body>
</html>

The element offers the following methods for content manipulation:

  • appendChild method appends HTML elements to the drop down.

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

    The method accepts only one argument - an HTML element.

    <!DOCTYPE html>
    <html>
    <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.scrollbar.js"></script>
     <script type="text/javascript" src="../../source/smart.listbox.js"></script>
     <script type="text/javascript" src="../../source/smart.dropdownlist.js"></script>
     <script type="text/javascript" src="../../source/smart.dropdownbutton.js"></script>
     <script  type="text/javascript" src="../../source/smart.menu.js"></script>
     <script type="text/javascript" src="../../source/smart.tree.js"></script>
     <script>
         window.onload = function () {
             const dropDownButton = document.querySelector('smart-drop-down-button'),
                tree = document.createElement('smart-tree');
    
            tree.dataSource = [{
                label: 'Cats',
                selected: true,
                items: [
                    {
                        label: 'Tiger',
                        selected: true
                    },
                    {
                        label: 'Lion'
                    },
                    {
                        label: 'Jaguar'
                    },
                    {
                        label: 'Leopard'
                    },
                    {
                        label: 'Serval'
                    },
                    {
                        label: 'Domestic cat'
                    }
                ]
            },
                {
                    label: 'Dogs',
                    expanded: true,
                    items: [
                        {
                            label: 'Gray wolf'
                        },
                        {
                            label: 'Ethiopian wolf',
                            selected: true
                        },
                        {
                            label: 'Arctic fox',
                            selected: true
                        },
                        {
                            label: 'Dingo'
                        },
                        {
                            label: 'Domestic dog',
                            selected: true
                        }
                    ]
                }
            ];
    
             dropDownButton.appendChild(tree);
         }
     </script>
       <style>
            smart-drop-down-button {
                --smart-drop-down-element-max-height: 500px;
            }
    
            .smart-drop-down smart-tree {
                border: none;
                width: 100%;
                height: 100%;
            }
        </style>
    </head>
    <body>
     <smart-drop-down-button drop-down-width="auto"></smart-drop-down-button>
    </body>
    </html>
  • removeChild method allows to remove an HTML element that has previously been appended.

    The method accepts one argument - the HTML element to be removed.
    <!DOCTYPE html>
    <html>
    <head>
     <link rel="stylesheet" href="./../../source/styles/smart.default.css" type="text/css" />
     <script type="text/javascript" src="../../source/smart.elements.js"></script>
     <script>
         window.onload = function () {
             const dropDownButton = document.querySelector('smart-drop-down-button'),
                   tree = document.getElementById('tree');
    
             //Remove the tree
             dropDownButton.removeChild(tree);
     </script>
    </head>
    <body>
     <smart-drop-down-button>
        <smart-tree id="tree" show-lines show-root-lines>
            <smart-tree-items-group>
                Europe
                <smart-tree-item>Germany</smart-tree-item>
                <smart-tree-item>Turkey</smart-tree-item>
                <smart-tree-item>Romania</smart-tree-item>
                <smart-tree-item>Bulgaria</smart-tree-item>
                <smart-tree-item>Croatia</smart-tree-item>
            </smart-tree-items-group>
            <smart-tree-items-group expanded>
                North America
                <smart-tree-item selected>United States</smart-tree-item>
                <smart-tree-item>Canada</smart-tree-item>
                <smart-tree-item>Mexico</smart-tree-item>
            </smart-tree-items-group>
            <smart-tree-items-group>
                Asia
                <smart-tree-item>Bangladesh</smart-tree-item>
                <smart-tree-item>Thailand</smart-tree-item>
                <smart-tree-item>South Korea</smart-tree-item>
                <smart-tree-item>Israel</smart-tree-item>
                <smart-tree-item>Bhutan</smart-tree-item>
                <smart-tree-item>United Arab Emirates</smart-tree-item>
                <smart-tree-item>China</smart-tree-item>
                <smart-tree-item>Sri Lanka</smart-tree-item>
            </smart-tree-items-group>
        </smart-tree>
    </smart-drop-down-button>
    </body>
    </html>
  • removeAll deletes the content of the drop down.

    Here's an example:

    <!DOCTYPE html>
    <html>
    <head>
     <link rel="stylesheet" href="./../../source/styles/smart.default.css" type="text/css" />
     <script type="text/javascript" src="../../source/smart.elements.js"></script>
     <script>
         window.onload = function () {
             const dropDownButton = document.querySelector('smart-drop-down-button');
    
             //Empty the drop down
             dropDownButton.removeAll();
         }
     </script>
    </head>
    <body>
     <smart-drop-down-button>
        What is Lorem Ipsum?
        Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
    </smart-drop-down-button>
    </body>
    </html>

Behavior

smartDropDownButton offers different drop down positions: bottom, top, overlay-center, overlay-bottom, overlay-top, center-top, center-bottom and auto. The position of the drop down can be changed via the dropDownPosition property, like so:

<!DOCTYPE html>
<html>
<head>
 <link rel="stylesheet" href="./../../source/styles/smart.default.css" type="text/css" />
 <script type="text/javascript" src="../../source/smart.elements.js"></script>
 <script>
     window.onload = function () {
         const dropDownButton = document.querySelector('smart-drop-down-button');

         dropDownButton.dropDownPosition = 'top';
     }
 </script>
</head>
<body>
 <smart-drop-down-button>
    What is Lorem Ipsum?
    Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
    </smart-drop-down-button>
</body>
</html>

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

<smart-drop-down-button drop-down-position="overlay-center"></smart-drop-down-button>

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.

Keyboard Support

The following keys apply to the DropDownButton element when it's closed:

Key Action
Space Open the drop down popup only if the drop down button is focused.
Enter Open / Close the drop down popup if the element or the drop down button is focused.
Escape Close the drop down popup.

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

Key Action
Arrow Up Scrolls up the content with the default scroll step.
Arrow Down Scrolls down the content with the default scroll step.
Home Scrolls to the top of the content.
End Scrolls to the bottom of the content.
Page Up Scrolls the content upwards using the page size. Works only if the popup is opened and focused.
Page Down Scrolls the content downwards using the page size. Works only if the popup is opened and focused.

Styling

smartDropDownButton uses the following CSS variables for styling:

  • --smart-drop-down-button-default-width - default width of the element
  • --smart-drop-down-button-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.default.css" type="text/css" />
 <script type="text/javascript" src="../../source/smart.element.js"></script>
 <script type="text/javascript" src="../../source/smart.dropdownlist.js"></script>
 <style>
 smart-drop-down-button {
     --smart-drop-down-button-default-width: 300px;
     --smart-drop-down-button-default-height: 50px;
     --smart-drop-down-element-width: 150px;
     --smart-drop-down-element-height: 350px;
 }
 </style>
</head>
<body>
 <smart-drop-down-button>
   What is Lorem Ipsum?
    Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
</smart-drop-down-button>
</body>
</html>