---
title:                                  Manuals
tagline:                                MsDropdown
date:                                   2021-03-07 00:00:00
description: >
                                        The template comes with a Web included, a skeleton for
                                        a new website created with J1 Template. This Web is called
                                        the "Starter web", a general-purpose scaffold to be modified
                                        for your needs.

categories:                             [ Manuals ]
tags:                                   [ MsDropdown ]

comments:                               true
fam_menu_id:                            page_ctrl_simple

permalink:                              /pages/public/manuals/msDropdown/
regenerate:                             false

resources:                              [ clipboard, rouge ]
resource_options:
  - attic:
      padding_top:                      400
      padding_bottom:                   50
      opacity:                          0.5
      slides:
        - url:                          /assets/images/modules/attics/matthew-dockery-1920x1280.jpg
          alt:                          Photo by Matthew Dockery on Unsplash
          badge:
            type:                       unsplash
            author:                     Matthew Dockery
            href:                       https://unsplash.com/@matt_dockery
---

== MsDropdown properties

=== Attributes

Besides selectedIndex, options, name, size, multiple, etc attributes/properties,
msDropdown reads below attributes too.

.msDropdown attributes
[cols="4a,8a", options="header", width="100%", role="rtable mt-3"]
|===
|Name |Description

|`autofocus`
|As the name suggests, this attribute lets you choose that a form control
should have autofocus when the page is loaded. Only one element can have
autofocus.

|`disabled`
|If this property is enabled, you won't be able to interact with the
element.

|`form`
|It returns the name of the <form> element to associate the <select>
with. This is readonly property.

|`name`
|It returns the name of the <select> element.

|`required`
|A Boolean attribute indicating that an option with a non-empty string
value must be selected. Here is a surprise; you can change the default
message too. Just set the
`data-error-message="Your custom message here"` in `<select>`.

|===

=== Data attributes

.msDropdown Data attributes
[cols="4a,8a", options="header", width="100%", role="rtable mt-3"]
|===
|Name |Description

|`data-main-css`
|This is the main CSS class. Default value is `ms-dd`

|`data-show-icon`
|If you are in need to hide the icon on the header. The default value
is: `true`

|`data-event`
|To interact msDropdown with an event. The default value is: `click`

|`data-child-width`
|Sometimes you need a list of children bigger than the dropdown. This can
help. The default value is: `null` or whatever is defined in the CSS.

|`data-child-height`
|By default, it shows all the options listed in the dropdown. If you
need to show some rows you can use this attribute. The default value is:
`null`

|`data-enable-checkbox`
|If you enable this; multiple will automatically set to true. It shows a
checkbox with each list item. The default value is: `false`

|`data-checkbox-name-suffix`
|If the checkbox is enabled; there is an extra field will be posted
with the form. Say <select> name is "tech" and checkbox is enabled,
tech_mscheck[] will be posted as an array. The default value is:
`{select_name}_mscheck`

|`data-enable-auto-filter`
|It lets you search by typing any key when msDropdown is open. Just like
auto-suggest. The default value is: `true`

|`data-visible-rows`
|If you set this attribute, it calculates the max height of the items
and sets the child height based on the number provided in value. You can
also achieve this by using the data-child-height property, only that set
in pixels. The default value is: `null`

|`data-show-plus-item-counter`
|If multiple is true and you select more than one item; it shows a text
+N. N denotes numbers here. The default value is: `true`

|`data-error-message`
|If `required` is enabled in <select> it shows a required message. Guess
what? You can change that by setting this attribute. The default value
is: `Please select an item from this list`
|===

=== Option attributes

Besides value, text, selected, disabled, class, and style attributes/properties.
msDropdown reads the below attributes too.

.msDropdown Option attributes
[cols="4a,8a", options="header", width="100%", role="rtable mt-3"]
|===
|Name |Description

|`data-image`
|This attribute is used to display an image in an item

|`data-title`
|If you need to display any text on hover of an item

|`data-description`
|To display a description along with the text in the next line.

|`data-image-css`
|You may use this if you want to display an image using CSS.

|===

