diff --git a/docs/api.md b/docs/api.md index a8b1ec9eb..6dc6d3d63 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,12 +1,12 @@ ## Selectize API Selectize controls can be controlled programmatically via the methods described in this section. -When initializing the control, the "selectize" property is +When initializing the control, the `selectize` property is added on the original <select> / <input> element—this property points to the underlying Selectize instance. ```js -// initialize the selectize control +// initialize the Selectize control var $select = $('select').selectize(options); // fetch the instance @@ -70,22 +70,25 @@ var selectize = $select[0].selectize; getAdjacentOption(value, direction) - Retrieves the jQuery element for the previous or next option, relative to the currently highlighted option. The "direction" argument should be 1 for "next" or -1 for "previous". + Retrieves the jQuery element for the previous or next option, relative to the currently highlighted option. The direction argument should be 1 for "next" or -1 for "previous". refreshOptions(triggerDropdown) Refreshes the list of available options shown in the autocomplete dropdown menu. + + Items + Method Description clear(silent) - Resets / clears all selected items from the control. If "silent" is truthy, no change event will be fired on the original input. + Resets / clears all selected items from the control. If silent is truthy, no change event will be fired on the original input. getItem(value) @@ -93,39 +96,42 @@ var selectize = $select[0].selectize; addItem(value, silent) - "Selects" an item. Adds it to the list at the current caret position. If "silent" is truthy, no change event will be fired on the original input. + "Selects" an item. Adds it to the list at the current caret position. If silent is truthy, no change event will be fired on the original input. removeItem(value, silent) - Removes the selected item matching the provided value. If "silent" is truthy, no change event will be fired on the original input. + Removes the selected item matching the provided value. If silent is truthy, no change event will be fired on the original input. createItem(value, callback) - Invokes the "create" method provided in the selectize options that should provide the data for the new item, given the user input. Once this completes, it will be added to the item list. + Invokes the create method provided in the Selectize settings that should provide the data for the new item, given the user input. Once this completes, it will be added to the item list. refreshItems() Re-renders the selected item lists. + + Optgroups + Method Description addOptionGroup(id, data) - Registers a new optgroup for options to be bucketed into. The "id" argument refers to a value of the property in option identified by the "optgroupField" setting. + Registers a new optgroup for options to be bucketed into. The id argument refers to a value of the property in option identified by the optgroupField setting. + + + removeOptionGroup(id) + Removes a single option group. + + + clearOptionGroups() + Removes all existing option groups. - - removeOptionGroup(id) - Removes a single option group. - - - clearOptionGroups() - Removes all existing option groups. - Events @@ -149,9 +155,12 @@ var selectize = $select[0].selectize; trigger(event, ...) Triggers event listeners. + + Dropdown + Method Description @@ -168,9 +177,12 @@ var selectize = $select[0].selectize; positionDropdown() Calculates and applies the appropriate position of the dropdown. + + Other + Method Description @@ -181,7 +193,7 @@ var selectize = $select[0].selectize; load(fn) - Loads options by invoking the the provided function. The function should accept one argument (callback) and invoke the callback with the results once they are available. + Loads options by invoking the provided function. The function should accept one argument (callback) and invoke the callback with the results once they are available. focus() @@ -209,7 +221,7 @@ var selectize = $select[0].selectize; getValue() - Returns the value of the control. If multiple items can be selected (e.g. <select multiple>, this returns an array. If only one item can be selected, this returns a string. + Returns the value of the control. If multiple items can be selected with a "select" input tag (e.g. <select multiple>), this returns an array. Otherwise, returns a string (separated by delimiter if "multiple"). setValue(value, silent) @@ -217,7 +229,7 @@ var selectize = $select[0].selectize; setCaret(index) - Moves the caret to the specified position ("index" being the index in the list of selected items). + Moves the caret to the specified position (index being the index in the list of selected items). isFull() @@ -225,7 +237,12 @@ var selectize = $select[0].selectize; clearCache(template) - Clears the render cache. Takes an optional template argument (e.g. "option", "item") to clear only that cache. + Clears the render cache. Takes an optional template argument (e.g. option , item) to clear only that cache. + + + updatePlaceholder() + When the `settings.placeholder` value is changed, the new placeholder will be displayed. + @@ -251,7 +268,7 @@ var selectize = $select[0].selectize; tokens - An array containing parsed search tokens. A token is an object containing two properties: "string" and "regex". + An array containing parsed search tokens. A token is an object containing two properties: string and regex . array @@ -261,7 +278,7 @@ var selectize = $select[0].selectize; items - A list of matched results. Each result is an object containing two properties: "score" and "id". + A list of matched results. Each result is an object containing two properties: score and id . array diff --git a/docs/events.md b/docs/events.md index 9b03133ab..bf65d69be 100644 --- a/docs/events.md +++ b/docs/events.md @@ -104,7 +104,7 @@ selectize.off('event_name', handler); "load" data - Invoked when new options have been loaded and added to the control (via the "load" option or "load" API method). + Invoked when new options have been loaded and added to the control (via the load option or load API method). "destroy" diff --git a/docs/plugins.md b/docs/plugins.md index 092f775de..103398187 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -23,7 +23,7 @@ complete control. ```js Selectize.define('plugin_name', function(options) { // options: plugin-specific options - // this: selectize instance + // this: Selectize instance }); ``` @@ -63,7 +63,7 @@ like so: Selectize.define('plugin_name', function(options) { var self = this; - // override the setup method to add an extra "click" handler + // override the setup method to add an extra `click` handler this.setup = (function() { var original = self.setup; return function() { diff --git a/docs/usage.md b/docs/usage.md index 5d6e4955c..fb66cc78b 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -10,14 +10,24 @@ $(function() { ``` -### Options +### Glossary + +- Config / configuration: the initial settings of Selectize, given at initialization. +- Settings: the current settings of Selectize, might be updated. Accessible with the `setting` property of the Selectize object. +- Options: the list of objects to display. + Each object must have a property with an unique **value** to identify the option; the property name is defined by the `valueField` setting. + Option objects must also have a property with the **label** to display (as tag, in the drop down, etc.); the property name is defined by the `labelField` setting. + The options can have other properties, ignored, unless referenced by other settings, like `sortField` or `searchField`. +- Items: the list of selected options. Or more exactly, the list of the values of the selected options. + +### Configuration - + @@ -36,35 +46,29 @@ $(function() { - + - - - - - - - + Allows the user to create new items that aren't in the initial list of options. This setting can be any of the following: true, false (disabled), or a function that accepts two arguments: input and callback. The callback should be invoked with the final data for the option. + - + Specifies a RegExp or a string containing a regular expression that the current search filter must match to be allowed to be created. May also be a predicate function that takes the filter text and returns whether it is allowed. + @@ -93,7 +97,7 @@ $(function() { - + @@ -103,15 +107,15 @@ $(function() { - - - - - - + + + + + + - + @@ -123,7 +127,7 @@ $(function() { - + @@ -133,21 +137,27 @@ $(function() { + + + + + + - + - + - + @@ -157,27 +167,37 @@ $(function() { + + + + + + + + + - + + - + + + + + + + - - - - - - @@ -186,7 +206,7 @@ $(function() { - + @@ -217,15 +237,11 @@ $(function() { @@ -238,19 +254,19 @@ $(function() { - + - + - + @@ -258,20 +274,20 @@ $(function() { - + - + - + @@ -281,18 +297,18 @@ $(function() { - - - - - - - - - - - - + + + + + + + + + + + + @@ -355,7 +371,7 @@ $(function() { - + @@ -365,10 +381,10 @@ $(function() {
General
OptionSetting Description Type Default
delimiterThe string to separate items by. This option is only used when Selectize is instantiated from a <input type="text"> element.The string to separate items by. When typing an item in a multi-selection control allowing creation, then the delimiter, the item is added. If you paste delimiter-separated items in such control, the items are added at once. The delimiter is also used in the getValue API call on a text <input> tag to separate the multiple values. string ','
diacriticsEnable or disable international character support.booleantrue
create - Allows the user to create a new items that aren't in the list of options. This option can be any of the following: "true", "false" (disabled), or a function that accepts two arguments: "input" and "callback". The callback should be invoked with the final data for the option.mixedboolean|function false
createOnBlur - If true, when user exits the field (clicks outside of input or presses ESC) new option is created and selected (if `create`-option is enabled). + If true, when user exits the field (clicks outside of input), a new option is created and selected (if create setting is enabled). boolean false
createFilter - Specifies a RegExp or String containing a regular expression that the current search filter must match to be allowed to be created. May also be a predicate function that takes the filter text and returns whether it is allowed.mixedRegExp|string|function null
maxItemsThe max number of items the user can select.The max number of items the user can select. 1 makes the control mono-selection, null allows an unlimited number of items. int 1
boolean false
closeAfterSelectIf true, the dropdown will be closed after a selection is made.booleanfalse
closeAfterSelectIf true, the dropdown will be closed after a selection is made.booleanfalse
allowEmptyOptionIf true, Selectize will treat any options with a "" value like normal. This defaults to false to accomodate the common <select> practice of having the first empty option act as a placeholder.If true, Selectize will treat any options with a "" value like normal. This defaults to false to accomodate the common <select> practice of having the first empty option to act as a placeholder. boolean false
loadThrottleThe number of milliseconds to wait before requesting options from the server or null. If null, throttling is disabled.The number of milliseconds to wait before requesting options from the server or null. If null, throttling is disabled. Useful when loading options dynamically while the user types a search / filter expression. int 300
string 'loading'
placeholderThe placeholder of the control (displayed when nothing is selected / typed). Defaults to input element's placeholder, unless this one is specified.stringundefined
preloadIf true, the "load" function will be called upon control initialization (with an empty search). Alternatively it can be set to "focus" to call the "load" function when control receives focus.If true, the load function will be called upon control initialization (with an empty search). Alternatively it can be set to 'focus' to call the load function when control receives focus. boolean/string false
dropdownParentThe element the dropdown menu is appended to. This should be "body" or null. If null, the dropdown will be appended as a child of the selectize control.The element the dropdown menu is appended to. This should be 'body' or null. If null, the dropdown will be appended as a child of the Selectize control. string null
addPrecedenceSets if the "Add..." option should be the default selection in the dropdown.If true, the "Add..." option is the default selection in the dropdown. boolean false
boolean false
diacriticsEnable or disable international character support.booleantrue
Data / Searching
OptionSetting Description Type Default
optionsOptions available to select; array of objects. If your element i as <select> with <option>s specified this property gets populated automatically. Setting this property is convenient if you have your data as an array and want to automatically generate the <option>s.See abovearray[]
optgroupsOption groups that options will be bucketed into. If your element is a <select> with <optgroup>s this property gets populated automatically. Make sure each object in the array has a property named whatever optgroupValueField is set to. array []
optgroupsOption groups that options will be bucketed into. If your element is a <select> with <optgroup>s this property gets populated automatically. Make sure each object in the array has a property named whatever "optgroupValueField" is set to.array[]
dataAttr The <option> attribute from which to read JSON data about the option.
valueFieldThe name of the property to use as the "value" when an item is selected.The name of the property to use as the value when an item is selected. string 'value'
sortField - A single field or an array of fields to sort by. Each item in the array should be an object containing at - least a "field" property. Optionally, "direction" can be set to "asc" or "desc". The - order of the array defines the sort precedence.

