@gitlab-org/droplab

DropLab

A generic dropdown for all of your custom dropdown needs.

Install

• Add /dist/droplab.js to your application assets.
• Link to it in your code. See examples.

If no modules API is detected, the library will fall back and add window.DropLab.

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.

The value of the data-dropdown-trigger should be a CSS selector that DropLab can use to find the triggers 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.

<a href="#" data-dropdown-trigger="#list">Toggle</a>

<ul id="list" data-dropdown>
  <!-- ... -->
<ul>

<script>
  new DropLab().init();
</script>

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.

Static data

You can add static list items.

<a href="#" data-dropdown-trigger="#list">Toggle</a>

<ul id="list" data-dropdown>
  <li>Static value 1</li>
  <li>Static value 2</li>
<ul>

<script>
  new DropLab().init();
</script>

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.

<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>

<ul id="list" data-dropdown>
  <!-- ... -->
<ul>

<script>
  const trigger = document.getElementById('trigger');
  const list = document.getElementById('list');

  new DropLab().init(trigger, list);
</script>

You can also add hooks to an existing DropLab instance using DropLab.prototype.addHook.

<a href="#" data-dropdown-trigger="#auto-dropdown">Toggle</a>
<ul id="auto-dropdown" data-dropdown><!-- ... --><ul>

<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
<ul id="list" data-dropdown><!-- ... --><ul>

<script>
  const droplab = new DropLab();

  droplab.init();

  const trigger = document.getElementById('trigger');
  const list = document.getElementById('list');

  droplab.addHook(trigger, list);
</script>

Dynamic data

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.

Passing an array of objects to DropLab.prototype.addData will render that data for all data-dynamic dropdown lists tracked by that DropLab instance.

<a href="#" data-dropdown-trigger="#list">Toggle</a>

<ul id="list" data-dropdown data-dynamic>
  <li><a href="#" data-id="{{id}}">{{text}}</a></li>
</ul>

<script>
  const droplab = new DropLab();

  droplab.init().addData([{
    id: 0,
    text: 'Jacob',
  }, {
    id: 1,
    text: 'Jeff',
  }]);
</script>

Alternatively, you can specify a specific dropdown to add this data to but passing the data as the second argument and and the id of the trigger element as the first argument.

<a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a>

<ul id="list" data-dropdown data-dynamic>
  <li><a href="#" data-id="{{id}}">{{text}}</a></li>
</ul>

<script>
  const droplab = new DropLab();

  droplab.init().addData('trigger', [{
    id: 0,
    text: 'Jacob',
  }, {
    id: 1,
    text: 'Jeff',
  }]);
</script>

This allows you to mix static and dynamic content with ease, even with 1 trigger.

Note the use of scoping regarding the data-dropdown attribute to capture both dropdown lists, one of which is dynamic.

<input id="trigger" data-dropdown-trigger="#list">
<div id="list" data-dropdown>
  <ul>
    <li><a href="#">Static item 1</a></li>
    <li><a href="#">Static item 2</a></li>
  </ul>
  <ul data-dynamic>
    <li><a href="#" data-id="{{id}}">{{text}}</a></li>
  </ul>
</div>

<script>
  const droplab = new DropLab();

  droplab.init().addData('trigger', [{
    id: 0,
    text: 'Jacob',
  }, {
    id: 1,
    text: 'Jeff',
  }]);
</script>

Internal selectors

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-active css class is added to items that have been selected using arrow key navigation.

Examples

Some example implementations are provided in /examples.

Please note: It is recommended you use npm run serve to view the examples as it will allow you to perform a mock JSON request for ajax-dependent examples.

Plugins

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.

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.

<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a>
<ul id="list" data-dropdown><!-- ... --><ul>

<script>
  const droplab = new DropLab();

  const trigger = document.getElementById('trigger');
  const list = document.getElementById('list');

  droplab.init(trigger, list, [droplabAjax], {
    droplabAjax: {
      endpoint: '/some-endpoint',
      method: 'setData',
    },
  });
</script>

Some plugins are available in /dist/plugins.

Plugin documentation

• ajax.datasource
• filter

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.

class MyPlugin {
  static init() {
    this.someProp = 'someProp';
    this.someMethod();
  }

  static someMethod() {
    this.otherProp = 'otherProp';
  }
}

export default MyPlugin;

Development

Use npm run webpack to create the DropLab and plugin bundles.

Use npm run karma to run the unit tests. Currently, this will run the tests on Chrome and PhantomJS. It will output an Istanbul HTML coverage report to /coverage.

Use npm run karma-ci to only run PhantomJS in CI-mode (clean exit 0 or exit 1).

Scripts can be compiled into /dist with npm run compile.