== MsDropdown API

It's always good to explore more and more. Let's do it then.

=== Set and get properties

.msDropdown properties
[cols="4a,8a", options="header", width="100%", role="rtable mt-3"]
|===
|Name |Description

|`selectedIndex`
|This property is used to set and get the selected index. +

[source, js]
----
let ddSelect = document.getElementById("tech").msDropdown;
//To set the value
ddSelect.selectedIndex = 3;

//To get get value
let index = ddSelect.selectedIndex;
----

|`options`
|This returns `<option>` (HTMLOptionsCollection) elements. You can set
the length of option with this property too. +

|`length`
|To set and get the length of the options.

|`value`
|Returns the selected value

|`selectedText (readonly)`
|This returns the selected text of the dropdown.

|`disabled`
|To make dropdown enable or disabled. You won't be able to interact with
msDropdown when it is disabled.

|`form (readonly)`
|This returns the associated `<form>` else null.

|`multiple`
|This property is used to set or get the multiple. You may be able to
select more than one item if multiple is true.

|`name`
|This returns the name of the <select>. I should mention here; msDropdown
borrows the name from the original dropdown to work the "required"
attribute.

|`required`
|A Boolean attribute indicating that an option with a non-empty string
value must be selected. Here is a surprise; you can change the default
message too. Just set the
`data-error-message="Your custom message here"` in `<select>`.

|`size`
|If the size is greater than 1, It will be converted as a list. The size
determines the number of rows to show.

|`selectedOptions (readonly)`
|It returns the selected <option>.

|`children (readonly)`
|It returns the list of options.

|`uiData (readonly)`
|It returns the selected data. You may find the following properties in
this one object. `isArray` will be true if data,UI, index etc will be
return as an array. +

[source, js]
----
{data: {
        "image": "../dist/images/icons/icon_games.gif",
        "title": "",
        "description": "",
        "value": "games",
        "text": "Games",
        "className": "",
        "imageCss": "",
        "index": 2,
        "selected": true,
        "disabled": false,
        "internalStyle": ""
        },
        ui: <li>,
        index: 2,
        option: <options>,
        isArray:false
}
----

|`version (readonly)`
|This returns the current version of the msDropdown.

|===

=== Access or set these properties

Here is an example. The below dropdown id is "tech". Each element has a
new property called "msDropdown" once it's converted to msDropdown/image
dropdown. You can access all the public properties and methods from that
one.

[source, js]
----
let ddSelect = document.getElementById("tech").msDropdown;
----

Select a property:

Reminder: I've made `ddSelect` as a global variable on this page. You
can play with that in `console`.

selectedIndex options length selectedText disabled form multiple name
required size selectedOptions children uiData

Try to copy-paste the below code in the console. You can set and get all
the properties.

[source, js]
----
ddSelect.selectedIndex = 0;
----

=== Public methods

.Public methods
[cols="4a,8a", options="header", width="100%", role="rtable mt-3"]
|===
|Name |Description

|`setSettingAttribute`
|Set the settings attributes, and you have an option to remake the
msDropdown by passing `true` in the last argument. +

[source, js]
----
/**
*
* @param key
* @param value
* @param shouldRefresh
*/
setSettingAttribute(key, value, shouldRefresh);
----

Below are available keys and default values: +
[source, js]
----
{
  byJson: {
      data: null, selectedIndex: 0, name: null,
      size: 0, multiple: false, width: 250
      },
  mainCss: 'ms-dd',
  rowHeight: null,
  visibleRows: null,
  showIcon: true,
  zIndex: 9999,
  event:'click',
  style: '',
  childWidth:null,
  childHeight:null,
  enableCheckbox:false,
  checkboxNameSuffix:'_mscheck',
  showPlusItemCounter:true,
  enableAutoFilter:true,
  showListCounter:false,
  errorMessage:'Please select an item from this list',
  on: {create: null,open: null,close: null,add: null,remove: null,
    change: null,blur: null,click: null,dblclick: null,mousemove: null,
    mouseover: null,mouseout: null,focus: null,mousedown: null,mouseup: null}
}
----

