j1-template 2021.2.0 → 2021.2.4

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

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