Dropkick
Getting started
After you've cloned the repo you will need to add the library to your page. In the build/js folder use
one of the two DropKick files given. One has a version number in the file name and the other is a version
number-less version. You will also need to grab the css from build/css and load it on the page.
Once those files are imported into the page you can call DropKick on any HTMLSelectElement:
new Dropkick( HTMLSelectElement, Options ); or new Dropkick( "ID", Options );. This returns the dropkick
object to you. It may be useful for you to store this in a var to reference later.
If you're using jQuery you can do this instead:
$('#select').dropkick( Options );
Constructor
Parameters:
-
selElemHTMLSelect Element being passed.
-
optionsOptsSee list of properties you can pass in here
Returns:
DropKick Object for that select. You can call your methods on this if stored in a var
Example:
// Pure JS
var select = new Dropkick("#select");
// jQuery
$("#select").dropkick();
Methods
add
-
elem -
before
Adds an element to the select. This option will not only add it to the original select, but create a Dropkick option and add it to the Dropkick select.
Parameters:
-
elemStringHTMLOptionElement
-
beforeNode/IntegerHTMLOptionElement/Index of Element
Example:
var select = new Dropkick("#select");
select.add("New option", 5);
Builds the Dropkick element from a select element
Parameters:
-
selNodeThe HTMLSelectElement
Returns:
An object containing the new DK element and it's options
close
()
Closes the DK dropdown
Example:
var select = new Dropkick("#select");
select.close(); //closes dk dropdown
delegate
()
disable
-
elem -
disabled
Disables or enables an option; if only a boolean is passed (or nothing), then the entire Dropkick will be disabled or enabled.
Parameters:
-
elemIntegerThe element or index to disable
-
disabledBooleanValue of disabled
Example:
var select = new Dropkick("#select");
// To disable the entire select
select.disable();
// To disable just an option with an index
select.disable(4, true);
// To re-enable the entire select
select.disable(false);
// To re-enable just an option with an index
select.disable(4, false);
dispose
()
Removes the DK Object from the cache and the element from the DOM
Example:
var select = new Dropkick("#select");
select.dispose();
focus
()
Brings focus to the proper DK element
Example:
var select = new Dropkick("#select");
$("#some_elm").on("click", function() {
select.focus();
});
handleEvent
()
highlight
()
Initializes the DK Object
Parameters:
-
selNode[description]
-
optsObjectOptions to override defaults
Returns:
The DK Object
item
-
index
Selects an option in the list at the desired index (negative numbers select from the end).
Parameters:
-
indexIntegerIndex of element (positive or negative)
Returns:
The DK option from the list, or null if not found
Example:
var select = new Dropkick("#select");
select.item(4); //returns DOM node of index
keyHandler
()
onDocClick
-
event
Focus DK Element when corresponding label is clicked; close all other DK's
Parameters:
-
eventObjectEvent from document click
open
()
Opens the DK dropdown
Example:
var select = new Dropkick("#select");
select.open(); //Opens the dk dropdown
refresh
()
Rebuilds the DK Object (use if HTMLSelectElement has changed)
Example:
var select = new Dropkick("#select");
//... [change original select] ...
select.refresh();
remove
-
index
Removes the option (from both the select and Dropkick) at the given index.
Parameters:
-
indexIntegerIndex of element (positive or negative)
Example:
var select = new Dropkick("#select");
select.remove(4);
reset
-
clear
Resets the Dropkick and select to it's original selected options; if clear is true,
It will select the first option by default (or no options for multi-selects).
Parameters:
-
clearBooleanDefaults to first option if True
Example:
var select = new Dropkick("#select");
// Reset to originally selected option
select.reset();
// Reset to first option in select
select.reset(true);
scrollTo
()
Finds all options who's text matches a pattern (strict, partial, or fuzzy)
"strict" - The search string matches exactly from the beginning of the
option's text value (case insensitive).
"partial" - The search string matches part of the option's text value
(case insensitive).
"fuzzy" - The search string matches the characters in the given order (not
exclusively). The strongest match is selected first. (case insensitive).
Parameters:
-
stringStringThe string to search for
-
modeIntegerHow to search; "strict", "partial", or "fuzzy"
Returns:
An Array of matched elements
searchOptions
()
select
-
elem -
disabled
Selects an option from the list
Parameters:
Returns:
The selected element
Example:
var elm = new Dropkick("#select");
// Select by index
elm.select(4); //selects & returns 5th item in the list
// Select by value
elm.select("AL"); // selects & returns option with the value "AL"
selectOne
-
elem -
disabled
Selects a single option from the list and scrolls to it (if the select is open or on multi-selects). Useful for selecting an option after a search by the user. Important to note: this doesn't close the dropdown when selecting. It keeps the dropdown open and scrolls to proper position.
Parameters:
-
elemIntegerThe element or index to select
-
disabledBooleanSelects disabled options
Returns:
The selected element
Example:
var select = new Dropkick("#select");
select.selectOne(4);
Properties
disabled
Boolean
Whether the form is currently disabled or not
Example:
var select = new Dropkick("#select");
select.disabled;
form
Node
The form associated with the select
Example:
var select = new Dropkick("#select");
select.form;
length
Integer
The number of options in the select
Example:
var select = new Dropkick("#select");
select.length;
multiple
Boolean
If this select is a multi-select
Example:
var select = new Dropkick("#select");
select.multiple;
options
Array
An array of Dropkick options
Example:
var select = new Dropkick("#select");
select.options;
selectedIndex
Integer
An index of the first selected option
Example:
var select = new Dropkick("#select");
select.selectedIndex;
selectedOptions
Array
An array of selected Dropkick options
Example:
var select = new Dropkick("#select");
select.selectedOptions;
value
String
The current value of the select
Example:
var select = new Dropkick("#select");
select.value;
Attributes
change
Function
Called whenever the value of the Dropkick select changes (by user action or through the API).
The value of this is the Dropkick object itself.
close
Function
Called whenever the Dropkick select is closed. The value of this is the Dropkick object itself.
initialize
Function
Called once after the DK element is inserted into the DOM.
The value of this is the Dropkick object itself.
open
Function
Called whenever the Dropkick select is opened. The value of this is the Dropkick object itself.
search
String
"strict" - The search string matches exactly from the beginning of the option's text value (case insensitive).
"partial" - The search string matches part of the option's text value (case insensitive).
"fuzzy" - The search string matches the characters in the given order (not exclusively).
The strongest match is selected first. (case insensitive).
Default: "strict"