jQuery.plainList - Documentation

0: Before starting

Before you begin download the newest jQuery library and the plainList (jquery.plainlist.js) plugin. Save both to "js/" folder on your webserver.

1: Add JavaScript libraries

	<script type="text/javascript" src="js/jquery-1.3.2.min.js"></script>
	<script type="text/javascript" src="js/jquery.plainlist.js"></script>

2: Add default classes (styles)

.plainList_normal {
	padding:5px 5px 5px 5px;
	margin:3px 3px 3px 3px;
	border:2px solid #EDE5DF;
	display:inline-block;
	cursor:pointer;
	background-color:#CEC7B8;
}

.plainList_hover {
	background-color:#eeeeee;
}

.plainList_selected {
	color:white;
	background-color:#65482C;
}

3: Create an empty div-container for plainList

<div id="myElement"></div>

(Object) options.elements = {}

Insert pre defined elements. Each element schould have a pattern like this: {"element-id":{"attribute1":"attribute value", ...}, ...}

$("#eElements1").plainList({
	elements: {"aaa":{title:"AAA"}, "bbb": {title:"BBB"}, "ccc": {title:"CCC"}}
});

(Object) options.classes = {normal: "plainList_normal", hover: "plainList_hover", selected: "plainList_selected"}

Style classes for normal, mouse over and selected elements.

$("#eClasses1").plainList({
	classes: {
		normal : "myNormal",
		hover : "myHover",
		selected : "mySelected"
		},
	elements: {"aaa":{title:"AAA"}, "bbb": {title:"BBB"}, "ccc": {title:"CCC"}}
});

(Boolean) options.multiselect = true

Allow selection of multiple elements.

$("#elementMultiselect2").plainList({
	multiselect : false,
	elements: {"aaa":{title:"AAA"}, "bbb": {title:"BBB"}, "ccc": {title:"CCC"}}
});

(Function) options.titleRenderer = function(id, attr){return attr["title"];}

The element title (text of the element) will be redered by using this function.
(String) id - ID of the element.
(Object) attr object with attributes of the current element.

$("#eTitleRenderer1").plainList({
	elements: {"aaaa":{title:"AAAA"}, "bb": {title:"BB"}, "ccc": {title:"CCC"}},
	titleRenderer : function(attr){
			var number = randomNumber(10,3000);
			return attr["title"]+" ("+attr["title"].length+" chars)";
		}
});

(Function) options.onChange = function(selected){}

This function will be called every time selection changes.

$("#eOnChange1").plainList({
	elements: {"aaa":{title:"AAA"}, "bbb": {title:"BBB"}, "ccc": {title:"CCC"}},
	onChange: function(selected){
		alert("Selected elements: "+selected);
	},
});

Variable access

You can directly assign the created plainList object to a variable. For accessing its methods later simply use the variable.

var access1 = $("#eAccess1").plainList({});
for(var i=0; i<10; i++) {
	access1.append(Math.round(Math.random()*1000));
}

Direct DOM element access

It's not necessary to store each plainList object in a separate variable. Once you created it you can access it's methods by initialising it without any options.

Append (look at the previous plainList object after a click)

<button onclick='$("#eAccess1").plainList().append(Math.round(Math.random()*1000))'>Append</button>

(void) .append(id, [attr])

(String) id - the unique ID of the element. It is not possible to insert two or more elements with identical ID in a plainList element.
(Object) attr - (Optional) an object with key-value pairs which will be saved in the object. If attr is empty, the attr.title will be automatical created and set to id.

Press me!

$("#eAppend1").plainList().append(Math.round(Math.random()*1000), {title: "WWW"});

(Object) .attr(id, [attributes])

If attributes is undefined: the method returns all attributes of an element.
If attributes are defined: the attributes of particulat object will be set to attributes.
(String) id - id of an element.

alert($("#eAttr1").plainList().attr("aaa").title)

(this) .clear()

Removes all elements from the plainList container and returns the cleared plainList object.
Clear!

$("#eClear1").plainList().clear();

(Object) .clone()

Clone all elements and their attributes (only first level of attributes).
Clone!

$("#eClone2").plainList({elements:$("#eClone1").plainList().clone()});

(Object) .cloneSelected()

Clone all selected elements and their attributes (only first level of attributes).
Clone selected!

$("#eCloneSelected2").plainList({elements:$("#eCloneSelected1").plainList().cloneSelected()});

(Object) .getElement(id)

Returns a DOM object reference of element.
(String) id - ID of an element.

Press me!

$("#eGetElement1").plainList().getElement("aaa").css("font-size","22pt");

(Array) .getElementIds()

Returns array if IDs of all elements of the list.

Press me!

alert($("#eGetElementIds1").plainList().getElementIds());

(Array) .getElements()

Returns all DOM objects of all elements (buttons). In the example below we use this method to add a qTip tooltip to every element.

$("#eGetElements1").plainList({
	elements: {"aaa":{title:"AAA"}, "bbb": {title:"BBB"}, "ccc": {title:"CCC"}}
});
$.each($("#eGetElements1").plainList().getElements(), function(index, item){
	$(item).qtip({	content: 'Hello!', style: { name: 'cream', tip: true } });
});

(Array) .getSelected()

Returns an array of IDs of selected elements.

Press me!

$("#eGetSelected1").plainList().getSelected()

(this) .repaint(id)

Repaints an element with particular id. This method can be used if the content depends on attributes of the element.
(String) id - ID of an element.

Press me!

$("#eRepaint1").plainList().attr("aaa").color = "blue";
$("#eRepaint1").plainList().repaint("aaa");

(this) .select(id, [state])

This method selects an element with particular ID.(String) id - element's ID.
(boolean) state - (Optional) the end state of the element. true - selected, false - unselected.

toggle 'aaa' / select 'aaa' / unselect 'aaa'

$('#eSelect1').plainList().select('aaa');
$('#eSelect1').plainList().select('aaa', true);
$('#eSelect1').plainList().select('aaa', false);

(this) .selectAll(select)

(boolean) select - true - all elements will be selected, false - all already selected elements will be unselected.

select all / unselect all

$('#eSelectall1').plainList().selectAll(true);
$('#eSelectall1').plainList().selectAll(false);

(this) .setMultiselect(multiselect)

Enable or disable multiselect.
(boolean) multiselect - true - enable multiselect, false - disable multiselect (selected items except one will be unselected).

enable / disable

$('#eSetMultiselect1').plainList().setMultiselect(true);
$('#eSetMultiselect1').plainList().setMultiselect(false);