Commit d879f19d authored by Craig Norris's avatar Craig Norris

Minor style updates

Some line length and style changes.
parent 6f4cbc8f
......@@ -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>
......@@ -250,8 +261,8 @@ A list of DropLab plugins is [available](./plugins/index.md).
### 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 {
......
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