|`add`
|Add an item to select. You can pass second param as index; where you
want to insert this item. +

[source, js]
----
/**
* Object can be pass as below
* new Option("Label", "value") or
* {text:"Label", value:"value"}
* or Label as string
* or full object ie {text:"", value:"", description:'', image:'', className:'' title:'', imageCss:''}
* @param obj {option \| object}
* @param index {int}
*/
add(item, index);

// You may use any of the below example
//
ddSelect.add("HashtagCms");
ddSelect.add(new Option("HashtagCms", "https://www.hashtagcms.org"));
ddSelect.add({text:"HashtagCms", value:"https://www.hashtagcms.org"});
ddSelect.add({text:"HashtagCms", value:"https://www.hashtagcms.org", description:"Laravel open-source CMS"});
----

|`remove`
|Remove an item from <select>. And it returns the removed item with
uiData. +

[source, js]
----
/**
* @param index {int}
* @return uiData
*/
remove(index)
----

|`next`
|Move to the next index/item +

[source, js]
----
next()
----

|`previous`
|Move to the previous index/item +

[source, js]
----
previous()
----

|`open`
|Open the dropdown +

[source, js]
----
open()
----

|`close`
|Close the dropdown +

[source, js]
----
close()
----

|`namedItem`
|If you have given any name of an option, will be returned. say, <option
name="cd"></option> +

[source, js]
----
/**
* @param name {string}
* @param withData {boolean}
*/
namedItem(name, withData)
----

|`item`
|Return `<option>` element based on the index that you have passed in the
argument. `uiData` will also be returned if you pass withData=true +

[source, js]
----
/**
* @param index {int}
* @param withData {boolean}
*/
item(index, withData)
----

|`visible`
|Show hide or get status of visibility. +

[source, js]
----
/**
* @param isShow
* @return {boolean}
*/
visible
----

| `showRows` \| `visibleRows`
|Calculate first item height and set child height. +

[source, js]
----
/**
* @param numberOfRows {int}
*/
showRows(numberOfRows)
----

|`on`
|Add an event on the dropdown. Below are possible event types you can
pass in the argument:

`create` \| `open` \| `close` \| `add` \| `remove` \| `change` \|
`blur` \| `click` \| `dblclick` \| `mousemove` \| `mouseover` \|
`mouseout` \| `focus` \| `mousedown` \| `mouseup` +

[source, js]
----
/**
* @param type {string}
* @param fn {function}
*/
on(type, fn)
----

