Commit f298a22b authored by Craig Norris's avatar Craig Norris

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
parents dcea6675 16380917
...@@ -10,19 +10,20 @@ A generic dropdown for all of your custom dropdown needs. ...@@ -10,19 +10,20 @@ A generic dropdown for all of your custom dropdown needs.
## Usage ## Usage
DropLab can be used by simply adding a `data-dropdown-trigger` HTML attribute. DropLab can be used by adding a `data-dropdown-trigger` HTML attribute. This
This attribute allows us to find the "trigger" _(toggle)_ for the dropdown, attribute allows us to find the "trigger" _(toggle)_ for the dropdown, whether
whether that is a button, link or input. it's a button, link or input.
The value of the `data-dropdown-trigger` should be a CSS selector that The value of the `data-dropdown-trigger` should be a CSS selector that DropLab
DropLab can use to find the trigger's dropdown list. can use to find the trigger's dropdown list.
You should also add the `data-dropdown` attribute to declare the dropdown list. You should also add the `data-dropdown` attribute to declare the dropdown list.
The value is irrelevant. The value is irrelevant.
The DropLab class has no side effects, so you must always call `.init` when The DropLab class has no side effects, so you must always call `.init` when the
the DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`. 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. If you don't provide any arguments, it will globally query and instantiate all
DropLab-compatible dropdowns.
```html ```html
<a href="#" data-dropdown-trigger="#list">Toggle</a> <a href="#" data-dropdown-trigger="#list">Toggle</a>
...@@ -37,8 +38,8 @@ const droplab = new DropLab(); ...@@ -37,8 +38,8 @@ const droplab = new DropLab();
droplab.init(); droplab.init();
``` ```
As you can see, we have a "Toggle" link, that is declared as a trigger. As noted, we have a "Toggle" link that's declared as a trigger. It provides a
It provides a selector to find the dropdown list it should control. selector to find the dropdown list it should control.
### Static data ### Static data
...@@ -60,8 +61,8 @@ droplab.init(); ...@@ -60,8 +61,8 @@ droplab.init();
### Explicit instantiation ### Explicit instantiation
You can pass the trigger and list elements as constructor arguments to return You can pass the trigger and list elements as constructor arguments to return a
a non-global instance of DropLab using the `DropLab.prototype.init` method. non-global instance of DropLab using the `DropLab.prototype.init` method.
```html ```html
<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
...@@ -102,12 +103,13 @@ droplab.addHook(trigger, list); ...@@ -102,12 +103,13 @@ droplab.addHook(trigger, list);
### Dynamic data ### 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. You can template a list item using the keys of the data object provided. Use the
Use the handlebars syntax `{{ value }}` to HTML escape the value. handlebars syntax `{{ value }}` to HTML escape the value. Use the `<%= value %>`
Use the `<%= value %>` syntax to simply interpolate the value. syntax to interpolate the value. Use the `<%= value %>` syntax to evaluate the
Use the `<%= value %>` syntax to evaluate the value. value.
Passing an array of objects to `DropLab.prototype.addData` will render that data Passing an array of objects to `DropLab.prototype.addData` will render that data
for all `data-dynamic` dropdown lists tracked by that DropLab instance. for all `data-dynamic` dropdown lists tracked by that DropLab instance.
...@@ -132,8 +134,9 @@ droplab.init().addData([{ ...@@ -132,8 +134,9 @@ droplab.init().addData([{
}]); }]);
``` ```
Alternatively, you can specify a specific dropdown to add this data to but passing Alternatively, you can specify a specific dropdown to add this data to by
the data as the second argument and the `id` of the trigger element as the first argument. passing the data as the second argument and the `id` of the trigger element as
the first argument.
```html ```html
<a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a> <a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a>
...@@ -155,7 +158,7 @@ droplab.init().addData('trigger', [{ ...@@ -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 Note the use of scoping regarding the `data-dropdown` attribute to capture both
dropdown lists, one of which is dynamic. dropdown lists, one of which is dynamic.
...@@ -191,12 +194,13 @@ DropLab adds some CSS classes to help lower the barrier to integration. ...@@ -191,12 +194,13 @@ DropLab adds some CSS classes to help lower the barrier to integration.
For example: For example:
- The `droplab-item-selected` CSS class is added to items that have been selected - The `droplab-item-selected` CSS class is added to items that have been
either by a mouse click or by enter key selection. 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 - The `droplab-item-active` CSS class is added to items that have been selected
using arrow key navigation. 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, - You can add the `droplab-item-ignore` CSS class to any item that you don't
an `<li class="divider"></li>` list divider element that should not be interactive. want to be selectable. For example, an `<li class="divider"></li>` list
divider element that shouldn't be interactive.
## Internal events ## Internal events
...@@ -204,26 +208,33 @@ DropLab uses some custom events to help lower the barrier to integration. ...@@ -204,26 +208,33 @@ DropLab uses some custom events to help lower the barrier to integration.
For example: For example:
- The `click.dl` event is fired when an `li` list item has been clicked. It is also - The `click.dl` event is fired when an `li` list item has been clicked. It's
fired when a list item has been selected with the keyboard. It is also fired when a also fired when a list item has been selected with the keyboard. It's also
`HookButton` button is clicked (a registered `button` tag or `a` tag trigger). fired when a `HookButton` button is clicked (a registered `button` tag or `a`
- The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. tag trigger).
- The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. - 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 `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. - 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
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 ### Usage
To use plugins, you can pass them in an array as the third argument of `DropLab.prototype.init` or `DropLab.prototype.addHook`. To use plugins, you can pass them in an array as the third argument of
Some plugins require configuration values, the config object can be passed as the fourth argument. `DropLab.prototype.init` or `DropLab.prototype.addHook`. Some plugins require
configuration values; the config object can be passed as the fourth argument.
```html ```html
<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
...@@ -246,14 +257,13 @@ droplab.init(trigger, list, [droplabAjax], { ...@@ -246,14 +257,13 @@ droplab.init(trigger, list, [droplabAjax], {
### Documentation ### Documentation
- [Ajax plugin](plugins/ajax.md) Refer to the list of available [DropLab plugins](plugins/index.md) for
- [Filter plugin](plugins/filter.md) information about their use.
- [InputSetter plugin](plugins/input_setter.md)
### Development ### Development
When plugins are initialised for a droplab trigger+dropdown, DropLab will When plugins are initialised for a DropLab trigger+dropdown, DropLab calls the
call the plugins `init` function, so this must be implemented in the plugin. plugins' `init` function, so this must be implemented in the plugin.
```javascript ```javascript
class MyPlugin { class MyPlugin {
......
...@@ -4,20 +4,22 @@ group: unassigned ...@@ -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 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 ## 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. - `endpoint`: Should be a URL to the request endpoint.
- `method` should be `setData` or `addData`. - `method`: Should be `setData` or `addData`.
- `setData` completely replaces the dropdown with the response data. - `setData`: Completely replaces the dropdown with the response data.
- `addData` appends the response data to the current dropdown list. - `addData`: Appends the response data to the current dropdown list.
```html ```html
<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> <a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
...@@ -38,7 +40,7 @@ droplab.addHook(trigger, list, [Ajax], { ...@@ -38,7 +40,7 @@ droplab.addHook(trigger, list, [Ajax], {
}); });
``` ```
Optionally you can set `loadingTemplate` to a HTML string. This HTML string will Optionally, you can set `loadingTemplate` to a HTML string. This HTML string
replace the dropdown list while the request is pending. replaces the dropdown list while the request is pending.
Additionally, you can set `onError` to a function to catch any XHR errors. Additionally, you can set `onError` to a function to catch any XHR errors.
...@@ -4,18 +4,19 @@ group: unassigned ...@@ -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 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. to the dropdown using a simple fuzzy string search of an input value.
## Usage ## 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`. - `Filter`: Requires a configuration value for `template`.
- `template` should be the key of the objects within your data array that you want to compare - `template`: Should be the key of the objects within your data array that you
to the user input string, for filtering. want to compare to the user input string, for filtering.
```html ```html
<input href="#" id="trigger" data-dropdown-trigger="#list"> <input href="#" id="trigger" data-dropdown-trigger="#list">
...@@ -45,8 +46,10 @@ droplab.addData('trigger', [{ ...@@ -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 Optionally you can set `filterFunction` to a function. This function will be
of `Filter`'s built in string search. `filterFunction` is passed 2 arguments, the first used instead of `Filter`'s built-in string search. `filterFunction` is passed
is one of the data objects, the second is the current input value. two arguments: the first is one of the data objects, and the second is the
current input value.
---
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)
...@@ -4,20 +4,23 @@ group: unassigned ...@@ -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 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 ## 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`. - `InputSetter`: Requires a configuration value for `input` and `valueAttribute`.
- `input` should be the DOM element that you want to manipulate. - `input`: 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 - `valueAttribute`: A string that's the name of an attribute on your list items
to update the `input` element with. 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 ```html
<input id="input" value=""> <input id="input" value="">
...@@ -58,9 +61,12 @@ droplab.addData('trigger', [{ ...@@ -58,9 +61,12 @@ droplab.addData('trigger', [{
}]); }]);
``` ```
Above, if the second list item was clicked, it would update the `#input` element In the previous code, if the second list item was clicked, it would update the
to have a `value` of `1`, it would also update the `#div` element's `data-selected-id` to `1`. `#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. Optionally, you can set `inputAttribute` to a string that's the name of an
If you do not provide an `inputAttribute`, `InputSetter` will update the `value` of the `input` element if it is an `INPUT` element, attribute on your `input` element that you want to update. If you don't provide
or the `textContent` of the `input` element if it is not an `INPUT` element. 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.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment