From f03833fdc3bd06315a51de7edbb5f23c492ac8f8 Mon Sep 17 00:00:00 2001
From: Adam Kudrna <adam@adamkudrna.cz>
Date: Wed, 29 Jul 2015 21:15:12 +0200
Subject: [PATCH] Various docs fixes of JavaScript section

---
 .../javascript/ckeditor-loader.less           | 36 +++++------
 .../components/javascript/confirmation.less   | 23 +++++---
 .../javascript/datetimepicker-loader.less     | 14 +++--
 src/less/components/javascript/disable.less   | 19 +++---
 .../components/javascript/filterable.less     | 35 ++++++-----
 .../components/javascript/select2-loader.less | 41 +++++++------
 src/less/components/javascript/slugger.less   | 59 ++++++++++---------
 .../components/javascript/sortable-table.less | 33 ++++++-----
 8 files changed, 143 insertions(+), 117 deletions(-)

diff --git a/src/less/components/javascript/ckeditor-loader.less b/src/less/components/javascript/ckeditor-loader.less
index f0e15868..01daf028 100644
--- a/src/less/components/javascript/ckeditor-loader.less
+++ b/src/less/components/javascript/ckeditor-loader.less
@@ -1,34 +1,34 @@
 /*
 CKEditor Loader
 
-Initializes CKEditor WYSIWYG editor (http://ckeditor.com) on the given textarea element.
-It does no more then to run the $.ckeditor() method. It is possible to initialize the editor with default or custom options.
+Initializes [CKEditor WYSIWYG editor](http://ckeditor.com) on the given `<textarea>` element.
+It does no more then to run the `$.ckeditor()` method. It is possible to initialize the editor with default or custom
+options.
 
 <div class="panel panel-danger">
     <div class="panel-heading"><h4 class="panel-title">JavaScript Required</h4></div>
     <div class="panel-body">
-        Script `ckeditor-loader.js` `CKEditor package` and `CKEditor jQuery adapter` must be included.
+        Script `ckeditor-loader.js`, **CKEditor package** and **CKEditor jQuery adapter** must be included.
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
 
-<h4>Data-api</h4>
-This loader only calls the jQuery plugin defined in CKEditor jQuery adapter with appropriate arguments. Id does nothing else.
+This loader only calls the jQuery plugin defined in CKEditor jQuery adapter with appropriate arguments. Id does nothing
+else.
 
-<h4>Data-api</h4>
-If a textarea html element has the attribute `data-onload-ckeditor` defined it will be initialized as a CKEditor upon page load.
-The editor can be configured by the value passed to the attribute.
-If no value is passed then CKEditor is initiated with the default configuration.
-If it the value is a valid json then it will be parsed and used as a configuration object
-(see http://docs.ckeditor.com/#!/api/CKEDITOR.config for supported options).
-If the value is not a valid json, then it will be used as a path to a editor config file to be used
-(see http://docs.ckeditor.com/#!/guide/dev_configuration-section-using-a-custom-configuration-file for custom config file documentation).
+#### Data-API
+
+If a `<textarea>` HTML element has the attribute `data-onload-ckeditor` defined, it will be initialized as a CKEditor
+upon page load. The editor can be configured by the value passed to the attribute. If no value is passed, then CKEditor
+is initiated with default configuration. If the value is a valid JSON, then it will be parsed and used as a
+configuration object (see http://docs.ckeditor.com/#!/api/CKEDITOR.config for supported options). If the value is not a
+valid JSON, then it will be used as a path to an editor config file to be used
+(see http://docs.ckeditor.com/#!/guide/dev_configuration-section-using-a-custom-configuration-file for custom config
+file documentation).
 
 Markup:
-<form>
-    <textarea data-onload-ckeditor='{"uiColor": "6D9000"}'>Hi, I'm a textarea and Im wearing a fancy CKEditor dress.</textarea>
-</form>
+<textarea data-onload-ckeditor='{"language": "en"}'>Hi, I’m a textarea and I’m wearing a fancy CKEditor dress.</textarea>
 
-Styleguide 6.5
+Styleguide 6.6
 */
