MAGEDOC-3441: Edit Knockout bindings topic

- Update bindings topic

Author: davemacaulay

docs/reference/knockout-bindings.md

@@ -2,56 +2,83 @@
 
 ## Summary
 
-As part of the Page Builder application, we provide new Knockout bindings you can use in your custom content types:
+As part of the Page Builder application, we provide a number of new Knockout bindings to add additional functionality to certain content types through Knockouts binding syntax.
 
-| Name           | Description                                                    | Usage                                  |
-| -------------- | -------------------------------------------------------------- | -------------------------------------  |
-| sortable       | Enables sorting the children of a bound element.               | \<div data-bind="sortable: {}"></div>  |
-| draggable      | Enables draggable functionality on DOM elements.               | \<div data-bind="draggable: {}"></div> |
-| live-edit      | Enables editing text directly from the Admin stage.            | \<div data-bind="liveEdit: {}"></div>  |
-| focus          | Enables default focus on DOM elements.                         | \<div data-bind="hasFocusNoScroll: $parent.focusedSlide() === $index()"></div>     |
+| Binding Name   | Description                                                    | 
+| -------------- | -------------------------------------------------------------- |
+| `sortable`       | Enables sorting the children of a bound element. We use this within container content types such as the root container, row and columns to enable drag and drop capabilities on their children content types. This can be used for easy access to the jQuery UI sortable functionality within your module. |
+| `draggable`      | Enables draggable functionality on DOM elements. We use this to enable the content types in the left menu to be dragged and dropped into containers on the stage. |              
+| `liveEdit`      | Enables basic live text editing on the stage, this also supports displaying additional items within the live edit UI for easier modification. You can read more about how to use live edit within our [How to add a custom Toolbar](../how-to/how-to-add-custom-toolbar.md) guide. |           
+| `hasFocusNoScroll` | Enables an element to use Knockout `hasFocus` binding without it causing the browser to scroll to the element, we use this within Slider to ensure the correct slide is focused but we do not want to scroll this into view always. |        
+{:style="table-layout:auto"}
 
-### Sortable binding
+### `sortable` binding
 
 ```shell
-app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/binding/sortable.ts
+view/adminhtml/web/ts/js/binding/sortable.ts
 ```
 
-The options in this binding are passed to the jQuery UI sortable instance. All options and their descriptions are available on the jQuery UI site: http://api.jqueryui.com/sortable/.
+This binding serves as an interface for jQuery UI Sortable.
 
 Within Page Builder, we use the `sortable` binding to pass preview-component options to the drag-and-drop binding. We bind multiple options and events to the `sortable` instance so we can correctly respond to user actions when dragging and dropping content. Configuration and usage of the `sortable` binding can be seen in the Preview component:
 
-Example Configuration:
+**Configuration:**
 
-```shell
-app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/content-type/preview.ts
-```
+Please see the options listed on jQuery UI's Sortable API page: http://api.jqueryui.com/sortable/
 
-Example Usage:
+**Usage:**
 
-```shell
-app/code/Magento/PageBuilder/view/adminhtml/web/template/content-type/preview.html
+```html
+<div data-bind="sortable: getSortableOptions()" />
 ```
+_As jQuery UI can have callback functions we recommend providing this configuration from a function within your Knockout view model._
 
-### Draggable binding
+### `draggable` binding
 
 ```shell
-app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/binding/draggable.ts
+view/adminhtml/web/ts/js/binding/draggable.ts
 ```
 
-The options provided in this binding are passed to the jQuery UI draggable instance. All options and their descriptions are available on the jQuery UI site: http://api.jqueryui.com/draggable/.
+This binding serves as an interface for jQuery UI Draggable.
 
 Within Page Builder, we use this binding for the left panel's content types. The configuration and usage of the `draggable` binding can be seen in the Panel component:
 
-Example Configuration:
+**Configuration:**
 
-```shell
-app/code/Magento/PageBuilder/view/adminhtml/web/ts/js/panel.ts
+Please see the options listed on jQuery UI's Sortable API page: http://api.jqueryui.com/draggable/
+
+**Usage:**
+
+```html
+<div data-bind="draggable: getDraggableOptions()" />
 ```
+_As jQuery UI can have callback functions we recommend providing this configuration from a function within your Knockout view model._
 
-Example Usage:
+### `liveEdit` binding
 
-```shell
-app/code/Magento/PageBuilder/view/adminhtml/web/template/panel.html
+This binding provides basic text live editing functionality to the current element, it does this by adding the `contenteditable` functionality to the bound element.
+
+**Configuration:**
+
+| Name           | Description                                                    | 
+| -------------- | -------------------------------------------------------------- |
+| `field`        | The field name from the UI component form which you wish the live edit instance to edit. | 
+| `placeholder`  | _Optional_. A placeholder to display if there is no data for this field.
+| `selectAll`    | _Optional_. Selects all text on focus within the live edit field. We use this within tabs. |           
+{:style="table-layout:auto"}
+
+**Usage:**
+```html
+<div data-bind="liveEdit: { field: 'field', placeholder: $t('Placeholder'), selectAll: true }" />
 ```
 
+### `hasFocusNoScroll` binding
+
+This binding enables the functionality of Knockout's [hasFocus](https://knockoutjs.com/documentation/hasfocus-binding.html) binding whilst removing the automatic scrolling that will occur when focusing an element within the browser.
+
+The binding has no configuration and must be passed an observable with a boolean value. 
+
+**Usage:**
+```html
+<div data-bind="hasFocusNoScroll: anObservable" />
+```