Public Methods

Public Methods

There are 3 "types" of methods Public Methods , which handles the tail.select elements or instance, API Methods, which handles the tail.select behavior or functions and Option Methods, which manipulates the used options of the instance.

Table of Content

1. Public Methods
   1. .open(animate)
   2. .close(animate)
   3. .toggle(animate)
   4. .remove()
   5. .reload()
   6. .config(key, value, rebuild)
   7. .enable(update)
   8. .disable(update)
   9. .on(event, callback, args)
2. API Methods
   1. .query(search, conf)
   2. .update(item)
   3. .updateLabel(label)
   4. .updateContainer(item)
   5. .updatePin(item)
   6. .updateCSV(item)
3. Option Methods
   1. .get(key, group)
   2. .set(option, rebuild)
   3. .add(key, value, group, selected, disabled, description, rebuild)
   4. .move(item, group, new_group, rebuild)
   5. .remove(key, group, rebuild)
   6. .is(state, key, group)
   7. .handle(state, key, group, _force)
   8. .enable(key, group)
   9. .disable(key, group)
   10. .select(key, group)
   11. .unselect(key, group)
   12. .toggle(key, group)
   13. .invert(state)
   14. .all(state, group)
   15. .walk(state, items, args)
   16. .finder(search, config)
   17. .find(search, config)
   18. .walker(orderi, orderg)

Public Methods

.open(animate)

animate <bool>
This method opens the dropdown field, if it isn't already opened. You can pass a bool argument, which disabled / enabled the open-animation regardless of the instance options!

.close(animate)

animate <bool>
This method closes the dropdown field, if it is still open. You can pass a bool argument, which disabled / enabled the close-animation regardless of the instance options!

.toggle(animate)

animate <bool>
This method opens or closes the dropdown field, depending on the current state. You can pass a bool argument, which disabled / enabled the close-animation regardless of the instance options!

.remove()

-
This method just removes the the complete tail.select instance from the DOM and the source select element! (The instance itself remains, so you can call .init() to rebuild the DOM elements).

.reload()

-
This method just calls .remove() and .init() for you.

.config(key, value, rebuild)

key <undefined|string|object>, value <undefined|multi>, reload <undefined|bool> This method will allow you to get and set each single options during the runtime. Use No Parameter to get all options as object, pass an single options key as first parameter to receive the respective value, pass an value as second parameter to "set" the respective option to the new value.

You can also pass an key: value object construct as first parameter to set multiple options at once. The last parameter defines the reload-ability, pass false to prevent the auto-reload function, which gets otherwise called whenever you change a option.

Notes

You can also en/disable the tail.select instance by using .config("disabled", true | false), BUT this will only en/disable the tail.select field itself and NOT the source select field! Use therefore .enable() or .disable() as described below.

.enable(update)

update <bool>
This method enables the tail.select instance as well as the source select field. By default, this function will reload the tail field too, unless you pass false as first argument.

.disable(update)

This method disables the tail.select instance as well as the source select field. By default, this function will reload the tail field too, unless you pass false as first argument.

.on(event, callback, args)

event <string>, callback <callback>, args <undefined|array> This method adds an callback function and custom / additional arguments, to the internal event listener. The current version offers the events "open", "close" and "change". The last one gets triggered if any selection or state-change (enable / disable) gets made.

You can also "hook" your function with the .addEventListener() method to the source element (which only fires the "change" event) or on the main tail.select container, which is accessible through the instance variable ".select". The main select container fires all 3 events, but uses the prefix "tail::<event_name>"! The ".detail" object contains the property "args", which holds the passed arguments, and "self" which holds the respective ProtoType Instance.

API Methods

.query(search, conf)

search <string>, conf <string>
This method builds the dropdown options list. The first parameter can be a string, which "searchs" through the options an just shows the results, the second parameter allows to configure the search method a bit.

.update(item)

-
This method calls all 4 .update*() methods below.

.updateLabel(label)

label <string>
This method changes the shown label, you can pass any string you want. Attention: Strings, which are also used as "keys" for one of the localization strings gets replaced by the respective string! (For example: If you pass placeholder it gets replaced by "Select an Option..."). Attention2: The substring ":limit" gets replaced by the multiLimit options (but on multiple select fields only, of course).

.updateContainer(item)

item <object>
This method adds or removes the respective item from the multiContainer, if used. The passed argument need to be a valid item object, which MUST contain the selected property!

.updatePin(item)

item <object>
This method "pins" or "unpins" the respective item, when multiPinSelected is enabled. The passed argument need to be a valid item object, which MUST contain the selected property!

.updateCSV(item)

item <object>
This method "rebuilds" the value for the (comma-separated) csvInput field, which is used when the csvOutput option is enabled. The passed argument need to be a valid item object, which MUST contain the selected property!

Option Methods

