Setup

Setting up superselector could not be simpler.

Include the css and the library

 <link rel="stylesheet" href="superselector.min.css">
 <script type="text/javascript" src="superselector.js">  </script> 

Create an input element to be the SuperSelctor.

<div id="example-selector"></div>

Turn the element into a superselector with some simple javascript

$("#example-selector").superselector({
    items:[ //array of items for the SuperSelector
        {value:"first", title:"First Item"},
        {value:"second", title:"Second Item"},
    ]
});

Defining Items List

When you create your SuperSelector, you can define the items to be chosen from the selection list in the items array.

$("#example-selector").superselector({
    items:[
        {value:"first", title:"First Item"},
        {value:"second", title:"Second Item"},
        {type:"title", title:"Group Title"},
        {value:"third", title:"Third Item"},
        {value:"fourth", title:"Disabled Item", disabled:true},
        {value:"fifth", title:"Fifth Item"},
        {type:"seperator"},
        {value:"sixth", title:"Sixth Item"},
    ],
})

Each item in the array is an object containing info for each line item.

Item Types

There are three types of line item available in the Superselector.

Standard Item

A standard item defines the value to be returned when the item is selected and the title to be displayed for that item.

{value:"first", title:"First Item"},

There is an optional disabled paramater to set the item to be disabled. in this state it appears greyed out in the list and cannot be selected.

{value:"fourth", title:"Disabled Item", disabled:true},

Title Item

A title item will show up in bold in the list with a darker background and a bigger font. a title item cannot be selected

{type:"title", title:"Group Title"},

Seperator Item

A seperator item appears as a horizontal line in the list.

{type:"seperator"},

Setting The Value

The value of a SuperSelector can be set using the standard jquery val() function.

$("#example-selector").val("first"); // set selector to value of "first"

If the set value is not in the list, then it is displayed in the input box as the value rather than a specified title.

If you wish to set the SuperSelector to a value not in the list, and display a seperate title then you can set the value with an item object instead.

$("#example-selector").val({value:"unlisted_value", title:"Unlisted Value"}); //set the SuperSelectors value to one that isnt in the list, and display a custom title for it.

Getting The Value

The value of a SuperSelector can be read using the standard jQuery val() function.

var value = $("#example-selector").val(); // get selector value

Manipulating List Items

Once your super selector has been created it is possible to change the items in the list using a variety of functions.

Disable/Enable Item

To enable or disable an item, use the disableItem function. The first argumnet should be the value of the item to be changed. The second argument is wheather the element is to be disabled (true) or enabled (param).

$("#example-selector").superselector("disableItem","first", true); //Disable the first item in the list using the items value;

You can also pass the object representing the item instead of its value.

var firstItem = {value:"first", title:"First Item"};
$("#example-selector").superselector("disableItem",firstItem, false); //Enable the first item in the list using the items object;

Remove Item

To remove an item from the list, use the removeItem function, passing items value.

$("#example-selector").superselector("removeItem","first"); //Remove the first item in the list using the items value;

You can also pass the object representing the item instead of its value.

var firstItem = {value:"first", title:"First Item"};
$("#example-selector").superselector("removeItem",firstItem); //Remove the first item in the list using the items object;

Replace Item

To replace an item, use the replaceItem function. The first argumnet should be the item to be replaced, this should either be the value of the item, or an object of the items definition. The second should be an object representing the new value.

var newItem = {value:"new", title:"New Item"};
$("#example-selector").superselector("replaceItem","first", newItem); //Replace the first item in the list using the items value, with the newItem object;

var firstItem = {value:"first", title:"First Item"};
var newItem = {value:"new", title:"New Item"};
$("#example-selector").superselector("replaceItem",firstItem, newItem); //Replace the first item in the list using the items object, with the newItem object;

Add Item

To and an item to the end of the list, use the addItem function. The first argument is the new items object.

var newItem = {value:"new", title:"New Item"};
$("#example-selector").superselector("addItem", newItem); //Add the new item to the end off the list;

Insert Item

To replace an item, use the insertItem function. The first argumnet should be the item to be that you want to insert the item next to, this should either be the value of the item, or an object of the items definition. The second should be an object representing the new value. The third argument is a boolean value representing weather the new item is to be isnerted before (true) or after (false) the specified first item

var newItem = {value:"new", title:"New Item"};
$("#example-selector").superselector("replaceItem","first", newItem, true); //Insert the new item before the first item in the list;

Get Item From value

To get the object of an item based on its value, use the getItem function. pass the value of the item to the function and it will return the object representing the item.

$("#example-selector").superselector("getItems"); //Returns and array of objets for all items in the list;

The function will return false if no item with a matching value is found.

Get All Items

To get the objects for all items in a SuperSelector, use the getItems function.

$("#example-selector").superselector("getItems"); //Returns and array of objets for all items in the list;

Example Returned List:

[
    {value:"first", title:"First Item"},
    {value:"second", title:"Second Item"},
    {type:"title", title:"Group Title"},
    {value:"third", title:"Third Item"},
    {value:"fourth", title:"Disabled Item", disabled:true},
    {value:"fifth", title:"Fifth Item"},
    {type:"seperator"},
    {value:"sixth", title:"Sixth Item"},
]

Set New Items List

To set a completly new list in the SuperSelector, use the setItems function, passing an array of new item objects.

var newItems = items:[
    {value:"newFirst", title:"1st Item"},
    {value:"newSecond", title:"Second Item"},
    {value:"newThird", title:"3rd Item"},
];

$("#example-selector").superselector("setItems", newItems); //clear the old list and add a new list;

CSS Clases

SuperSelector elements are assigned a range of CSS classes to make it easier for you to manipulate the look, feel and function of the selector.