jqListbox Manual

Quick install

1. Copy the js/jqListbox.plugin-1.3.js file to your web root (or in a subfolder)
2. Include the file after jQuery in your HTML file(s)

Quick checklist

1. jQuery is included on your page
2. jqListbox is included on your page
3. You are created a wrapper element (for example a div) which will contain your list container element.
   • However you are not required to create a wrapper element it is better because of styling your listbox via CSS: if you wrap your for example ul list under a div element you can style your div as fixed height and overflow: auto to imitate a listbox with scroll.
     Of course it is up to you how to use jqListbox - maybe you don't need a wrapper element at all.
4. You are created a container element (for example a ul) which will contain your list items.
   • You must call .jqListbox() on the element containing your list items. When a new item will be appended it will be appended into your container element. Don't confuse the optional wrapper element created for styling and the container element containing your list items!
   • If you are working with a ul list you must call .jqListbox on the ul element: $('ul#myul').jqListbox();
5. Your selectable items can be selected by a jQuery selector string (like li). Items will be matched with the defined itemSelector relative to your container element like $('ul#myul').find(itemSelector);
6. Called .jqListbox() on your container element after jQuery and jqListbox loaded and the DOM is ready
7. You have set up your listbox - options, callbacks, events
8. You have set up insert, update, remove, etc events on some triggers (for example button clicks)
9. You have some styles for your list

Terms

Container: the main container for all of your items. If you are using a list then the container can be the <ul> element.
You must call .jqListbox() on your container element.

Wrapper: an optional element containing your container element mainly because of styling via CSS.

Item: one of your item in your listbox.

listboxValueEncoder: a function which will be called any time your listbox has changed (insert, update, etc). The array of the stored items will be passed to this function. Your function must return a value which can be used for example to post back to your backend application and save it. It is recommended to use JSON.stringify()

listboxValueDecoder: a function which will be called when you need to decode your elements. This function is used when the initial values is set from a value generated by the listboxValueEncoder.

itemRenderer: a function which will be called when your items are rendered. This function is called once for every item so you must return a string or jQuery object which must be appended to your list container element.

JSON: JavaScript Object Notation. Text representation of JavaScript objects. Read more here and here.

Initial setup

jQuery, JavaScript

This plugin needs jQuery 1.x (tested with 1.11.3), 2.x (tested with 2.1.4) or 3.x (tested with 3.2.1). You can download jQuery from here or you can use the jQuery CDN. You must include jQuery on every page where jqListbox is used.

Once jQuery is included you must include jqListbox after jQuery is loaded. For production sites you should use the minified version of the plugin (filename ends with .min.js).

<!-- If the plugin found in your /js folder -->    
<script type="text/javascript" src="js/jqListbox.plugin-1.3.min.js"></script>

CSS

No specific style sheet is needed for the jqListbox plugin. Also no style sheets are included in the package.

You can use this plugin with your own CSS styles.

HTML

You can use any structure you like! Just ensure that your items are wrapped under a container.

You will need a container which holds your items. You can initialize the plugin on this container. Also typically you will need to declare when and how to insert, update, remove and render items.

Item selector must be defined relative to your container element because it will be matched with $(container).find(itemSelector); when needed!

The default itemSelector is li. You can override this option via the option itemSelector.

In the following example your container element will be ul#customlist while your items will be the li tags.

<!-- HTML structure -->
    <ul id="customlist">
    </ul>
...
<!-- somewhere in your JS code -->
<script>
    $('#customlist').jqListbox();
</script>    

Initialize the plugin

Simply call the plugin jqListbox() on your container element. You can define custom options as a passed parameter object.

<script>
    $('#customlist').jqListbox({
        selectedClass: 'selected-item',
        mutliselect: false
    });
</script>

Our basic starter structure for the example

<!-- HTML structure -->
    <ul id="customlist">
    </ul>
...
<!-- somewhere in your JS code -->
<script>
    $('#customlist').jqListbox();
</script>

Setup item renderer

The itemRenderer function defines how an item is rendered. The default is to render li items from a basic Array of string structure (var items = ['Item','Item',...];).

The itemRenderer function will be called every time a rendering is needed. The actual rendered item, its position and the instance of the current jqListbox will be passed as parameters.

In this example we are assuming that your items are Objects which contains a field and a price property which needs to be rendered.

<script>
    $('#customlist').jqListbox({
       // Render items
       itemRenderer: function(item, pos, listbox) {
          return '<li>' + item.title + ' (' + item.price + ')</li>';
       }
    });
</script>

Setup listbox value renderer

The listboxValueEncoder function produces the result of your listbox (remember the image on the top of the documentation). jqListbox supporting setting this value in an input by default (see option targetInput) but it is up to you what to do with this value. Typically you want to post it back to your backend application to save it.

The default function used by jqListbox is to convert your array of items to a JSON string. Typically this is what you need: encode your values to JSON string - later you can decode this string on backend side if needed (json_decode in PHP) to save in DB for example.

If you need something else then JSON.stringify() for encoding the values of your listbox just fire up your own function via the option listboxValueEncoder.

Output value

By default jqListbox will try to set this value in an input with id #listbox-value. You can override this selector with the option targetInput. Set the value of this option to false to completely disable this functionality and do it on your own.

Now for the example we will modify the targetInput selector to point to our newly created hidden input. We must add a dummy form above our ul list.

<!-- HTML structure -->
    <form id="target-form" method="post" action="/post.php">
        <input type="hidden" name="output" id="output">
    </form> 
    
    <ul id="customlist">
    </ul>
...
    
<script>
    $('#customlist').jqListbox({
       // Render items
       itemRenderer: function(item, pos, listbox) {
          return '<li>' + item.title + ' (' + item.price + ')</li>';
       },
       // Modify the input selector
       targetInput: '#output'
    });