Each tailSelect instance has an own tailOptions instance, which is accessible through the <tail.select>.options property. This ProtoTyped and Array-Like Object contains the following methods and functions:

.get(key, group)

key <multi>, group <string>
This method tries to get the respective option, you can pass the following values as first argument, the second MUST be the respective option group (label) as STRING, or nothing to use the main group.

• The unique option key as STRING.
• The respective option number as INTEGER.
• The <option> HTMLElement from the source select field.
• The <li> HTMLElement from the tail.select dropdown field.

Already fetched item objects gets returned as they are!

.set(option, rebuild)

option <HTMLElement>, rebuild <bool>
This method adds already existing <option> elements, which does "already exist" on the source select field, to the instance. The first argument MUST be the <option> HTMLElement, the second parameter can be an optional bool value: True will rebuild the tail.select dropdown list, False will prevent this.

.add(key, value, group, selected, disabled, description, rebuild)

key <string|object>, value <string>, group <string>, selected <bool>, disabled <bool>, description <string>, rebuild <bool>
This method will create a complete new option, which gets also appended to the source select field. You MUST pass at least the unique option key, as well as the shown option value (innerText). All other arguments are optional! This function will NOT rebuild the dropdown field, unless you pass true as last argument!

You can also pass a complete object as first argument (like on the items option), to create and add multiple options at once.

.move(item, group, new_group, rebuild)

item <multi>, group <string>, new_group <string>, rebuild <bool>
This method allows you to "move" an option from a group to another one. Just pass the new group label as third argument. This function will NOT rebuild the dropdown field, unless you pass true as last argument! Read .get(key, group) for more informations about the first two arguments.

.remove(key, group, rebuild)

key <multi>, group <string>>, rebuild <bool>
This method will remove the passed option from the instance as well as from the source select field. Read .get(key, group) for more informations about the arguments.

.is(state, key, group)

state <string>, key <multi>, group <string>
This method will check if the passed option has the respective state (first argument). Use "select", "unselect", "enable" or "disable" as first parameter to check the respective value. Read .get(key, group) for more informations about the last both arguments.

.handle(state, key, group, _force)

This method will change the state (first argument) on the passed option. Use "select", "unselect", "enable" or "disable" as first parameter to "set" the respective state. The fourth argument forces / skips the "don't unselect an option on single select fields, which aren't deselectable" condition.

Read .get(key, group) for more informations about the seconds and third argument.

.enable(key, group)

key <multi>, group <string>
This method is just a alias / shortcode for .handle("enable", key, group) and enables the passed option, if possible! Read .get(key, group) for more informations about the arguments.

.disable(key, group)

key <multi>, group <string>
This method is just a alias / shortcode for .handle("disable", key, group) and disables the passed option, if possible! Read .get(key, group) for more informations about the arguments.

.select(key, group)

key <multi>, group <string>
This method is just a alias / shortcode for .handle("select", key, group) and selects the passed option, if possible! Read .get(key, group) for more informations about the arguments.

.unselect(key, group)

key <multi>, group <string>
This method is just a alias / shortcode for .handle("unselect", key, group) and unselects the passed option, if possible! Read .get(key, group) for more informations about the arguments.

.toggle(key, group)

key <multi>, group <string>
This method is just a alias / shortcode for .handle(state, key, group) and selects or unselects the passed option if possible! Read .get(key, group) for more informations about the arguments.

.invert(state)

state <string>
This method will "invert" all options with the respective state. Use "select" / "unselect", which selects all unselected and unselect all selected options or "enable" / "disable", which enables all disabled and disables all enabled options.

.all(state, group)

state <string>, group <string>
This method applies the passed state to all options. You can "restrict" the options by passing an additional group, which will apply the state only to the options of the respective group! Use "select", "unselect", "enable" or "disable" as first argument.

.walk(state, items, args)

state <string>, items <array|object>, args <array>
This method allows you to "apply" a state function to multiple items, which gets passed as array or as Array-Like object (Like a HTMLCollection or NodeList).

.finder(search, config)

state <string>, config <string>
This option will "search" through the option and return each one, which contains the value, passed as first argument. You can configure the search behavior by passing a second argument with any or value. This function works like a generator (or a real generator by using the ECMAScript 2015 version of this script). Which means you need to use this method within a own loop!

.find(search, config)

state <string>, config <string>
This method is just a shortcode for .finder() with one difference: It will return the search result as object at once. So it doesn't work "like a generator" (or a real generator when using the ECMAScript 2015 version of this script).

.walker(orderi, orderg)

orderi <string|function>, orderg <string|function>
This method will just loop each single option of the instance. This function works like a generator (or a real generator by using the ECMAScript 2015 version of this script). Which means you need to use this method within a own loop!

Both available arguments can either be "ASC" / "DESC" or an own callback functions, the first one "sorts" the items of a group, the second one the groups itself. Pass NOTHING to keep the order.