diff --git a/src/less/components/javascript/confirmation.less b/src/less/components/javascript/confirmation.less
index 9da890fe..f445834c 100644
--- a/src/less/components/javascript/confirmation.less
+++ b/src/less/components/javascript/confirmation.less
@@ -30,19 +30,21 @@ appropriately or by overriding the plugin default options which affects all inst
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
 
-<h4>Data-api</h4>
+#### Data-API
 
 To bind confirmation dialog to an element, the element must have `data-toggle="confirm"` attribute defined.
 
-To overload the default options, you can use the same options as the JavaScript api prepended with `data-` (i.e. `data-confirm-yes="Oui"`).
+To override default options, you can use the same options as the JavaScript API prepended with `data-`
+(i.e. `data-confirm-yes="Oui"`).
 
-This components data-api only supports `<button>` elements.
+**Note that this component only supports `<button>` elements.**
 
-<h4>JavaScript</h4>
+#### JavaScript
+
+##### Options
 
-<h5>Options</h5>
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
@@ -74,11 +76,14 @@ This components data-api only supports `<button>` elements.
     </tbody>
 </table>
 
-<h5>Methods</h5>
-<h6>$().showConfirmation()</h6>
+##### Methods
+
+###### $().showConfirmation()
+
 Triggers a confirmation dialog on the given element.
 
