x-dropdown

Description

A CustomElement that creates a Bootstrap dropdown menu

Tested on Chrome and Firefox

Dependencies

• CustomElements API (or polyfills)
• HTMLTemplateElement
• MutationObserver API
• x-tag
• x-slot
• ES6 Object/Array methods. See the API section for details on which methods are required.

The dist/x-dropdown-full.min.js includes all necessary polyfills to run this component. Use the dist/x-navbar.min.js if you are including all dependencies so that the code size can be reduced.

Usage

  <x-dropdown>
    <xd-item><a>item 1</a></xd-item>
    <xd-item><a>item 2</a></xd-item>
  </x-dropdown>

Note:The anchor tags in the <xd-item> tag is needed for the default Bootstrap styling.

Slots

There are a few components that can be customized using slots:

• The toggle button: simply add the slot="toggle" attribute to replace the default toggle button.
• The toggle button text: if you want to only replace the HTML of the toggle button, use slot="toggle-text".
• Default slot: all other components will be added the <ul>.dropdown-menu element. Only the <xd-item> elements will be converted to <li>, however.

Notes

• When defining styles, please be aware that the <xd-item> tags are replaced with <li> tags:

  <!-- input -->
  <x-dropdown>                                    
    <xd-item><a>item 1</a></xd-item>
    <xd-item><a>item 2</a></xd-item>
  </x-dropdown>
 
  <!-- output -->
  <x-dropdown>
    <div>
      <button toggle></button>
      <ul>
        <li><a>item 1</a></li>      <!-- li replaced the xd-item tags! -->
        <li><a>item 2</a></li>
      </ul>
    </div>
  </x-dropdown>

Also note that the standard Bootstrap dropdown syntax is used.

• Another styling tip: if the styles being applied are not taking effect because the styles defined by the component are overriding them, add an ID to an element that contains the dropdown and use the id in the CSS selector. This will ensure that the specificity is higher than the selectors defined by the component.

Running the examples

To run the examples, cd example, then npm install, and finally npm run start. Point a browser to localhost:9001 to see the component in action.

XDropdown

Kind: global class
Requires: module:x-slot, module:CustomElement, module:HTMLTemplateElement, module:Array.prototype.filter, module:Array.prototype.map, module:Array.from, module:Array.prototype.forEach, module:Object.prototype.keys, module:Object.prototype.assign, module:MutationObserver
Properties

Name	Type	Description
virtual-dom	attribute	If this attribute exists, then the component will be setup for a virtual-dom environment (Angular, React, etc...)
drop-direction	attribute	Determines which direction the menu will open. Possible options are: right up down left Default is "down"
type	attribute	Determines the action with which the menu is toggled. Possible options are: click hover Default is "click".
inline	attribute	Boolean attribute. If this attribute is applied, then the dropdown menu will be rendered as an inline type. By default it's rendered as a block and takes up the entire line that it's on.
align-right	attribute	Boolean attribute. If applied, the dropdown menu and the toggle button will have the right edges aligned. Left edges are aligned by default. This only works if the drop-direction is either "up" or "down".
align-bottom	attribute	Boolean attribute. If applied, the dropdown menu and the toggle button will have the bottom edges aligned. Top edges are aligned by default. This only works if the drop-direction is either "left" or "right".
data-use-prefix	attribute	Defines a prefix that should be applied to all attribute names. This is useful when working with framworks that don't allow the usage of custom attribute names. The default prefix is "data-". Example: <x-dropdown data-use-prefix="prefix" prefix-type="hover" prefix-drop-direction="up"></x-dropdown> ^ ------ ^ <!-- or just use the default "data-" prefix --> <x-dropdown data-use-prefix data-type="hover" data-inline data-drop-direction="left"></x-dropdown>
items	Array.<HTMLLIElement>	An array of items within the dropdown. These elements are <li> elements. Setting this property will update the menu automatically. Note that simply updating the array of items (push, slice, shift, etc...) will not update the list. This property must be set after the manipulation has occurred.
evt	object	A list of constants defining the names of various events that can be fired
evt.MENU_TOGGLED	string	An event that's fired when the menu is toggled
evt.ITEM_SELECTED	string	An event that's fired when a menu item is clicked
disabled	attribute	If this attribute is applied, the menu will be disabled (not clickable). This has an equivalent, boolean property: xdropdown.disabled

• XDropdown
  • new XDropdown()
  • instance
    • "menu-toggled"
    • "item-selected"
  • static
    • .setDisabled(shouldBeDisabled)
    • .open()
    • .close()
    • .closeAll()
    • .isDisabled() ⇒ boolean

new XDropdown()

A Bootstrap themable dropdown component. It has two "modes": click and hover. The click option requires to the user to click the button to expand the menu. The hover option requires that the user simply hovers over the button.

"menu-toggled"

This event is fired when the menu is going to be either opened or closed. Calling event.preventDefault() in the event handler will stop the menu from toggling.

Kind: event emitted by XDropdown
Properties

Name	Type	Description
detail	object
detail.willOpen	boolean	If TRUE, then the menu will be opened unless event.preventDefault() is called.
target	XDropdown	The <x-dropdown> element that fired the event
preventDefault	function	Call this method to prevent the menu from opening or closing. To programmatically close/open the menu, use the open/close methods on the <x-dropdown> element

Example

// set up an event handler
const dropdown = document.querySelector("x-dropdown");
dropdown.on(dropdown.evt.MENU_TOGGLED, (e)=>{
  // prevent the menu from opening/closing
  e.preventDefault();
  // perform some nice logic...
  // close the menu by using the target attribute
  e.target.close();
});

"item-selected"

This event is fired when the user clicks a menu item

Kind: event emitted by XDropdown
Properties

Name	Type	Description
detail	object
detail.item	HTMLLIElement	the menu item that was clicked
target	XDropdown	The <x-dropdown> element that fired the event

XDropdown.setDisabled(shouldBeDisabled)

Sets the dropdown menu as disabled or enabled.

Kind: static method of XDropdown

Param	Type	Description
shouldBeDisabled	boolean	If TRUE, the dropdown will be disabled

XDropdown.open()

Convenience method used to open the current menu

Kind: static method of XDropdown

XDropdown.close()

Convenience method used to close the current menu

Kind: static method of XDropdown

XDropdown.closeAll()

Closes the main menu and all sub-menus

Kind: static method of XDropdown

XDropdown.isDisabled() ⇒ boolean

Checks to see if the dropdown should be disabled. It can be disabled via the "disabled" attribute OR if the parentNode is disabled.

Kind: static method of XDropdown
Returns: boolean - TRUE if the dropdown is disabled