Added the documentation for Sortable widget (#5358)

* Added the documentation for Sortable widget * Adjusting the sortable widget documentation * Adjusted the sortable widget documentation
magento · Sep 18, 2019 · aab6298 · aab6298
1 parent 3a300db
commit aab6298
Show file tree

Hide file tree

Showing 6 changed files with 133 additions and 0 deletions.
diff --git a/_data/toc/javascript-developer-guide.yml b/_data/toc/javascript-developer-guide.yml
@@ -109,6 +109,9 @@ pages:
         - label: RowBuilder widget
           url: /javascript-dev-guide/widgets/widget-row-builder.html
 
+        - label: Sortable widget
+          url: /javascript-dev-guide/widgets/widget-sortable.html
+
         - label: Sticky widget
           url: /javascript-dev-guide/widgets/widget_sticky.html
 

diff --git a/common/images/widget/sortable-widget-initial-result.png b/common/images/widget/sortable-widget-initial-result.png
diff --git a/common/images/widget/sortable-widget-sorted-result.png b/common/images/widget/sortable-widget-sorted-result.png
diff --git a/guides/v2.2/javascript-dev-guide/widgets/jquery-widgets-about.md b/guides/v2.2/javascript-dev-guide/widgets/jquery-widgets-about.md
@@ -29,6 +29,7 @@ This guide discusses the following widgets:
 -   [QuickSearch widget]
 -   [RedirectUrl widget]
 -   [RowBuilder widget]
+-   [Sortable widget]
 -   [Sticky widget]
 -   [Tabs widget]
 -   [ToggleAdvanced widget]
@@ -62,6 +63,7 @@ Magento out of the box does not contain jQuery UI styles. Also, it is not recomm
 [QuickSearch widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget_quickSearch.html
 [RedirectUrl widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget_redirectUrl.html
 [RowBuilder widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget-row-builder.html
+[Sortable widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget-sortable.html
 [Tabs widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget_tabs.html
 [ToggleAdvanced widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget_toggle.html
 [TrimInput widget]: {{page.baseurl}}/javascript-dev-guide/widgets/widget-trim-input.html

diff --git a/guides/v2.2/javascript-dev-guide/widgets/widget-sortable.md b/guides/v2.2/javascript-dev-guide/widgets/widget-sortable.md
@@ -0,0 +1,127 @@
+---
+group: javascript-developer-guide
+title: Sortable widget
+contributor_name: Atwix
+contributor_link: https://www.atwix.com/
+---
+
+The Sortable [widget](https://glossary.magento.com/widget/) is a customized jQuery [Sortable Widget][] that allows you to reorder sortable items using *Up* and *Down* buttons.
+
+The Sortable widget is only available in the [adminhtml](https://glossary.magento.com/adminhtml) area.
+
+The widget source file is [`<Magento_Theme_module_dir>/view/adminhtml/web/js/sortable.js`][].
+
+## Initialize the Sortable widget
+
+For information about how to initialize a widget in a JS component or `.phtml` template, see the [Initialize JavaScript][] topic.
+
+Use the `sortable()` function to instantiate the Sortable widget:
+
+```javascript
+$('#sortable').sortable();
+```
+
+Where:
+
+- `#sortable` is the selector of the block element where Sortable is initialized.
+
+The following example shows a PHTML file using the script:
+
+```html
+<script>
+    require([
+            'jquery',
+            'Magento_Theme/js/sortable'
+        ], function ($) {
+            'use strict';
+
+            $('#sortable').sortable();
+        });
+</script>
+```
+
+## Methods, Options and Events inheritance
+
+Most options, methods, and events for the Sortable widget correspond to the jQuery [Sortable Widget] options.
+
+## Options
+
+The Sortable has only two custom options that are different from default [Sortable Widget] options.
+
+- [moveUpEvent](#moveupevent)
+- [moveDownEvent](#movedownevent)
+
+### `moveUpEvent`
+
+The name of the event which moves a sortable item up.
+
+**Type**: String
+
+**Default value**: `'moveUp'`
+
+### `moveDownEvent`
+
+The name of the event which moves a sortable item down.
+
+**Type**: String
+
+**Default value**: `'moveDown'`
+
+## Code sample
+
+This example shows how to initialize the sortable widget.
+
+```html
+<ul id="sortable-list">
+    <li>
+        <div>
+            <span>Sortable Item #1</span>
+        </div>
+        <input type="button" class="up" title="Up" value="Up">
+        <input type="button" class="down" title="Down" value="Down">
+    </li>
+    <li>
+        <div>
+            <span>Sortable Item #2</span>
+        </div>
+        <input type="button" class="up" title="Up" value="Up">
+        <input type="button" class="down" title="Down" value="Down">
+    </li>
+    <li>
+        <div>
+            <span>Sortable Item #3</span>
+        </div>
+        <input type="button" class="up" title="Up" value="Up">
+        <input type="button" class="down" title="Down" value="Down">
+    </li>
+</ul>
+
+<script>
+require([
+    "jquery",
+    "jquery/ui",
+    "Magento_Theme/js/sortable"
+], function ($) {
+    'use strict';
+
+    $('#sortable-list').sortable({
+       axis: 'y',
+       tolerance: 'pointer',
+       items: 'li'
+    });
+});
+</script>
+```
+
+### Result
+
+As a result, we see the list of sortable items that can be sorted via *Up*, *Down* buttons or via dragging.
+
+![Sortable widget initial view Example]({{ site.baseurl }}/common/images/widget/sortable-widget-initial-result.png)
+![Sortable widget sorted view Example]({{ site.baseurl }}/common/images/widget/sortable-widget-sorted-result.png)
+
+<!-- Link Definitions -->
+
+[Sortable Widget]: https://api.jqueryui.com/sortable/
+[Initialize JavaScript]: {{page.baseurl}}/javascript-dev-guide/javascript/js_init.html
+[`<Magento_Theme_module_dir>/view/adminhtml/web/js/sortable.js`]: {{ site.mage2bloburl }}/{{ page.guide_version }}/app/code/Magento/Theme/view/adminhtml/web/js/sortable.js
diff --git a/guides/v2.3/javascript-dev-guide/widgets/widget-sortable.md b/guides/v2.3/javascript-dev-guide/widgets/widget-sortable.md
@@ -0,0 +1 @@
+../../../v2.2/javascript-dev-guide/widgets/widget-sortable.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		../../../v2.2/javascript-dev-guide/widgets/widget-sortable.md