diff options
Diffstat (limited to 'doc/development/fe_guide/droplab/droplab.md')
| -rw-r--r-- | doc/development/fe_guide/droplab/droplab.md | 94 |
1 files changed, 55 insertions, 39 deletions
diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md index 83bc4216403..fe0f07b3019 100644 --- a/doc/development/fe_guide/droplab/droplab.md +++ b/doc/development/fe_guide/droplab/droplab.md @@ -1,22 +1,29 @@ +--- +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 +--- + # DropLab 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> @@ -31,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 @@ -54,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> @@ -96,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. @@ -126,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> @@ -149,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. @@ -185,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 @@ -198,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> @@ -240,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 { |