Merge branch 'nav-on-droplab-plugins' into 'master'

docs: Add navigation to DropLab plugins on Frontend Development Guide

See merge request gitlab-org/gitlab!47752

doc/development/fe_guide/droplab/droplab.md

@@ -10,19 +10,20 @@ A generic dropdown for all of your custom dropdown needs.
 
 ## Usage
 
-DropLab can be used by simply adding a `data-dropdown-trigger` HTML attribute.
-This attribute allows us to find the "trigger" _(toggle)_ for the dropdown,
-whether that is a button, link or input.
+DropLab can be used by adding a `data-dropdown-trigger` HTML attribute. This
+attribute allows us to find the "trigger" _(toggle)_ for the dropdown, whether
+it's a button, link or input.
 
-The value of the `data-dropdown-trigger` should be a CSS selector that
-DropLab can use to find the trigger's dropdown list.
+The value of the `data-dropdown-trigger` should be a CSS selector that DropLab
+can use to find the trigger's dropdown list.
 
 You should also add the `data-dropdown` attribute to declare the dropdown list.
 The value is irrelevant.
 
-The DropLab class has no side effects, so you must always call `.init` when
-the DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`.
-If you do not provide any arguments, it will globally query and instantiate all droplab compatible dropdowns.
+The DropLab class has no side effects, so you must always call `.init` when the
+DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`.
+If you don't provide any arguments, it will globally query and instantiate all
+DropLab-compatible dropdowns.
 
 ```html
 <a href="#" data-dropdown-trigger="#list">Toggle</a>
@@ -37,8 +38,8 @@ const droplab = new DropLab();
 droplab.init();
 ```
 
-As you can see, we have a "Toggle" link, that is declared as a trigger.
-It provides a selector to find the dropdown list it should control.
+As noted, we have a "Toggle" link that's declared as a trigger. It provides a
+selector to find the dropdown list it should control.
 
 ### Static data
 
@@ -60,8 +61,8 @@ droplab.init();
 
 ### Explicit instantiation
 
-You can pass the trigger and list elements as constructor arguments to return
-a non-global instance of DropLab using the `DropLab.prototype.init` method.
+You can pass the trigger and list elements as constructor arguments to return a
+non-global instance of DropLab using the `DropLab.prototype.init` method.
 
 ```html
 <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
@@ -102,12 +103,13 @@ droplab.addHook(trigger, list);
 
 ### Dynamic data
 
-Adding `data-dynamic` to your dropdown element will enable dynamic list rendering.
+Adding `data-dynamic` to your dropdown element will enable dynamic list
+rendering.
 
-You can template a list item using the keys of the data object provided.
-Use the handlebars syntax `{{ value }}` to HTML escape the value.
-Use the `<%= value %>` syntax to simply interpolate the value.
-Use the `<%= value %>` syntax to evaluate the value.
+You can template a list item using the keys of the data object provided. Use the
+handlebars syntax `{{ value }}` to HTML escape the value. Use the `<%= value %>`
+syntax to interpolate the value. Use the `<%= value %>` syntax to evaluate the
+value.
 
 Passing an array of objects to `DropLab.prototype.addData` will render that data
 for all `data-dynamic` dropdown lists tracked by that DropLab instance.
@@ -132,8 +134,9 @@ droplab.init().addData([{
 }]);
 ```
 
-Alternatively, you can specify a specific dropdown to add this data to but passing
-the data as the second argument and the `id` of the trigger element as the first argument.
+Alternatively, you can specify a specific dropdown to add this data to by
+passing the data as the second argument and the `id` of the trigger element as
+the first argument.
 
 ```html
 <a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a>
@@ -155,7 +158,7 @@ droplab.init().addData('trigger', [{
 }]);
 ```
 
-This allows you to mix static and dynamic content with ease, even with one trigger.
+This allows you to mix static and dynamic content, even with one trigger.
 
 Note the use of scoping regarding the `data-dropdown` attribute to capture both
 dropdown lists, one of which is dynamic.
@@ -191,12 +194,13 @@ DropLab adds some CSS classes to help lower the barrier to integration.
 
 For example:
 
-- The `droplab-item-selected` CSS class is added to items that have been selected
-  either by a mouse click or by enter key selection.
+- The `droplab-item-selected` CSS class is added to items that have been
+  selected either by a mouse click or by enter key selection.
 - The `droplab-item-active` CSS class is added to items that have been selected
   using arrow key navigation.
