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. ...@@ -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>
...@@ -250,8 +261,8 @@ A list of DropLab plugins is [available](./plugins/index.md). ...@@ -250,8 +261,8 @@ A list of DropLab plugins is [available](./plugins/index.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 {
......
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