+

A single field or an array of fields to sort by. Each item in the array should be an object containing at least a field property. Optionally, direction can be set to 'asc' or 'desc'. The order of the array defines the sort precedence.

- Unless present, a special "$score" field will be automatically added to the beginning - of the sort list. This will make results sorted primarily by match quality (descending).

- +

Unless present, a special `$score` field will be automatically added to the beginning of the sort list. This will make results sorted primarily by match quality (descending).

- You can override the "$score" function. For more information, see the sifter documentation. +

You can override the `$score` function. For more information, see the sifter documentation.

 string|array '$order'
searchConjunctionWhen searching for multiple terms (separated by a space), this is the operator used. Can be "and" or "or".When searching for multiple terms (separated by space), this is the operator used. Can be 'and' or 'or' . string 'and'
lockOptgroupOrderIf truthy, selectize will make all optgroups be in the same order as they were added (by the "$order" property). Otherwise, it will order based on the score of the results in each.If truthy, Selectize will make all optgroups be in the same order as they were added (by the `$order` property). Otherwise, it will order based on the score of the results in each. boolean false
copyClassesToDropdownCopy the original input classes to the Dropdown element.Copy the original input classes to the dropdown element. boolean true
Callbacks
OptionSetting Description Type Default
load(query, callback)Invoked when new options should be loaded from the server.Invoked when new options should be loaded from the server. Called with the current query string and a callback function to call with the results when they are loaded (or nothing when an error arises). function null
score(search)Overrides the scoring function used to sort available options. The provided function should return a function that returns a number greater than or equal to zero to represent the "score" of an item (the function's first argument). If 0, the option is declared not a match. The "search" argument is a Search object. For an example, see the "GitHub" example.Overrides the scoring function used to sort available options. The provided function should return a function that returns a number greater than or equal to zero to represent the score of an item (the function's first argument). If 0, the option is declared not a match. The search argument is a Search object. For an example, see the "GitHub" example. function null
function null
onFocus()Invoked when the control gains focus.functionnull
onBlur()Invoked when the control loses focus.functionnull
onFocus()Invoked when the control gains focus.functionnull
onBlur()Invoked when the control loses focus.functionnull
onChange(value) Invoked when the value of the control changes.
onLoad(data)Invoked when new options have been loaded and added to the control (via the "load" option or "load" API method).Invoked when new options have been loaded and added to the control (via the load option or load API method). function null
render - Custom rendering functions. Each function should accept two arguments: "data" and "escape" and return HTML (string) with a single root element. - The "escape" argument is a function that takes a string and escapes all special HTML characters. + Custom rendering functions. Each function should accept two arguments: data and escape and return HTML (string) with a single root element. + The escape argument is a function that takes a string and escapes all special HTML characters. This is very important to use to prevent XSS vulnerabilities. - +
@@ -379,7 +395,7 @@ $(function() { - + @@ -387,7 +403,7 @@ $(function() { - +
option An option in the dropdown list of available options.
option_createThe "create new" option at the bottom of the dropdown. The data contains one property: "input" (which is what the user has typed).The "create new" option at the bottom of the dropdown. The data contains one property: input (which is what the user has typed).
optgroup_header
optgroupThe wrapper for an optgroup. The "html" property in the data will be the raw html of the optgroup's header and options.The wrapper for an optgroup. The html property in the data will be the raw html of the optgroup's header and options.