-<h3>Events</h3>
+##### Events
+
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
diff --git a/src/less/components/javascript/datetimepicker-loader.less b/src/less/components/javascript/datetimepicker-loader.less
index a06c3151..e6b53238 100644
--- a/src/less/components/javascript/datetimepicker-loader.less
+++ b/src/less/components/javascript/datetimepicker-loader.less
@@ -8,16 +8,18 @@ Initializes [Bootstrap Datetimepicker](http://eonasdan.github.io/bootstrap-datet
 <div class="panel panel-danger">
     <div class="panel-heading"><h4 class="panel-title">JavaScript Required</h4></div>
     <div class="panel-body">
-        Scripts `datetimepicker-loader.js`, `moment.js`, `bootstrap.js` and `bootstrap-datetimepicker.js` must be included.
+        Scripts `datetimepicker-loader.js`, `moment.js` (this one before `bootstrap.js`) and `bootstrap-datetimepicker.js` must be included.
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
+
 This loader only calls the jQuery plugin defined in bootstrap-datetimepicker component. It does nothing else.
 
-<h4>Data-API</h4>
-If an input has the attribute `data-onload-datetimepicker` defined it will be initialized with a datetimepicker
-upon page load. The picker can be configured by the value passed to the attribute. If no value is passed, picker is
+#### Data-API
+
+If an input group has the attribute `data-onload-datetimepicker` defined, it will be initialized with a datetimepicker
+upon page load. The picker can be configured by the value passed to the attribute. If no value is passed, the picker is
 initiated with default configuration. If the value is a valid JSON, then it will be parsed and used as a configuration
 object (see http://eonasdan.github.io/bootstrap-datetimepicker/Options for supported options).
 
@@ -47,5 +49,5 @@ Markup:
     </div>
 </div>
 
-Styleguide 6.6
+Styleguide 6.7
 */
diff --git a/src/less/components/javascript/disable.less b/src/less/components/javascript/disable.less
index 235f74fa..7164665f 100644
--- a/src/less/components/javascript/disable.less
+++ b/src/less/components/javascript/disable.less
@@ -1,7 +1,7 @@
 /*
 Disable
 
-Toogles the disabled property on DOM elements.
+Toggles the disabled property on DOM elements.
 
 <div class="panel panel-danger">
     <div class="panel-heading"><h4 class="panel-title">JavaScript Required</h4></div>
@@ -10,25 +10,28 @@ Toogles the disabled property on DOM elements.
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
 
-<h4>Data-api</h4>
+#### Data-API
 
 To use an element as control element for toggling disable status on other elements, it must possess the
 `data-toggle="disable"` attribute. It also must define the `data-disable-target` attribute that holds a string which,
 when evaluated as a jQuery selector, returns a jQuery object referencing the elements that are to be disabled or
 enabled.
 
-By default the control element triggers the disable() method on the JS event `change`. This can be changed by
+By default the control element triggers the `disable()` method on the JS event `change`. This can be changed by
 specifying the `data-disable-event` attribute on the control element (i.e. `data-disable-event="click"`).
 
-<h4>JavaScript</h4>
+#### JavaScript
+
+##### Methods
+
+###### $().toggle()
 
-<h5>Methods</h5>
-<h6>$().toggle()</h6>
 Toggles between enabled and disabled states.
 
-<h3>Events</h3>
+##### Events
+
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
diff --git a/src/less/components/javascript/filterable.less b/src/less/components/javascript/filterable.less
index ef1eb7ab..d66ae587 100644
--- a/src/less/components/javascript/filterable.less
+++ b/src/less/components/javascript/filterable.less
@@ -9,10 +9,10 @@ filtered. If a data attribute is not provided, the element is ignored by the fil
 is treated as if it passed the filter.
 
 The options to be passed to the Filterable plugin are always an array of filter definition objects. If using the
-data-api, each of these object has to be represented by a single `:input` element with the appropriate `data-*`
+data-API, each of these objects has to be represented by a single `:input` element with the appropriate `data-*`
 attributes.
 
-To allow users to view all filterable elements when using the data-api, simply place a button with `type="reset"`
+To allow users to view all filterable elements when using the data-API, simply place a button with `type="reset"`
 attribute within the filter `<form>`.
 
 <div class="panel panel-danger">
@@ -22,21 +22,23 @@ attribute within the filter `<form>`.
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
 
-<h4>Data-api</h4>
+#### Data-API
 
-The filter has to be a `<form>` with a `data-filter-target` attribute containing a string which, when evaluated as a jQuery
-selector, returns a jQuery object holding the DOM elements to be filtered.
+The filter has to be a `<form>` with a `data-filter-target` attribute containing a string which, when evaluated as a
+jQuery selector, returns a jQuery object holding the DOM elements to be filtered.
 
-Each of the `:input` elements of the form that are to be used for filtering have to define the `data-toggle="filter"` attribute.
-Further each one also has to possess the `data-filter-attrib` and `data-filter-operator` attributes (see the Filter Object section bellow)
+Each of the `:input` elements of the form that are to be used for filtering have to define the `data-toggle="filter"`
+attribute. Further each one also has to possess the `data-filter-attrib` and `data-filter-operator` attributes (see the
+Filter Object section below).
 
 The element that is to reset the filter on click has to have the `data-toggle="reset-filter"` attribute defined.
 
-<h4>JavaScript</h4>
+#### JavaScript
+
+##### Filter Object
 
-<h5>Filter Object</h5>
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
@@ -139,13 +141,18 @@ The element that is to reset the filter on click has to have the `data-toggle="r
     </tbody>
 </table>
 
-<h5>Methods</h5>
-<h6>$().filter(filterObjects)</h6>
+##### Methods
+
+###### $().filter(filterObjects)
+
 Filters the set of elements on which it is called according to the given array of filter objects.
-<h6>$().resetFilter)</h6>
+
+###### $().resetFilter)
+
 Displays all filterable elements.
 
-<h3>Events</h3>
+##### Events
+
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
diff --git a/src/less/components/javascript/select2-loader.less b/src/less/components/javascript/select2-loader.less
index 826cb4d4..cffa9c2f 100644
--- a/src/less/components/javascript/select2-loader.less
+++ b/src/less/components/javascript/select2-loader.less
@@ -1,36 +1,35 @@
 /*
 Select2 Loader
 
-Initializes select2 (https://select2.github.io) on the given html element.
-It does no more then to run the $.select2() method. It is possible to initialize the widget with default or custom options.
+Initializes [select2](https://select2.github.io) on the given `<select>` element.
+It does no more then to run the `$.select2()` method. It is possible to initialize the widget with default or custom
+options.
 
 <div class="panel panel-danger">
     <div class="panel-heading"><h4 class="panel-title">JavaScript Required</h4></div>
     <div class="panel-body">
-        Scripts `select2-loader.js` and `select2 package` must be included.
+        Script `select2-loader.js` and **select2 package** must be included.
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
 
-<h4>Data-api</h4>
-This loader only calls the jQuery plugin defined in the select2 library with appropriate arguments. Id does nothing else.
+This loader only calls the jQuery plugin defined in the select2 library with appropriate arguments. It does nothing
+else.
 
-<h4>Data-api</h4>
-If a html element has the attribute `data-onload-select2` defined it will be initialized as a select2 upon page load.
-The widget can be configured by the value passed to the attribute.
-If no value is passed then select2 is initiated with teh default configuration.
-If a json object is passed in then it will be parsed and used as a configuration object
-(see https://select2.github.io/options.html for supported options).
+#### Data-API
+
+If a `<select>` element has the attribute `data-onload-select2` defined, it will be initialized as a select2 upon page
+load. The widget can be configured by the value passed to the attribute. If no value is passed, then select2 is
+initiated with default configuration. If a JSON object is passed, then it will be parsed and used as a configuration
+object (see https://select2.github.io/options.html for supported options).
 
 Markup:
-<form>
-    <select multi data-onload-select2='{"minimumResultsForSearch": "Infinity"}'>
-        <option>Option 1</option>
-        <option>Option 2</option>
-        <option>Option 3</option>
-    </select>
-</form>
-
-Styleguide 6.6
+<select class="form-control" multiple data-onload-select2='{"minimumResultsForSearch": "Infinity"}'>
+    <option selected>Option 1</option>
+    <option>Option 2</option>
+    <option>Option 3</option>
+</select>
+
+Styleguide 6.8
 */
diff --git a/src/less/components/javascript/slugger.less b/src/less/components/javascript/slugger.less
index 42520b90..e6d0a485 100644
--- a/src/less/components/javascript/slugger.less
+++ b/src/less/components/javascript/slugger.less
@@ -2,7 +2,8 @@
 Slugger
 
 Creates a slug in one HTML form element based on value in another.
-The relationship is unidirectional in the sense that changes made to source element affect the target element, but not vice versa.
+The relationship is unidirectional in the sense that changes made to source element affect the target element, but not
+vice versa.
 
 <div class="panel panel-danger">
     <div class="panel-heading"><h4 class="panel-title">JavaScript Required</h4></div>
@@ -11,21 +12,24 @@ The relationship is unidirectional in the sense that changes made to source elem
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
 
-<h4>Data-api</h4>
+#### Data-API
 
-To make this component function there must be two HTML form elements.
-One is the source where user types text and the other is the target where slugger dynamically generates the slug.
+To make this component function there must be two HTML form elements. One is the source where user types text and the
+other is the target where slugger dynamically generates the slug.
 
-Two attributes have to be defined on the source element.
-`data-toggle="slugger"`indicates that the elements value will be used as the string from which the slug is to be generated..
-`data-slugger-target="#id-of-the-target-element"` defines the jQuery selector of the HTML form element where
+Two attributes have to be defined on the source element:
+
+* `data-toggle="slugger"`indicates that the element’s value will be used as the string from which the slug is to be
+generated.
+* `data-slugger-target="#id-of-the-target-element"` defines the jQuery selector of the HTML form element where
 the generated slug is to be displayed.
 
-<h4>JavaScript</h4>
+#### JavaScript
+
+##### Options
 
-<h5>Options</h5>
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
@@ -45,11 +49,14 @@ the generated slug is to be displayed.
     </tbody>
 </table>
 
-<h5>Methods</h5>
-<h6>$().updateSlug()</h6>
+##### Methods
+
+###### $().updateSlug()
+
 Sets slug generated as the value of the target element based on the value of the source element.
 
-<h3>Events</h3>
+##### Events
+
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
@@ -70,22 +77,20 @@ Sets slug generated as the value of the target element based on the value of the
 </table>
 
 Markup:
-<form>
-    <div class="row">
-        <div class="col-sm-6">
-            <div class="form-group">
-                <label>Source</label>
-                <input type="text" class="form-control" data-toggle="slugger" data-slugger-target="#slugger-target" />
-            </div>
+<div class="row">
+    <div class="col-sm-6">
+        <div class="form-group">
+            <label>Source</label>
+            <input type="text" class="form-control" data-toggle="slugger" data-slugger-target="#slugger-target" />
         </div>
-        <div class="col-sm-6">
-            <div class="form-group">
-                <label>Target</label>
-                <input type="text" class="form-control" id="slugger-target" />
-            </div>
+    </div>
+    <div class="col-sm-6">
+        <div class="form-group">
+            <label>Target</label>
+            <input type="text" class="form-control" id="slugger-target" />
         </div>
     </div>
-</form>
+</div>
 
-Styleguide 6.7
+Styleguide 6.5
 */
diff --git a/src/less/components/javascript/sortable-table.less b/src/less/components/javascript/sortable-table.less
index 7dc3ebb5..953f3d41 100644
--- a/src/less/components/javascript/sortable-table.less
+++ b/src/less/components/javascript/sortable-table.less
@@ -11,7 +11,6 @@ To initialize the component taking into account that the data is already sorted
 a `.sorting-asc` and `.sorting-desc` can be added to the relevant `<th>` to indicate the column and direction of the
 default sorting.
 
-
 <div class="panel panel-danger">
     <div class="panel-heading"><h4 class="panel-title">JavaScript Required</h4></div>
     <div class="panel-body">
@@ -27,22 +26,25 @@ default sorting.
     </div>
 </div>
 
-<h3>Usage</h3>
+### Usage
+
+#### Data-API
 
-<h4>Data-api</h4>
+To use sortable-table via data-API, `data-toggle="sort"` has to be defined on the `<th>` that should trigger sorting on
+click.
 
-To use sortable-table via data-api, `data-toggle="sort"` has to be defined on the `<th>` that should trigger sorting on click.
+In order to utilize the navigation feature, `data-sort-navigation` has to be defined on the `<table>` element and it
+must contain a string that, when evaluated as a jQuery selector, will return a jQuery object referencing the navigation
+container DOM element.
 
-In order to utilize the navigation feature, `data-sort-navigation` has to be defined on the `<table>`element and it must contain a string that
-when evaluated as a jQuery selector will return a jQuery object referencing teh navigation container DOM element.
+Forcing sorting of a given table on page load (and potentially generating group headers and navigation) can be achieved
+by specifying the attribute `data-sort-onload` on the appropriate `<th>`. This attribute takes the value of either `asc`
+or `desc` to indicate the sorting order.
 
-Forcing sorting of a given table on page load (and potentially generating group headers and navigation) can be
-achieved by specifying the attribute `data-sort-onload` on the appropriate `<th>`. This attribute takes the value
-of either `asc` or `desc` to indicate the sorting order.
+#### JavaScript
 
-<h4>JavaScript</h4>
+##### Options
 
-<h5>Options</h5>
 <table class="table table-bordered table-striped">
     <thead>
         <tr>
@@ -78,11 +80,14 @@ of either `asc` or `desc` to indicate the sorting order.
     </tbody>
 </table>
 
-<h5>Methods</h5>
-<h6>$().sortableTable(options)</h6>
+##### Methods
+
+###### $().sortableTable(options)
+
 Initiates a sortable table if needed and performs the sorting according to the options object.
 
-<h3>Events</h3>
+##### Events
+
 <table class="table table-bordered table-striped">
     <thead>
         <tr>