Merge pull request #5354 from serhiyzhovnir/update-multiselect-widget-documentation

Update Multiselect Widget Documentation

Author: dobooth

guides/v2.2/javascript-dev-guide/widgets/widget-multiselect.md

@@ -19,9 +19,7 @@ The following example shows how to instantiate the Multiselect widget:
 $("#multiselect").multiselect2({});
 ```
 
-Where:
-
-- `#multiselect` is the selector of the select element for which Multiselect is initialized.
+where `#multiselect` is the selector of the select element for which Multiselect is initialized.
 
 The following example shows a PHTML file using the script:
 
@@ -42,31 +40,40 @@ The following example shows a PHTML file using the script:
 
 The RedirectUrl widget has the following options:
 
-- [mselectContainer](#mselectcontainer)
-- [mselectItemsWrapperClass](#mselectitemswrapperclass)
-- [mselectCheckedClass](#mselectcheckedclass)
-- [containerClass](#containerclass)
-- [searchInputClass](#searchinputclass)
-- [selectedItemsCountClass](#selecteditemscountclass)
-- [currentPage](#currentpage)
-- [lastAppendValue](#lastappendvalue)
-- [updateDelay](#updatedelay)
+-  [containerClass](#containerclass)
+-  [currentPage](#currentpage)
+-  [lastAppendValue](#lastappendvalue)
+-  [mselectCheckedClass](#mselectcheckedclass)
+-  [mselectContainer](#mselectcontainer)
+-  [mselectItemsWrapperClass](#mselectitemswrapperclass)
+-  [nextPageUrl](#nextpageurl)
+-  [searchInputClass](#searchinputclass)
+-  [selectedItemsCountClass](#selecteditemscountclass)
+-  [updateDelay](#updatedelay)
 
-### `mselectContainer`
+### `containerClass`
 
-Multiselect container selector.
+The class which is attached to the container with [multi-select container selector](#mselectcontainer).
 
 **Type**: String
 
-**Default value**: `'section.mselect-list'`
+**Default value**: `'paginated'`
 
-### `mselectItemsWrapperClass`
+### `currentPage`
 
-Multiselect items wrapper class.
+Current page of multi-select items.
 
-**Type**: String
+**Type**: Integer
 
-**Default value**: `'mselect-items-wrapper'`
+**Default value**: `1`
+
+### `lastAppendValue`
+
+The value of the last added multi-select item.
+
+**Type**: Integer, String
+
+**Default value**: `0`
 
 ### `mselectCheckedClass`
 
@@ -76,13 +83,48 @@ The class which is attached to a checked multi-select item.
 
 **Default value**: `'mselect-checked'`
 
-### `containerClass`
+### `mselectContainer`
 
-The class which is attached to the container with [multi-select container selector](#mselectcontainer).
+Multiselect container selector.
 
 **Type**: String
 
-**Default value**: `'paginated'`
+**Default value**: `'section.mselect-list'`
+
+### `mselectItemsWrapperClass`
+
+Multiselect items wrapper class.
+
+**Type**: String
+
+**Default value**: `'mselect-items-wrapper'`
+
+### `nextPageUrl`
+
+The url of the controller or API which returns the JSON response.
+
+```json
+{
+  "success": true,
+  "errorMessage": "",
+  "result": [
+    {
+      "value": "1",
+      "label": "Multi-select item label #1"
+    },
+    {
+      "value": "2",
+      "label": "Multi-select item label #2"
+    }
+  ]
+}
+```
+
+An example of the controller: [`<Magento_Tax_module_dir>/Controller/Adminhtml/Rule/AjaxLoadRates.php`][]
+
+**Type**: String
+
+**Default value**: `undefined`
 
 ### `searchInputClass`
 
@@ -100,29 +142,92 @@ Class of the selected items counter.
 
 **Default value**: `'admin__action-multiselect-search'`
 
-### `currentPage`
+### `updateDelay`
 
-Current page of multi-select items.
+The search field update delay.
 
-**Type**: Integer
+**Type**: Integer, String
 
-**Default value**: `1`
+**Default value**: `0`
 
-### `lastAppendValue`
+## Methods
 
-The value of the last added multi-select item.
+The Multiselect methods are the following:
 
-**Type**: Integer, String
+- [appendOptions()](#appendoptions)
+- [clearMultiselectOptions()](#clearmultiselectoptions)
+- [getCurrentPage()](#getcurrentpage)
+- [getSearchCriteria()](#getsearchcriteria)
+- [isOptionsLoaded()](#isoptionsloaded)
+- [loadOptions()](#loadoptions)
+- [setCurrentPage()](#setcurrentpage)
 
-**Default value**: `0`
+### `appendOptions`
 
-### `updateDelay`
+The method appends multi-select items to the multi-select.
 
-The search field update delay.
+Code example:
 
-**Type**: Integer, String
+```javascript
+$('#multiselect').multiselect2('appendOptions', [{"value": "1", "label": "Label #1"}, {"value": "2", "label": "Label #2"}]);
+```
 
-**Default value**: `0`
+### `clearMultiselectOptions`
+
+The method removes all multi-select items.
+
+Code example:
+
+```javascript
+$('#multiselect').multiselect2('clearMultiselectOptions');
+```
+
+### `getCurrentPage`
+
+The method returns the number of the current page.
+
+```javascript
+$('#multiselect').multiselect2('getCurrentPage');
+```
+
+### `getSearchCriteria`
+
+The method returns the trimmed value of the search input.
+
+Code example:
+
+```javascript
+$('#multiselect').multiselect2('getSearchCriteria');
+```
+
+### `isOptionsLoaded`
+
+The method checks if all multi-select items are already loaded.
+
+```javascript
+$('#multiselect').multiselect2('isOptionsLoaded', [{"value": "2", "label": "Label #2"}]);
+```
+
+This method returns `true` if multiple selection items are loaded, and it returns `false` if they are not loaded.
+
+### `loadOptions`
+
+The method loads the next page with multi-select items from [nextPageUrl](#nextpageurl) according to the [search criteria](#getsearchcriteria).
+The multi-select items from the Ajax response are appended to the multi-select.
+
+Code example:
+
+```javascript
+$('#multiselect').multiselect2('loadOptions');
+```
+
+### `setCurrentPage`
+
+The method configures the current page number.
+
+```javascript
+$('#multiselect').multiselect2('setCurrentPage', 2);
+```
 
 ## Code sample
 
@@ -156,3 +261,4 @@ You can now search for an option in the search bar and the **Add new value** but
 <!-- Link Definitions -->
 [lib/web/mage/multiselect.js]: {{ site.mage2bloburl }}/{{ page.guide_version }}/lib/web/mage/multiselect.js
 [Initialize JavaScript]: {{page.baseurl}}/javascript-dev-guide/javascript/js_init.html
+[`<Magento_Tax_module_dir>/Controller/Adminhtml/Rule/AjaxLoadRates.php`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Tax/Controller/Adminhtml/Rule/AjaxLoadRates.php