Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
G
gitlab-ce
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
1
Merge Requests
1
Analytics
Analytics
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Commits
Issue Boards
Open sidebar
nexedi
gitlab-ce
Commits
d879f19d
Commit
d879f19d
authored
Nov 16, 2020
by
Craig Norris
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
Minor style updates
Some line length and style changes.
parent
6f4cbc8f
Changes
1
Show whitespace changes
Inline
Side-by-side
Showing
1 changed file
with
47 additions
and
36 deletions
+47
-36
doc/development/fe_guide/droplab/droplab.md
doc/development/fe_guide/droplab/droplab.md
+47
-36
No files found.
doc/development/fe_guide/droplab/droplab.md
View file @
d879f19d
...
...
@@ -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 i
s 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
{
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment