j1-template 2021.2.10 → 2021.3.1

data/lib/starter_web/pages/public/manuals/dropdown-help.adoc

@@ -1,743 +1,743 @@
----
-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
-      }
-});
-----
+---
+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
+      }
+});
+----