jQuery

Init heapbox:

$("#mySelect").heapbox();

Documentation

Settings

Settings name Description
tabindex
(default = undefined)
Tabindex value.
insert
(default = before)
Where to insert heapbox.(available: before, after, inside)
emptyMessage
(default = 'Empty')
Message shown when source selectbox is empty.
heapsize
(default = undefined)
Max height of heapbox.
effect{type}
(default = 'slide')
Effect used to show/hide list of options. (available: fade,slide,standard)
effect{speed}
(default = 'slow')
Speed of effect used to show/hide list of options. (available: slow, fast)

Events

Event name Description
openStart() Event is triggered when heapbox opening started.
openComplete() Event is triggered when heapbox opening is complete.
closeStart() Event is triggered when heapbox closing started.
closeComplete() Event is triggered when heapbox closing is complete.
onChange(value) Event is triggered when user select value in heapbox.

Examples

Basic

Basic heapbox without any configuration.

$("#mySelect1").heapbox();

Result:


Basic non-select heapbox

Basic non-select heapbox.

$("#myDivElement").heapbox({'insert':'inside'});
json = '[{"value":"value_1","text":"value 1"},{"value":"value_2","text":"value 2"}]';
$("#myDivElement").heapbox("set",json);

Result:


Insertion

Heapbox can be inserted before, after or inside defined element. If defined element is select, only before or after option can be used.

$("#mySelect10").heapbox({'insert':'after'});

Result:


Selected attribute

Heapbox till version 0.9.1 supports selected attribute. Let's say you have three values in your select mac, linux and windows. Linux option has selected attribute.

Result:


Tabindex attribute

Heapbox knows how to take tabindex from source element if it's defined. Tabindex can be also set manually. Manually defined tabindex has higher priority.

Example

$("#mySelect11").heapbox({'tabindex':'11'});

Events and callbacks

Example of available heapbox events and callbacks

$(".mySelect").heapbox({
'onChange':function(){$("#eventLog").prepend("Heapbox changed, value is: "+value+"");},
'openStart':function(){$("#eventLog").prepend("Heapbox is opening");},
'openComplete':function(){$("#eventLog").prepend("Heapbox has been opened");},
'closeStart':function(){$("#eventLog").prepend("Heapbox is closing");},
'closeComplete':function(){$("#eventLog").prepend("Heapbox has been closed");},
});

Result:


waiting for events...

Themes

Everything about heapbox is fully customizable via CSS. Curently available "ready to use" themes are:


Long lists

Heapbox know how to deal with long lists:

$("#mySelect12").heapbox({"heapsize":"100px"});

AJAX

Heapbox is AJAX friendly.

//init heapbox for #ajaxSelect and define onChange callback with ajax
$("#ajaxSelect").heapbox({
 'onChange':function(value)
 {
  //hide heapbox
  $("#ajaxSelect2").heapbox("hide");
 
   if(value){
   $.ajax({
    type: "POST",
    url: "ajax/ajax.php",
    data: "type="+value,
    success:function(data)
    {
     showAjaxSelect2(data);
     $("#ajaxSelect2").heapbox("show");
    }
    });
   }
 }
});

//init heapbox for #ajaxSelect2
$("#ajaxSelect2").heapbox({
 'onChange': function(value)
 {
  showMessage();
 }
});
 
 //hide heapbox
 $("#ajaxSelect2").heapbox("hide");

//set data to heapbox for #ajaxSelect2
function showAjaxSelect2(data)
{
   $("#ajaxSelect2").heapbox("set",data);
}

//show selected values
function showMessage()
{
  foodType = $("#ajaxSelect option:selected").attr("value");
  food = $("#ajaxSelect2 option:selected").attr("value");

  alert("Cool, you are into "+foodType+", especially "+food+".");
}
          

Result:


Effects

Heapbox supports effects. Actually you can choose between slide, fade or no effect. Example of slow fade effect:

$("#mySelect3").heapbox({
        'effect': {
                'type': 'fade',
                'speed': 'slow'
        }
});

Result:


Setting data dynamically

Data can be also set dynamically whenever you need.

$("#mySelect4").heapbox();
json = '[{"value":"dynamic_value_1","text":"Dynamic value 1"},{"value":"dynamic_value_2","text":"Dynamic value 2"}]';
$("#mySelect4").heapbox("set",json);

Manual heapbox update

Okay, you have already own functions to update selectboxes. No problem. Just say when heapbox should update his data.

//init heapbox
$("#mySelect5").heapbox();

//add new option to source selectbox
newOption = $('

Access selected data in JavaScript

Selected data can be accessed in JavaScript via onChange callback

$("#mySelect5").heapbox({
        'onChange':function(value){alert('Selected value: '+value)}
});

Result:


Disable and enable heapbox

You can also disable or enable heapbox whenever you want. Disabled heapbox has CSS classes "heapbox" and "disabled".

Disable heapbox:

$("#mySelect7").heapbox("disable");

Result:


Enable heapbox:

$("#mySelect8").heapbox("enable");

Result:


Empty heapbox

When source selectbox is empty emptyMessage option text is shown.

$("#mySelect9").heapbox({emptyMessage: 'It\'s empty'});

Result:


Todo


  • Tabindex support
  • Selectbox attribute "disabled" support
  • Suboptions support
  • Optgroup support
  • Create twitter bootstrap theme
  • Fix for long lists of options (scrollbars etc)
  • Keyboard events

Changelog


v1.0.0 (not released yet)

  • final release

v0.9.4 (not released yet)

  • html options support

v0.9.3 (not released yet)

  • improved keyboard support
  • support for long lists of options
  • option disabled attribute support
  • bug fixes

v0.9.2

  • keyboard support - heapbox is fully keyboard accessible
  • tabindex support
  • fixed bug in onChange event

v0.9.1

  • added selected attribute support
  • heapbox can be used also with non-select elements
  • new option "insert" added (before, after, inside values available)
  • fixed bug (enable vs disable heapbox)

v0.9.0

  • Initial version