.Example
[source, js]
----
ddSelect.on("change", function() {console.log(ddSelect.uiData});
----

|`off`
|Remove event listener. +

[source, js]
----
/**
* @param type {string}
* @param fn {function}
*/
off(type, fn);
----

|`updateUiAndValue`
|In case there UI is not updated. You can call this method. +

[source, js]
----
updateUiAndValue()
----

|`refresh`
|Recreatea a msDropdown. +

[source, js]
----
refresh()
----

|`destroy`
|Remove msDropdown and returns back to the original dropdown. +

[source, js]
----
destroy()
----

|===


== Examples


=== Simple dropdown

Email FAQ Games Music Phone Graph Secured Video CD

There are two ways that you can apply msDropdown on <select> element

. You can add `is="ms-dropdown"`attributes. Like we have in the
below example.

[source, html]
----
<select class="tech" name="tech" is="ms-dropdown">
    <option value="" selected>Please select one</option>
    <option data-image="./dist/images/icons/icon_email.gif" value="email">Email</option>
    <option data-image="./dist/images/icons/icon_faq.gif" value="faq">FAQ</option>
    <option data-image="./dist/images/icons/icon_games.gif" value="games">Games</option>
    <option data-image="./dist/images/icons/icon_music.gif" value="music">Music</option>
    <option data-image="./dist/images/icons/icon_phone.gif" value="phone">Phone</option>
    <option data-image="./dist/images/icons/icon_sales.gif" value="graph">Graph</option>
    <option data-image="./dist/images/icons/icon_secure.gif" value="secured">Secured</option>
    <option data-image="./dist/images/icons/icon_video.gif" value="video">Video</option>
    <option data-image="./dist/images/icons/icon_cd.gif" name="cd" value="cd">CD</option>
</select>
----

[start=2]
. You don't need the below code if you have already included
  `dd.min.js` in the bottom of the page. Like I've mentioned in the
  installation section. +

In case you want to convert later by script, you can use the below code.
You may use a CSS selector too. +

[source, js]
----
MsDropdown.make('#select_element');
//or
new MsDropdown('.select_elements');
----

=== Dropdown with description

Did you notice? There is an extra attribute `data-description` in `<option>`.

[source, html]
----
<select id="payments" name="payments" is="ms-dropdown" data-enable-auto-filter="false" required>
  <option value="" data-description="Choose your payment gateway">Payment Gateway</option>
  <option value="amex" data-image="./dist/images/icons/Amex-56.png" data-description="My life. My card...">Amex</option>
  <option value="Discover" data-image="./dist/images/icons/Discover-56.png" data-description="It pays to Discover...">Discover</option>
  <option value="Mastercard" data-image="./dist/images/icons/Mastercard-56.png" data-title="For everything else..." data-description="For everything else...">Mastercard</option>
  <option value="cash" data-image="./dist/images/icons/Cash-56.png" data-description="Pay at your doorstep...">Cash on delivery</option>
  <option value="Visa" data-image="./dist/images/icons/Visa-56.png" data-description="All you need...">Visa</option>
  <option value="Paypal" data-image="./dist/images/icons/Paypal-56.png" data-description="Pay and get paid...">Paypal</option>
</select>
----

=== Dropdown with checkboxes

Email FAQ Games Music Phone Graph Secured Video CD

[source, html]
----
<select name="tech_with_checkbox" is="ms-dropdown" data-enable-checkbox="true">
  <option data-image="./dist/images/icons/icon_email.gif"  value="email">Email</option>
  <option data-image="./dist/images/icons/icon_faq.gif"  value="faq">FAQ</option>
  <option data-image="./dist/images/icons/icon_games.gif"  selected value="games">Games</option>
  <option data-image="./dist/images/icons/icon_music.gif" value="music">Music</option>
  <option data-image="./dist/images/icons/icon_phone.gif" value="phone">Phone</option>
  <option data-image="./dist/images/icons/icon_sales.gif"  value="graph">Graph</option>
  <option data-image="./dist/images/icons/icon_secure.gif" value="secured">Secured</option>
  <option data-image="./dist/images/icons/icon_video.gif" value="video">Video</option>
  <option data-image="./dist/images/icons/icon_cd.gif" name="cd" value="cd">CD</option>
</select>
----

=== Option groups

[source, html]
----
<select is="ms-dropdown" name="car_group">
  <optgroup label="Mercedes Benz">
    <option>Mercedes-Benz GLA</option>
    <option>Mercedes-Benz S-Class</option>
    <option>Mercedes-Benz E-Class</option>
    <option>Mercedes-Benz GLS</option>
  </optgroup>
  <optgroup label="Jaguar">
    <option>Jaguar F-TYPE</option>
    <option selected>Jaguar XE</option>
    <option>Jaguar F-Pace</option>
    <option>Jaguar I-Pace</option>
    <option>Jaguar XF</option>
  </optgroup>
</select>
----

=== Dropdown with CSS images

[source, html]
----
<select name="countries" id="countries" is="ms-dropdown" data-child-height="315">
  <option value='ad' data-image-css="flag ad" data-title="Andorra">Andorra</option>
  <option value='ae' data-image-css="flag ae" data-title="United Arab Emirates">United Arab Emirates</option>
  <option value='af' data-image-css="flag af" data-title="Afghanistan">Afghanistan</option>
  ...
  <option value='zr' data-image-css="flag zr" data-title="Zaire (former)">Zaire (former)</option>
  <option value='zw' data-image-css="flag zw" data-title="Zimbabwe">Zimbabwe</option>
</select>
----

=== Dropdown as a list

Please select one Email FAQ Games Music Phone Graph Secured Video CD

[source, html]
----
<select name="gameList[]" is="ms-dropdown" multiple size="5">
  <option value="" selected>Please select one</option>
  <option data-image="./dist/images/icons/icon_email.gif"  value="email">Email</option>
  <option data-image="./dist/images/icons/icon_faq.gif"  value="faq">FAQ</option>
  <option data-image="./dist/images/icons/icon_games.gif"  value="games">Games</option>
  <option data-image="./dist/images/icons/icon_music.gif" value="music">Music</option>
  <option data-image="./dist/images/icons/icon_phone.gif" value="phone">Phone</option>
  <option data-image="./dist/images/icons/icon_sales.gif"  value="graph">Graph</option>
  <option data-image="./dist/images/icons/icon_secure.gif" value="secured">Secured</option>
  <option data-image="./dist/images/icons/icon_video.gif" value="video">Video</option>
  <option data-image="./dist/images/icons/icon_cd.gif" name="cd" value="cd">CD</option>
</select>
----

=== Create Dropdown from JSON object

[source, js]
----
[
  {description:'Choose your payment gateway', value:'', text:'Payment Gateway'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Amex-56.png', description:'My life. My card...', value:'amex', text:'Amex'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Discover-56.png', description:'It pays to Discover...', value:'Discover', text:'Discover'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Mastercard-56.png', title:'For everything else...', description:'For everything else...', value:'Mastercard', text:'Mastercard'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Cash-56.png', description:'Sorry not available...', value:'cash', text:'Cash on delivery', disabled:true},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Visa-56.png', description:'All you need...', value:'Visa', text:'Visa'},
  {image:'/assets/mywork/web-components/image-dropdown/images/icons/Paypal-56.png', description:'Pay and get paid...', value:'Paypal', text:'Paypal'}
];
----

Below method is being called on "Click here to convert by above json"
button.

[source, html]
----
<script>
  function makeDd() {
    'use strict';
    //get the data from above json string
    let json = new function (`return ${document.getElementById('json_data').innerHTML}`)();
    //clean the holder
    document.getElementById("json_dropdown").innerHTML = "";

    //convert to msDropdown
    MsDropdown.make("#json_dropdown", {
        byJson: {
            data: json, selectedIndex: 0, name: "json_dropdown",
            size: 0, multiple: false, width: 450
        },
        enableAutoFilter:false
    });
    //or we can use like this too.
    /*new MsDropdown(document.getElementById("json_dropdown"), {
        byJson: {
            data: json, name: "json_dropdown"
        }
    });*/
  }
</script>
----

=== What are the settings params

If you are creating with the help of JavaScript you might need this.
So, how do you create it? Syntax is below

[source, js]
----
//Style 1
MsDropdown.make("element", {...settings});

//Style 2
new MsDropdown(document.getElementById("element_id"), {...settings});
----

And what are the settings params you can pass to the msDropdown? It is
similar to the data-attributes, those I've mentioned above in this
document. Only difference is that you passed as a camelCase key without
the "data-". For example if you want to set child width, you passed in
attribute as `data-child-width="300px"` whereas you need to pass in
settings as `childWidth:'300px'`

So, here is an example what you can pass in settings.

[source, js]
----
MsDropdown.make("element", {
  byJson: {
      data: null, selectedIndex: 0, name: null,
      size: 0, multiple: false, width: 250
      },
  mainCss: 'ms-dd',
  rowHeight: null,
  visibleRows: null,
  showIcon: true,
  zIndex: 9999,
  event:'click',
  style: '',
  childWidth:null,
  childHeight:null,
  enableCheckbox:false,
  checkboxNameSuffix:'_mscheck',
  showPlusItemCounter:true,
  enableAutoFilter:true,
  showListCounter:false,
  errorMessage:'Please select an item from this list',
  on: { create: null,open: null,close: null,add: null,remove: null,
        change: null,blur: null,click: null,dblclick: null,mousemove: null,
        mouseover: null,mouseout: null,focus: null,mousedown: null,
        mouseup: null
      }
});
----