Logo
doctype [?]
[strict] [loose] [none]

Selectbox Utility Functions


The Selectbox.js library creates a global Selectbox object, which has a number of class methods used to manipulate <select> options.

These methods are added as part of the Date object itself, and do not need an instantiated Date object.


Selectbox.hasOptions (selectObject) : Boolean

Returns true if the select object has a non-null option object (even if there are no actual options), otherwise false.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean


Selectbox.selectOptions (selectObject, regExp) : Boolean

Given a select object, the method selects options whose .text value matches the regular expression passed in. The regex passed in is passed to the RegExp() constructor, so it can either be a string ("text") or a regular expression literal (/text/). If a string is passed, any option whose .text value contains the string will be selected. If multiple options match in a single-select object, only the last matching option will remain selected. Options which are already selected which do not match the regexp will remain selected. Returns false if RegExp() constructor is not supported or the select object has no options, otherwise returns true.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form
regExpString or Regular Expression LiteralYesA string or regular expression to match against option .text's

Returns: Boolean


Selectbox.selectOnlyOptions (selectObject, regExp) : Boolean

Works just like the selectOptions() method, but any options that do not match the regexp are unselected.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form
regExpString or Regular Expression LiteralYesA string or regular expression to match against option .text's

Returns: Boolean


Selectbox.unselectOptions (selectObject) : Boolean

Given a select object, the method unselects options whose .text value matches the regular expression passed in. The regex passed in is passed to the RegExp() constructor, so it can either be a string ("text") or a regular expression literal (/text/). If a string is passed, any option whose .text value contains the string will be unselected. Returns false if RegExp() constructor is not supported or the select object has no options, otherwise returns true.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form
regExpString or Regular Expression LiteralYesA string or regular expression to match against option .text's

Returns: Boolean


Selectbox.sort (selectObject) : Boolean

Sorts the options in a select list by their .text value. Sorting will always be done alphanumerically, so a text value of "10" will be before a text value of "5". Selected options will remain selected. Returns false if there is no options object, otherwise true.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean


Selectbox.selectAllOptions (selectObject) : Boolean

Marks all options in a select object as selected. In a single-select, only the last option will remain selected. Returns false if there is no options object, otherwise true.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean


Selectbox.moveSelectedOptions (fromSelect, toSelect [,autosort [,regexp]]) : Boolean

Moves the selected options from one select object to another, appending them to the end of the target select and removing them from the first select box. If no options are selected, then nothing is moved. After moving options, both lists are re-sorted using the Selectbox.sort() method, unless the autosort parameter is false. Finally, a regular expression may be passed as the fourth argument. Any options in the 'from' list whose .text value matches the regular expression will not be moved, even if selected. Returns true if successful, else false.

ArgumentTypeRequiredDescription
fromSelect<select> objectYesA reference to a select object in a form to move options from
toSelect<select> objectYesA reference to a select object in a form to move options to
autosortBooleanNoTrue to sort select lists after moving, false to not sort
regexpString or Regular Expression LiteralNoA string or regular expression to match against option .text's<

Returns: Boolean


Selectbox.copySelectedOptions (fromSelect, toSelect [,autosort]) : Boolean

Works just like the moveSelectedOptions() method, except options are copied rather than moved and there is no regexp argument. If the option already exists in the target list, another copy is not created.

ArgumentTypeRequiredDescription
fromSelect<select> objectYesA reference to a select object in a form to move options from
toSelect<select> objectYesA reference to a select object in a form to move options to
autosortBooleanNoTrue to sort select lists after moving, false to not sort

Returns: Boolean


Selectbox.moveAllOptions (fromSelect, toSelect) : Boolean

Works just like moveSelectedOptions() except all options are considered, not just the ones that are selected.

ArgumentTypeRequiredDescription
fromSelect<select> objectYesA reference to a select object in a form to move options from
toSelect<select> objectYesA reference to a select object in a form to move options to
autosortBooleanNoTrue to sort select lists after moving, false to not sort
regexpString or Regular Expression LiteralNoA string or regular expression to match against option .text's<

Returns: Boolean


Selectbox.copyAllOptions (fromSelect, toSelect [,autosort]) : Boolean

Works just like copySelectedOptions() except all options are considered, not just the ones that are selected.

ArgumentTypeRequiredDescription
fromSelect<select> objectYesA reference to a select object in a form to move options from
toSelect<select> objectYesA reference to a select object in a form to move options to
autosortBooleanNoTrue to sort select lists after moving, false to not sort

Returns: Boolean


Selectbox.swapOptions (selectObject, index1, index2) : Boolean

Swaps the position of two options in a select box. Their selected and defaultSelected properties are maintained. Returns true if successful, else false.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form
index1IntYesThe index in the options[] array of the first option to swap
index2IntYesThe index in the options[] array of the second option to swap

Returns: Boolean

Selectbox.moveOptionUp (selectObject) : Boolean

Moves the selected option(s) up one position. If multiple options are selected, they are each moved up and their selected status is maintained. If the first option is selected, it is of course not moved.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean

Selectbox.moveOptionDown (selectObject) : Boolean

Moves the selected option(s) down one position. If multiple options are selected, they are each moved down and their selected status is maintained. If the last option is selected, it is of course not moved.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean

Selectbox.removeSelectedOptions (selectObject) : Boolean

Removes all the selected options from the select object. Returns true if successful, else false.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean

Selectbox.removeAllOptions (selectObject) : Boolean

Removes all options from a select object. Returns true if successful, else false.

ArgumentTypeRequiredDescription
selectObject<select> objectYesA reference to a select object in a form

Returns: Boolean