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.
...
@@ -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 i
s 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
{
...
...
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