-- You can add the `droplab-item-ignore` CSS class to any item that you do not want to be selectable. For example,
-  an `<li class="divider"></li>` list divider element that should not be interactive.
+- You can add the `droplab-item-ignore` CSS class to any item that you don't
+  want to be selectable. For example, an `<li class="divider"></li>` list
+  divider element that shouldn't be interactive.
 
 ## Internal events
 
@@ -204,26 +208,33 @@ DropLab uses some custom events to help lower the barrier to integration.
 
 For example:
 
-- The `click.dl` event is fired when an `li` list item has been clicked. It is also
-  fired when a list item has been selected with the keyboard. It is also fired when a
-  `HookButton` button is clicked (a registered `button` tag or `a` tag trigger).
-- The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event.
-- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event.
+- The `click.dl` event is fired when an `li` list item has been clicked. It's
+  also fired when a list item has been selected with the keyboard. It's also
+  fired when a `HookButton` button is clicked (a registered `button` tag or `a`
+  tag trigger).
+- The `input.dl` event is fired when a `HookInput` (a registered `input` tag
+  trigger) triggers an `input` event.
+- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown`
+  event.
 - The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event.
 - The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event.
 
-These custom events add a `detail` object to the vanilla `Event` object that provides some potentially useful data.
+These custom events add a `detail` object to the vanilla `Event` object that
+provides some potentially useful data.
 
 ## Plugins
 
-Plugins are objects that are registered to be executed when a hook is added (when a droplab trigger and dropdown are instantiated).
+Plugins are objects that are registered to be executed when a hook is added (when
+a DropLab trigger and dropdown are instantiated).
 
-If no modules API is detected, the library will fall back as it does with `window.DropLab` and will add `window.DropLab.plugins.PluginName`.
+If no modules API is detected, the library will fall back as it does with
+`window.DropLab` and will add `window.DropLab.plugins.PluginName`.
 
 ### Usage
 
-To use plugins, you can pass them in an array as the third argument of `DropLab.prototype.init` or `DropLab.prototype.addHook`.
-Some plugins require configuration values, the config object can be passed as the fourth argument.
+To use plugins, you can pass them in an array as the third argument of
+`DropLab.prototype.init` or `DropLab.prototype.addHook`. Some plugins require
+configuration values; the config object can be passed as the fourth argument.
 
 ```html
 <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
