Methods reference
Here is some methods to manipulate your Celesta instances directly (that is, without any user actions).
Examples below assume you have Celesta instance created and named c
(why not c
?):
var c = new Celesta ( document . getElementById ( 'my_select' ));
Most methods examples below will use this c
variable to demonstrate some usage case.
c . someCoolMethod ();
And only static methods examples (there are few) will use Celesta.prototype
instead.
Arguments:
{object} config_overrides
Static method to override default options (config params) for all newly created Celesta instances.
Accepts an object of option names and values , like the following.
Celesta . prototype . setConfigDefaults ({
space_key_open : false ,
options_nav_cycling : true ,
closed_options_pagekey_jump_by : 5
})
Arguments:
{string} param_name
Returns:
{*}
Get the value for config param (option ) specified.
c . getConfigParam ( 'enter_key_open' ); // => true
c . getConfigParam ( 'typed_life' ); // => 1000
var x = new Celesta ( document . querySelector ( '.another-select' , { typed_life : 1500 });
x . getConfigParam ( 'typed_life' ); // => 1500
Returns:
{boolean}
Returns true
if current instance is successfully initialized, false
otherwise.
c . isInitialized (); // => true
Arguments:
{string} event_name
,
{function} handler
Attaches a callback that will be fired on certain event.
For more information on events and callback arguments, see Events reference .
c . addEventListener ( 'open' , function () {
console . log ( 'bang!' );
});
c . open (); // 'bang!'
c . addEventListener ( 'change' , function ( new_value , old_value , new_text , old_text , new_index , old_index ) {
console . log ( "Changed to option '" + new_value + "' which has text '" + new_text + "' and index '" + new_index + "'." );
});
c . selectOption ( 2 ); // "Changed to option 'second' which has text 'The second option' and index '2'."
c . selectOption ( 3 ); // "Changed to option 'third' which has text 'The third option' and index '3'."
c . selectOption ( 3 ); // (nothing happens, because selected option wasn't changed)
Turns Celesta to open state (as if it was mouse-clicked).
c . open (); // (now you can see it opened)
Turns Celesta to closed state (as if Esc was pressed).
c . close (); // (now you can see it closed)
Turns Celesta to closed state (as if Esc was pressed).
c . toggle (); // (now you can see it opened)
c . toggle (); // (now you can see it closed again)
Returns:
{boolean}
Returns true
if Celesta is currently in open state, false
otherwise.
c . open ();
c . isOpen (); // => true
c . close ();
c . isOpen (); // => false
c . toggle ();
c . isOpen (); // => true
c . toggle ();
c . isOpen (); // => false
Arguments:
{boolean} value
Set or unsets disabled state for Celesta instance. Accepts boolean value (true
to disable, false
to enable).
c . setDisabled ( true ); // (now you can see it disabled)
c . setDisabled ( false ); // (now you can see it enabled again)
A shortcut for setDisabled(true)
.
c . disable (); // (now you can see it disabled)
A shortcut for setDisabled(false)
.
c . enable (); // (now you can see it enabled)
Returns:
{boolean}
Returns true
if Celesta is currently in open state, false
otherwise.
c . isDisabled (); // => false
c . disable ();
c . isDisabled (); // => true
c . enable ();
c . isDisabled (); // => false
Arguments:
{number} index
,
{boolean=false} force
Selects an option by index.
c . selectOption ( 2 ); // (option with index 2 is now selected)
Arguments:
{number} index
Pre-selects an option by index. That imitates the behavior of displaying the text for keyboard-focused option
in selectbox facade without selecting it.
Pre-selected option only becomes selected only after selectbox (or Celesta) is closed (even by pressing Esc).
Only works on open Celesta instance.
// assuming we have closed Celesta with option values like 'first', 'second' etc., and 'first' is now selected
c . getValue (); // => 'first'
c . preselectOption ( 2 ); // (nothing happens, because Celesta is closed)
c . getPreselectedOptionIndex (); // => undefined
c . getValue (); // => 'first'
c . open ();
c . preselectOption ( 2 ); // (option with index 2 is now pre-selected)
c . getPreselectedOptionIndex (); // => 2
c . getValue (); // => 'first' (pre-selected doesn't mean selected!)
c . close ();
c . getPreselectedOptionIndex (); // => undefined (pre-selected option doesn't exist on closed Celesta)
c . getValue (); // => 'second' (instead, it became really selected!)
Arguments:
{number} index
,
{boolean=false} is_mouse
,
{boolean=false} force
Hovers (focuses) an option by index.
Accepts optional second param is_mouse
, default false
(which means “keyboard”).
By default, keyboard-focused items are also pre-selected , but mouse-hovered aren’t
(that depends on keyboard_hover_preselect
and mouse_hover_preselect
config params).
Only works on open Celesta instance.
// assuming we have closed Celesta with option values like 'first', 'second' etc., and 'first' is now selected
c . getValue (); // => 'first'
c . hoverOption ( 2 ); // (nothing happens, because Celesta is closed)
c . open ();
c . hoverOption ( 2 ); // (option with index 2 is now focused "by keyboard")
c . getPreselectedOptionIndex (); // => 2 (by default, keyboard-focused item is also pre-selected)
c . hoverOption ( 3 , true ); // (option with index 3 is now hovered "by mouse")
c . getPreselectedOptionIndex (); // => 2 (still 2, because by default, mouse-hovered item isn't pre-selected)
c . hoverOption ( 3 , false ); // (option with index 3 is now hovered "by keyboard"; actually, that false value isn't needed)
c . getPreselectedOptionIndex (); // => 3 (finally, now it is 3)
Arguments:
{number} index
Acts as hoverOption on open Celesta, and as selectOption on closed one.
c . open ();
c . jumpToOption ( 2 ); // (option with index 2 is now hovered)
c . close ();
c . jumpToOption ( 4 ); // (option with index 4 is now selected)
Returns:
{string}
Returns the value of currently selected option.
// assuming you have <option value="second">The second option</option>
c . getSelectedOptionValue (); // => 'second'
Returns:
{string}
An alias for getSelectedOptionValue .
// assuming we have <option value="second">The second option</option>
c . getValue (); // => 'second'
Returns:
{string}
Returns the text of currently selected option.
// assuming we have <option value="second">The second option</option>
c . getValue (); // => 'The second option'
Returns:
{number}
Returns the index of currently selected option.
// assuming we have Celesta with option values like 'zero', 'first', 'second' etc., and 'zero' is now selected
c . getSelectedOptionIndex (); // => 0
c . getValue (); // => 'zero'
c . selectOption ( 2 );
c . getSelectedOptionIndex (); // => 2
c . getValue (); // => 'second'
Returns:
{number|undefined}
Returns the index of currently pre-selected option (undefined
if none).
// assuming we have closed Celesta with option values like 'zero', 'first', 'second' etc., and 'zero' is now selected
c . open ();
c . getPreselectedOptionIndex (); // => undefined (nothing was pre-selected by now)
c . preselectOption ( 2 );
c . getSelectedOptionIndex (); // => 2
c . close ();
c . getSelectedOptionIndex (); // => undefined (Celesta is closed, no pre-selected option exists)
Returns:
{number|undefined}
Returns the index of currently hovered (focused) option (undefined
if none).
// assuming we have closed Celesta with option values like 'zero', 'first', 'second' etc., and 'zero' is now selected
c . getHoveredOptionIndex (); // => undefined (Celesta is closed, no hovered option exists)
c . open ();
c . getHoveredOptionIndex (); // => 0 (on open, selected option is focused automatically)
c . hoverOption ( 2 );
c . getHoveredOptionIndex (); // => 2
c . close ();
c . getHoveredOptionIndex (); // => undefined (because Celesta is closed)
Act as if ArrowUp (↑ ) key is pressed (selects/hovers previous available option).
// assuming you have months option list with September currently selected
c . getValue (); // => 'september'
c . arrowUp ();
c . getValue (); // => 'august'
Act as if ArrowDown (↓ ) key is pressed (selects/hovers next available option).
// assuming you have months option list with September currently selected
c . getValue (); // => 'september'
c . arrowDown ();
c . getValue (); // => 'october'
// now, assuming you have weekdays list with Wednesday currently selected, and (for some reason) Thursday disabled
c . getValue (); // => 'wednesday'
c . arrowDown (); // (goes down, skips disabled option, so actually goes down once more)
c . getValue (); // => 'friday'
Acts as if PageUp key is pressed (skips several options up). The jump size differs depending on open state, and relies on values for options closed_options_pagekey_jump_by
and open_options_pagekey_jump_by
.
// assuming that Celesta is currently closed, and jumps by 3 items by default
// also assuming it contains a list of months with September currently selected
c . getValue (); // => 'september'
c . pageUp (); ( skips 3 items up )
c . getValue (); // => 'june'
Acts as if PageDown key is pressed (skips several options down). The jump size differs depending on open state, and relies on values for options closed_options_pagekey_jump_by
and open_options_pagekey_jump_by
.
// assuming that Celesta is currently closed, and jumps by 3 items by default
// also assuming it contains a list of months with September currently selected
c . getValue (); // => 'september'
c . pageDown (); ( skips 3 items down )
c . getValue (); // => 'december'
Arguments:
{string} new_char
Appends a character to the end quicksearch text (as if it was typed from the keyboard, to find some option).
// assuming you have an option list that contains weekdays
c . appendTyped ( 't' ); // (quicksearch text is now: 't', 'Tuesday' becomes selected)
c . appendTyped ( 'h' ); // (quicksearch text is now: 'th', 'Thursday' becomes selected)
c . appendTyped ( 'w' ); // (quicksearch text is now: 'thw', 'Thursday' is still selected because there is no matching item)
Clears quicksearch text previously (as if Backspace was pressed while typing).
// assuming you have an option list that contains weekdays
c . appendTyped ( 't' ); // (quicksearch text is now: 't', 'Tuesday' becomes selected)
c . appendTyped ( 'h' ); // (quicksearch text is now: 'th', 'Thursday' becomes selected)
c . appendTyped ( 'w' ); // (quicksearch text is now: 'thw', 'Thursday' is still selected because there is no matching item)
c . clearTyped (); // (quicksearch text is now empty)
c . appendTyped ( 'w' ); // (quicksearch text is now: 'w', 'Wednesday' becomes selected)
Returns:
{HTMLSelectElement}
Returns DOM element for source <select>
.
c . getSourceSelect (); // => HTMLSelectElement: <select id="my_select">...</select>
Returns:
{HTMLElement}
Returns DOM element for Celesta overall container. May be used to attach some click events etc.
c . getContainer (); // => HTMLSpanElement: <span class="celesta-container">...</span>
Returns:
{HTMLElement}
Returns DOM element for Celesta facade (a block to display currently selected option). May be used to attach some click events etc.
c . getFacade (); // => HTMLSpanElement: <span class="celesta-facade">...</span>
Returns:
{HTMLElement}
Returns DOM element for Celesta options list container. May be used to attach some custom scroll library.
c . getFacade (); // => HTMLSpanElement: <span class="celesta-facade">...</span>
Rebuilds Celesta DOM structure, based on source <select>
structure. To be called after external change of source <select>
.
Assuming we have the following HTML markup:
<select id= "the_select" >
<option value= "milk" > Milk</option>
<option value= "honey" > Honey</option>
</select>
Now, let’s play:
var source = document . getElementById ( 'the_select' );
var celesta = new Celesta ( source ); // (contains 'Milk' and 'Honey' items with indexes 0 and 1)
celesta . selectOption ( 1 ); // (selecting 'Honey')
celesta . getSelectedOptionIndex (); // => 1
// now, adding another option (using jQuery syntax to make more readable)
$ ( source . options [ 0 ]). insertAfter ( '<option value="toast">Toast</option>' ); // source select now has 'Milk' and 'Toast' and 'Honey'
// but linked Celesta doesn't know anything about this change, so it cannot even selected third item (which has index 2)
celesta . selectOption ( 2 ); // trying to select last item
celesta . getSelectedOption (); // => 1 (nothing changed, because 2 is out of options range remembered by Celesta)
// so we need to make a refresh
celesta . refresh ();
celesta . selectOption ( 2 ); // trying to select last item, again
celesta . getSelectedOption (); // => 2 (finally, we got it!)
Just an alias for refresh .
c . update ();
Destroy any DOM structure and handlers created by Celesta instance. Restores source select to be visible and selectable.
c . selectOption ( 2 ); // (that also affects source select)
c . destroy (); // (restores source select, with index 2 selected)