jQuery Plugin: imMultiLineList – A Multi-Line ListBox plugin.

I have been working on a project where I needed a ListBox that displays multiple lines of information per row. The user must select from a list of offices, but many of the office names are the same and the only way to distinguish one office from the other is by the office address. Because a ListBox does not allow multiple lines in each row, I decided to create the imMultiLineList jQuery plugin. This plugin will turn any div into a multi-line multi-select list. And because I need to interact with the plugin, I decided to create it using an Object Oriented approach.

The imMultiLIneList plugin is fairly simple to use. Multiple items can be added to the list ajaxally using a JSON object, but the plugin will also allow single items to be manually added.

Options

The following are the options that can be used with the imMultiLineList plugin:

option_map: Just like a ListBox or Select (http://www.w3schools.com/tags/tag_select.asp) element, each row in the imMultiLineList plugin must have a value and display text. The option_map allows the user to define what the optionValue and optionText will be. The option_map is a mandatory option because the plugin won’t know how to parse the JSON data without this map.

?View Code JAVASCRIPT
option_map: {"optionValue": "id", "optionText": "address"}

In the example above, the plugin knows when the JSON data is loaded, to use the id as the optionValue and the address as the optionText.

item_class: Use this option to define the style for the items in the list (more on this later).

item_hover_class: Use this option to define the hover style for the items in the list.

item_select_class: Use this option to define the style for an item when it is selected.

value_text_separator: This option is used when manually adding items to the list. The default value is a tilde (~).

Usage

Because I created the imMultiLineList plugin with an Object Oriented approach, using it requires at least two lines of code. The first line defines the options, and the second is used to initialize the plugin (A standard jQuery plugin defines the options and initializes in a single step).

Adding Items

Use the addItems method to add multiple items to the list. When adding multiple items, the data that is loaded must be in the JSON format.

?View Code JAVASCRIPT
$(document).ready( function() {
	var addressList = $("#listCntnr").imMultiLineList({
		option_map: {"optionValue": "id", "optionText": "address"},
		item_class: "multiListItem",
		item_hover_class: "multiListItemHover",
		item_select_class: 'multiListItemSelect'
	});
	addressList.addItems('assets/js/jquery/immultilinelist/address.php');
});

The addItems method takes a single argument – the url where you intend to retrieve the JSON object. The option_map option must be set prior to loading the data. In the example above, the plugin will try to parse the id and address:

?View Code JAVASCRIPT
[{"id": "1", "address": "Ben\'s Chilli Bowl<br />1213 U St NW Washington, DC<br />20009"}]

Notice the br tags. This is how I create the multiple lines. In fact, the plugin will accept any html, so you could also add images or any other html element.

Add Single Item

The plugin will also you to manually load a single item to the list. The item added can be one of the following:

  1. A JSON object – The JSON must be created with the same data map options:
    {"id": "1", "address": "111 Whatever Street, This City, MD 22222"}
  2. Any string value – If the optionText is not a JSON object, the imMultiLineList plugin will use the value to create a JSON object. The option_map option optionValue can be entered with the optionText value.
    • To specify the optionValue, add the value to end of the string and separate the optionText and optionValue with a tilde (~).
      111 Whatever Street, This City, MD 22222~5

      Note: The tilde can be changed by adding the value_text_separator option.
    • If the optionValue is not part of the string, the imMultiLneList plugin will calculate the value based upon the number of items in the list.

In the example below, I add multiple items using the addItems method. I then add a single item from an input field when the user clicks on a button.

?View Code JAVASCRIPT
$(document).ready( function() {
	var addressList = $("#listCntnr").imMultiLineList({
		option_map: {"optionValue": "id", "optionText": "address"},
		item_class: "multiListItem",
		item_hover_class: "multiListItemHover",
		item_select_class: 'multiListItemSelect'
	});
	addressList.addItems('assets/js/jquery/immultilinelist/address.php');
	$('#theButton').click(function() {
		addressList.addItem($('#theText').val());
	});
});

Get Selected Items

Just like any other ListBox or select, the imMultiLineList plugin allows the developer to retrieve the selected option value and text using the getSelectedItems method. The method will return a multi-dimensional array that contains two members: value and text.

Note: Just like a ListBox, use cntrl-click (cmd-click on Mac) to select multiple items or use shift-click to select a range of items.

In the example below, I retrieve the selected items and then place the value and text inside a div.

?View Code JAVASCRIPT
$(document).ready( function() {
	var addressList = $("#listCntnr").imMultiLineList({
		option_map: {"optionValue": "id", "optionText": "address"},
		item_class: "multiListItem",
		item_hover_class: "multiListItemHover",
		item_select_class: 'multiListItemSelect'
	});
	addressList.addItems('assets/js/jquery/immultilinelist/address.php');
	$('#theButton').click(function() {
		var addresses = addressList.getSelectedItems();
		$.each(addresses, function(i,itm) {
			$('#selectedCntnr').append(itm.value + '<br />' + itm.text + '<br />');
		});
	});
});

Remove Selected Items

Although this may not be useful in most situations, I decided to add the ability to remove selected items from the list. Removing selected items is fairly straightforward – use the removeSelectedItems method.

?View Code JAVASCRIPT
$(document).ready( function() {
	var addressList = $("#listCntnr").imMultiLineList({
		option_map: {"optionValue": "id", "optionText": "address"},
		item_class: "multiListItem",
		item_hover_class: "multiListItemHover",
		item_select_class: 'multiListItemSelect'
	});
	addressList.addItems('assets/js/jquery/immultilinelist/address.php');
	$('#theButton').click(function() {
		addressList.removeSelectedItems();
	});
});

CSS

The list can be styled to your liking. The following is the CSS that I used to create the examples in the demos:

#listCntnr {
	float:left;
	width: 300px;
	height:300px;
	background-color:#fff;
	border: solid thin #000;
	overflow:auto;
	font-family:"arial";
	font-size:12px;
}
.multiListItem {
	width:100%;
	margin-bottom:3px;
	padding-left:3px;
	-moz-user-select: none;
	-khtml-user-select: none;
	user-select: none;
}
.multiListItemHover {
	background-color:#BDE1F2;
	cursor:pointer;
}
.multiListItemSelect {
	background-color: blue;
	color:white;
}

This styling is fairly simple. The listCntnr is the ListBox container. The other styles define the CSS for the item (multiListItem), item hover (multiListItemHover) and select (multiListItemSelect) states. Note that the multiListItem defines user-select attributes. If these attributes are not defined, when a user shift-clicks multiple items, the browser will select the text within each item.

Demos

A demo of this plugin can be viewed in the demo section of this site.

The plugin can be downloaded from GitHub.

Enjoy.

Be Sociable, Share!

Checkout My New Site - T-shirts For Geeks