UPDATE

This has become quite an old version, it’s good to get started, but to get the latest version, please take a look here: http://ndesoft.dk/category/web/js/nmultiselect-js/

Quick links

About NMultiSelect

Okay, I have been foolin’ around with javascripts again, i know, can’t help it. This time I have made me a jQuery plug-in. I chose jQuery because it’s so much easier to do cross browser compatible stuff with that framework, compared to time it will take for me to build it on my own.

The last 3/4 of a year, i have worked on and off with the Microsoft ASP.NET MVC framework, and found it quite likeable, in terms of development speed and possibilities in the markup and, in this case, JavaScript.

While working with the MVC framework, I have been looking for a nice, easy to implement method for a user to choose multiple values from a list. The good ol’ “hold ctrl while clicking”-method doesn’t quite do the job, so I decided to build my own control.

It’s, like most of the other stuff I’ve made, quite easy to use.

Seen from a user’s perspective, it’s simple, click or double click, select and click or what ever he or she feels like. For the developer, it’s also quite easy. A few lines of code, and you’re ready to go:

Getting started

First we need to include a few scripts:

<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>

 <script type="text/javascript" src="http://code.jdempster.com/jQuery.DisableTextSelect/jquery.disable.text.select.pack.js"></script>

 <script type="text/javascript" src="http://nmultiselect.ndesoft.dk/scripts/jquery.nmultiselect.min.js"></script>

Where you wan’t to place your box, you just put a div:

<div id="EmptySelectContainer"></div>

We wan’t to remember this ID for later…

To transform the div, to a multi select box, we will have to write the following piece of code:

$(document).ready(
    function () {
        var m1 = $("#EmptySelectContainer").NMultiSelect("mySelection");
    }
);

What happens here is:

1. $(document).ready – We will wait until the page is ready before doing anything.
2. $(“#EmptySelectContainer”) – We select’s our div, using the ID from earlier. You can use any form of selectors here.
3. NMultiSelect(“mySelection”) – Transform our div to a multi select box. The parameter (mySelection) is the name of the field getting posted to the server. In this case, we will be able to get our data using $_POST[“mySelection”] (using php, but more on that later.)

Now, we have transformed our div to a multi select box, but it’s a bit useless. Lets fill it with some values. To do so, use this function:

AddItemToList(value,text,selected).

The function AddItemToList, takes 3 parameters.

The first, is the value posted to the server. Usually an ID.

The second, is the text shown in the box.

The third, is a boolean value (not mandatory). If true, the item will be selected and visible in the right hand side box.

You can add as many items you want, Below is an example:

m1 = $("#EmptySelectContainer").NMultiSelect("mySelection");

m1.AddItemToList("1-1","Value 1",false);
m1.AddItemToList("2-1","Value 2",false);
m1.AddItemToList("3-1","Value 3",true);
m1.AddItemToList("4-1","Value 4",true);

Here we add 4 items to our box. Whereof the last two are pre-selected.

Now we have our items, it could be nice, to track how the user chooses, for statistics or calling AJAX methods or whatever. To do se, we can subscribe to the event:

SelectionChanged(code).

The parameter (code), is code that will be executed, when a user selects or deselects one or more items.

An example:

m1.SelectionChanged(function(data)
{
    // Do stuff here.
});

The function, or code, that is being executed, must take one parameter, (call it whatever you feel like, i would recommend “data”, because, that is what it is). This parameter contains two properties:

• Items
  • Contains all elements we have added.
• Selection
  • Contains all chosen elements.

The objects contained in the lists, has the following properties:

• Text
• Value
• Selected

Full example

Bellow is a full example. You could also see nmultiselect live here.

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="da">
<head>
    <title>NMultiselect</title>
    <link rel="stylesheet" type="text/css" href="/styles/style.css"/>
    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.5.1/jquery.min.js"></script>
    <script type="text/javascript" src="/scripts/jquery.nmultiselect.min.js"></script>
    <script>
        var m1;
        var m2;

        $(document).ready(
            function () {
                m1 = $("#EmptySelectContainer").NMultiSelect("mySelection",true);

                m1.AddItemToList("1-1","Value 1",false);
                m1.AddItemToList("2-1","Value 2",false);
                m1.AddItemToList("3-1","Value 3",true);
                m1.AddItemToList("4-1","Value 4",true);

                m1.SelectionChanged(function(data)
                {
                    console.log('List 1, selected values: '+(data.Selection.length));
                });

                m2 = $("#EmptySelectContainer2").NMultiSelect("mySelection2");
                m2.AddItemToList("1-2","Value 1",true);
                m2.AddItemToList("2-2","Value 2",false);
                m2.AddItemToList("3-2","Value 3",false);
                m2.AddItemToList("4-2","Value 4",true);
                m2.AddItemToList("5-2","Value 5",true);
                m2.AddItemToList("6-2","Value 6",true);
                m2.AddItemToList("7-2","Value 7",false);
                m2.AddItemToList("8-2","Value 8",false);

                m2.SelectionChanged(function(data)
                {
                    console.log('List 2, selected values: '+(data.Selection.length));
                });
            }
        );
    </script>

</head>
<body>
<form method="get">
    <div id="EmptySelectContainer"></div>
    <p>hejsa</p>
    <div id="EmptySelectContainer2">

    </div>
    <input type="submit" value="submit"/>
    </form>
</body>
</html>

Serverside

So, what to do on the serverside to get the data?

Well, the name you apply in the NMultiSelect function above, is the name of the field getting posted to the server.

If we say, you use the ASP.NET MVC framework, your backend would look somewhat like this:

[HttpPost]
public void GiveMeData(string mySelection)
{
    // Først splittes værdierne:
    // Ja, vi splitter på komma, i en fremtidig version kan dette ændres!
    string[] mySelectionItems = mySelection.Split(',');

    // Gennemløb værdierne:
    foreach(string itemId in mySelectionItems)
    {
        // Du kan her behandle værdierne som du ønsker.
    }
}

PHP

<?php
    # Få fat i værdierne:
    $selection = $_POST["mySelection"];

    # Split værdierne:
    $values = explode(",", $selection);

    # Gennemløb værdierne:
    foreach ($values as &$value) {
            # Gør med dataene hvad du vil.
    }

    # Husk at ryde op:
    unset($value);

?>

Reference

Heres a short reference of all the functions available:

data(‘values’)

If you call data(‘values’), (it’s importent to include the ‘values’ part. This is a jQuery thingy!), you will get an object with two properties:

• Items
• Selection

Each of these properties contains a list of objects. Items – A list of all items we’ve added, and selection – A list of all chosen items. Each of these objects has the following properties:

• Value
• Text
• Selected

In the Items-list, all values will be the ones, the item was created with.

In the Selection-list, the only difference would be, that the selected-property will be true.

Download

You can grap the code and an example here:

Download NMultiSelect 1.0