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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A reference to a select object in a form
regExp	String or Regular Expression Literal	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A reference to a select object in a form
regExp	String or Regular Expression Literal	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A reference to a select object in a form
regExp	String or Regular Expression Literal	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A 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.

Argument	Type	Required	Description
fromSelect	<select> object	Yes	A reference to a select object in a form to move options from
toSelect	<select> object	Yes	A reference to a select object in a form to move options to
autosort	Boolean	No	True to sort select lists after moving, false to not sort
regexp	String or Regular Expression Literal	No	A 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.

Argument	Type	Required	Description
fromSelect	<select> object	Yes	A reference to a select object in a form to move options from
toSelect	<select> object	Yes	A reference to a select object in a form to move options to
autosort	Boolean	No	True 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.

Argument	Type	Required	Description
fromSelect	<select> object	Yes	A reference to a select object in a form to move options from
toSelect	<select> object	Yes	A reference to a select object in a form to move options to
autosort	Boolean	No	True to sort select lists after moving, false to not sort
regexp	String or Regular Expression Literal	No	A 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.

Argument	Type	Required	Description
fromSelect	<select> object	Yes	A reference to a select object in a form to move options from
toSelect	<select> object	Yes	A reference to a select object in a form to move options to
autosort	Boolean	No	True 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A reference to a select object in a form
index1	Int	Yes	The index in the options[] array of the first option to swap
index2	Int	Yes	The 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A 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.

Argument	Type	Required	Description
selectObject	<select> object	Yes	A reference to a select object in a form

Returns: Boolean