@@ -246,14 +257,13 @@ droplab.init(trigger, list, [droplabAjax], {
 
 ### Documentation
 
-- [Ajax plugin](plugins/ajax.md)
-- [Filter plugin](plugins/filter.md)
-- [InputSetter plugin](plugins/input_setter.md)
+Refer to the list of available [DropLab plugins](plugins/index.md) for
+information about their use.
 
 ### Development
 
-When plugins are initialised for a droplab trigger+dropdown, DropLab will
-call the plugins `init` function, so this must be implemented in the plugin.
+When plugins are initialised for a DropLab trigger+dropdown, DropLab calls the
+plugins' `init` function, so this must be implemented in the plugin.
 
 ```javascript
 class MyPlugin {

doc/development/fe_guide/droplab/plugins/ajax.md

@@ -4,20 +4,22 @@ group: unassigned
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# Ajax
+# Ajax plugin
 
-`Ajax` is a droplab plugin that allows for retrieving and rendering list data from a server.
+`Ajax` is a DropLab plugin that allows for retrieving and rendering list data
+from a server.
 
 ## Usage
 
-Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call.
+Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or
+`DropLab.prototype.addHook` call.
 
-`Ajax` requires 2 configuration values, the `endpoint` and `method`.
+`Ajax` requires 2 configuration values: the `endpoint` and `method`.
 
-- `endpoint` should be a URL to the request endpoint.
-- `method` should be `setData` or `addData`.
-- `setData` completely replaces the dropdown with the response data.
-- `addData` appends the response data to the current dropdown list.
+- `endpoint`: Should be a URL to the request endpoint.
+- `method`: Should be `setData` or `addData`.
+- `setData`: Completely replaces the dropdown with the response data.
+- `addData`: Appends the response data to the current dropdown list.
 
 ```html
 <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
@@ -38,7 +40,7 @@ droplab.addHook(trigger, list, [Ajax], {
 });
 ```
 
-Optionally you can set `loadingTemplate` to a HTML string. This HTML string will
-replace the dropdown list while the request is pending.
+Optionally, you can set `loadingTemplate` to a HTML string. This HTML string
+replaces the dropdown list while the request is pending.
 
 Additionally, you can set `onError` to a function to catch any XHR errors.

doc/development/fe_guide/droplab/plugins/filter.md

@@ -4,18 +4,19 @@ group: unassigned
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# Filter
+# Filter plugin
 
-`Filter` is a plugin that allows for filtering data that has been added
+`Filter` is a DropLab plugin that allows for filtering data that has been added
 to the dropdown using a simple fuzzy string search of an input value.
 
 ## Usage
 
-Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call.
+Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or
+`DropLab.prototype.addHook` call.
 
-- `Filter` requires a configuration value for `template`.
-- `template` should be the key of the objects within your data array that you want to compare
-  to the user input string, for filtering.
+- `Filter`: Requires a configuration value for `template`.
+- `template`: Should be the key of the objects within your data array that you
+  want to compare to the user input string, for filtering.
 
 ```html
 <input href="#" id="trigger" data-dropdown-trigger="#list">
@@ -45,8 +46,10 @@ droplab.addData('trigger', [{
 }]);
 ```
 
-Above, the input string will be compared against the `test` key of the passed data objects.
+In the previous code, the input string is compared against the `test` key of the
+passed data objects.
 
-Optionally you can set `filterFunction` to a function. This function will be used instead
-of `Filter`'s built in string search. `filterFunction` is passed 2 arguments, the first
-is one of the data objects, the second is the current input value.
+Optionally you can set `filterFunction` to a function. This function will be
+used instead of `Filter`'s built-in string search. `filterFunction` is passed
+two arguments: the first is one of the data objects, and the second is the
+current input value.

doc/development/fe_guide/droplab/plugins/index.md

+---
+stage: none
+group: unassigned
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
+description: A list of DropLab plugins.
+---
+
+# DropLab plugins
+
+The following plugins are available for use with [DropLab](../droplab.md):
+
+- [Ajax plugin](ajax.md)
+- [Filter plugin](filter.md)
+- [InputSetter plugin](input_setter.md)

doc/development/fe_guide/droplab/plugins/input_setter.md

@@ -4,20 +4,23 @@ group: unassigned
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
 ---
 
-# InputSetter
+# InputSetter plugin
 
-`InputSetter` is a plugin that allows for updating DOM out of the scope of droplab when a list item is clicked.
+`InputSetter` is a DropLab plugin that allows for updating DOM out of the scope
+of DropLab when a list item is clicked.
 
 ## Usage
 
-Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call.
+Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init`
+or `DropLab.prototype.addHook` call.
 
-- `InputSetter` requires a configuration value for `input` and `valueAttribute`.
-- `input` should be the DOM element that you want to manipulate.
-- `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value
-  to update the `input` element with.
+- `InputSetter`: Requires a configuration value for `input` and `valueAttribute`.
+- `input`: The DOM element that you want to manipulate.
+- `valueAttribute`: A string that's the name of an attribute on your list items
+  that's used to get the value to update the `input` element with.
 
-You can also set the `InputSetter` configuration to an array of objects, which will allow you to update multiple elements.
+You can also set the `InputSetter` configuration to an array of objects, which
+allows you to update multiple elements.
 
 ```html
 <input id="input" value="">
@@ -58,9 +61,12 @@ droplab.addData('trigger', [{
 }]);
 ```
 
-Above, if the second list item was clicked, it would update the `#input` element
-to have a `value` of `1`, it would also update the `#div` element's `data-selected-id` to `1`.
+In the previous code, if the second list item was clicked, it would update the
+`#input` element to have a `value` of `1`, it would also update the `#div`
+element's `data-selected-id` to `1`.
 
-Optionally you can set `inputAttribute` to a string that is the name of an attribute on your `input` element that you want to update.
-If you do not provide an `inputAttribute`, `InputSetter` will update the `value` of the `input` element if it is an `INPUT` element,
-or the `textContent` of the `input` element if it is not an `INPUT` element.
+Optionally, you can set `inputAttribute` to a string that's the name of an
+attribute on your `input` element that you want to update. If you don't provide
+an `inputAttribute`, `InputSetter` will update the `value` of the `input`
+element if it's an `INPUT` element, or the `textContent` of the `input` element
+if it isn't an `INPUT` element.