</script>

If you need custom output logic
The onAfterRender event will be triggered any time when the listbox has changed and re-rendered so it is good to put new output rendering logic there. Don't forget to disable the targetInput option if you need custom logic! Check out the options below.

Setup decoder

A decoder is needed if you want to initialize/pre-set elements in your listbox from encoded values. Generally the listboxValueDecoder function is the opposite function of the listboxValueEncoder.

The default value of the listboxValueDecoder is a function which calls the JSON.parse(), the opposite of JSON.stringify() - so it will return the original array of your items.

If you remember we are already using the default function of listboxValueEncoder so we are good to also leave the default option for listboxValueEncoder for now.

Setup actions

For inserting, updating, deleting your elements you should add some action buttons. You must define your own logic for this actions and call jqListbox's methods to handle your items.

Insert

For this example we are creating a button and add a new item on click.

    <a href="#" id="insert">Insert new element</a>
    <script>
        $('#insert').click(function(e){
            // Show your own dialog or something to your user
            // and clicking on some button insert the new element
            // For this demo we just inserting a new element
            // So basically yes, this call to the insert method should go to the submit handler of your form for example
            $('#customlist').jqListbox('insert', {'title' : 'New element', 'price' : 12345});
            e.preventDefault();
            return false;
        });
    </script>

Update

Updating is similar to inserting: you must call the update method to update the selected item.

If multiple selection is allowed and more than one element is selected then you can update all of them with the same data or pass an array of updated elements to update each selected element with different data (so you must pass one updated element for every selected element) to the updateMulti method. Yes, there are two update methods: the update and the updateMulti (and the third is the updateAt).

    <a href="#" id="update">Update element</a>
    <script>
        $('#insert').click(function(e){
            // Show your own dialog or something to your user
            // and clicking on some button update the selected element(s)
            // For this demo we just updating the selected elements
            $('#customlist').jqListbox('update', {'title' : 'Updated element', 'price' : 99999});
            e.preventDefault();
            return false;
        });
    </script>

Remove

Also deletion is similar to updating. Calling the remove method will remove all of the selected elements.

    <a href="#" id="remove">Remove selected</a>
    <script>
        $('#remove').click(function(e){
            if (confirm('Are you sure?')) {
               $('#customlist').jqListbox('remove');
            }
            e.preventDefault();
            return false;
        });
    </script>

Clear

Calling the clear method will remove all of the elements.

    <a href="#" id="clear">Clear</a>
    <script>
        $('#clear').click(function(e){
            if (confirm('Are you sure?')) {
               $('#customlist').jqListbox('clear');
            }
            e.preventDefault();
            return false;
        });
    </script>

Move up

The built-in moveup method supports multiple selection. When calling moveup all of the selected items will be moved up by one position. If the very-first element is moved up it will be moved to the end of the list and all other elements will be pushed up by one position.

    <a href="#" id="moveup">Move up</a>
    <script>
        $('#moveup').click(function(e){
            $('#customlist').jqListbox('moveup');
            e.preventDefault();
            return false;
        });
    </script>

Move down

The built-in movedown method supports multiple selection. When calling movedown all of the selected items will be moved down by one position. If the very-last element is moved down it will be moved to the beginning of the list and all other elements will be pushed down by one position.

    <a href="#" id="movedown">Move up</a>
    <script>
        $('#movedown').click(function(e){
            $('#customlist').jqListbox('movedown');
            e.preventDefault();
            return false;
        });
    </script>

Enable only available actions

Of course you don't want to enable the update or remove action if no items are selected. You can easily do this by setting up some easy logic.

The onBeforeRender or the onAfterRender are two good candidates for this kind of logics.

What you want is: if no element is selected (countSelected() method returns 0) then disable the update,remove,moveup and movedown actions. In this example we just add a disabled class to these buttons.

    <script>
        $('#customlist').jqListbox({
            ...
            onBeforeRender: function (listbox) {
                if (listbox.countSelected() == 0) {
                    $('#update,#remove,#moveup,#movedown').addClass('disabled');
                } else {
                    $('#update,#remove,#moveup,#movedown').removeClass('disabled');
                }
            }
            ...
        });
    </script>

Optional events

There are a lot of callbacks triggered by different events: for example you can fire up some custom logic before a new element is inserted or elements are updated. Also you can change the newly inserted element before the insertion, etc. There are a lot of possibilities in these callbacks!

Methods

You can use the following methods in jqListbox.

Every method can be accessed via the jqListbox instance but there are some methods which are intended for internal use only - for example you won't need to call setupAutoClickHandler by hand.
I'm listing only the methods intended for use in your code - however you can check all of the methods in the documented source file.

Call these methods on the jqListbox instance on your element like $('#customlist').jqListbox('remove');. Simply pass parameters like $('#customlist').jqListbox('removeByIndex', 4);. In the callbacks where the current instance is passed you can simply use the methods of the passed instance (like listbox.removeByIndex(4);

Options

You can pass several options to the jqListbox plugin on initialization.

function (item, pos, jqListbox) {
   return '<li>' + item + '</li>';
}

function (items) {
   return JSON.stringify(items);
}

function (values) {
    if (values.length > 0) {
       return JSON.parse(values);
    }
    return [];
}

Callback and method scopes

Each callback and method uses the scope of the container element which has the jqListbox instance. It means that $(this) will point to the container jQuery element inside your callback.

<script>
    $('#price-table').jqListbox({
        onBeforeAllowed: function (el, id, jqListbox){
            $(this).remove(); // this will remove the $('#price-table') element!
        }
    });
</script>