JQuery Plugin: imList

imList is a JQuery plugin that began as a way to “Ajaxally” (Adjective: Meaning to post or retrieve information without having to refresh the page) create html tables using JQuery. After creating the table plugin, I realized that I could apply much of the same functionality to any type of list that is displayed on a web page, to include: ul/ol, comboboxes, lists, and divs. The power of this plugin is it’s regular expression functionality that will allow developers to display anything they wish within a list. I have also built in a delete row capability that can, not only delete the row that is displayed on the web page, but also allow the developer to delete the record from the server (ajaxally, of course).

$("#memNotify").imList({
	display: {"type": "table"},
	header_cols: [{"caption": "Area", "width" : "80%", "align": "center"}, {"name": "Delete", "width" : "20%", "align": "center"}],
	data_url: '../includes/controllers/dbActionController.php',
	width: '80%',
	data: [{name: "action", value: "doGetJson"}, {name: "page", value: "member_notify"}, {name: "subset", value: "true"}, {name: "lookup", value: "states"}, {name: "member_id", value: memId} ],
	db_map: [{"type": "db", "value": "city, state_abbrev", "separator": ", "},
			{"type": "text", "value": "Delete", "func": "doDeleteRow", "url": "../includes/controllers/dbActionController.php", "params" :
		  			[{"name": "action", "value": "doDelete"},
					{"name": "page", "value": "member_notify"},
					{"name": "member_notify_id", "value": "member_notify_id", "fromDB": "true"}
				]}]
});

The Container

In the example above, “memNotify” is the container. The container can optionally have a width. In the example above, the width is set to 80%. The default for the “width” option is 100%.

Display Options

The display option let’s the imList plugin know which type of list your want to display. The options are ‘table’, ‘div’, ‘ol’, ‘ul’, ‘select’, or ‘self’. Display has other options as well:

display: {"type": "div", "name": "catSelect", "id": "catSelect", "class_name": ""}

name: The name of the container.
id: The id of the container.
class_name: The class name of the container.

display.type = ‘select’

Use type = select to create a dropdown box. You can create a list instead of a dropdown box by adding the “multiple” option when using a display type of “select”:

display: {"type": "select", "name": "catSelect", "id": "catSelect", "class_name": "", “multiple”: true}

display.type = ‘self’

When using display type = “self”, the “class_name” option must be provided. The “self” option will create multiple divs inside the parent container. In the example invocation of the plugin above, “memNotify” is the parent container. For an example of using the ‘self’ option, see the imList plugin examples in the demo section.

display: {"type": "self", "name": "", "id": "", "class_name": "resultRow"}

display.type = ‘ol/ul’

When using display type = ‘ol’ or ‘ul’, you can also add a class to style the li’s

display: {"type": "ul", "name": "", "id": "", "class_name": "", “li_class”: “className”}

Header Options

Header_cols

I created the ‘header_cols’ option for use with tables (column headings), but the plugin also accepts this option for ol/ul and div lists as well. For tables, the plugin creates tags; For ol/ul and divs, the plugin creates an tag (so you can style them accordingly).

header_cols: [{"caption": "Area", "width" : "80%", "align": "center"}, {"caption": "Delete", "width" : "20%", "align": "center"}]

caption: The text that is displayed.
width: The width of the column. Used with tables only.
align: The alignment (“left”, “right”, “center”). Used with tables only.

Header Class

The “header_class” option can be used with tables (th), divs (h3), and ol/ul (h3). I created this option as an additional way to style the header.

Stripe Class

The “stripe_class” option can be used with tables. It enables you to alternate the color of the table rows. It takes the form:

stripe_class: {odd: “class name”, even: “class name”}

When using this option, you do not have to set both the odd and even.

stripe_class: {odd: “class name”}

Getting the Data

To retrieve the data for the list use the following options:

data_url: The URL where you will retrieve the address
data: Any data that you want to send to the data_url. The format for this option should be:

[{name: "name1", value: "value1"}, {name: "name2", value: "value2"}, etc. ]

The options will be converted into name=value pairs and sent to the data_url.

The Data Map

The plugin uses the db_map option to map the data that comes back from the server. The data returned from the server must be a Json object.

[{"member_id": "1", "first_name": "Jack", "last_name": "O\'neal", "address": "225 Cheyenne Mountain", "city": "Colorado Springs", "state_abbrev": "CO"},
 {"member_id": "2", "first_name": "Samantha", "last_name": "Carter", "address": "226 Cheyenne Mountain", "city": "Colorado Springs", "state_abbrev": "CO"},
 {"member_id": "3", "first_name": "Daniel", "last_name": "Jackson", "address": "227 Cheyenne Mountain", "city": "Colorado Springs", "state_abbrev": "CO"},
 {"member_id": "4", "first_name": "Teal\'c", "last_name": "of Chulak", "address": "228 Cheyenne Mountain", "city": "Colorado Springs", "state_abbrev": "CO"},
 {"member_id": "5", "first_name": "General", "last_name": "Hammond", "address": "229 Cheyenne Mountain", "city": "Colorado Springs", "state_abbrev": "CO"}]

type: The type of field to display. The options are:

• db: Displays a database field as returned from the server
• text: Displays whatever text is entered in the “value” option
• regex: Uses Regular Expressions to display the value. More on this later.

value: The value of the field to display. If type = “db”, then it is the name of field in the Json object. If you want to combine multiple fields (display together in one column), list each field separated by a comma (no space after each comma) and use the “separator” option to let the plugin know how to display the column. In the example below, I want to display the city and state abbreviation in a column. The values will be displayed separated by a comma (city, state).

[{"type": "db", "value": "city, state_abbrev", "separator": ", "}

func: Use the ‘func’ option to call a function when the value is clicked. The plugin has a built-in function, “doDeleteRow” that can be used when the display type is “table”. You should provide the url and any parameters that you want to send to the server. In the example below, each row in the table has column with the text “Delete”. This text is hyperlinked with an onClick attribute.

{"type": "text", "value": "Delete", "func": "doDeleteRow", "url": "../includes/controllers/dbActionController.php", "params" :
				  			                            [{"name": "action", "value": "doDelete"},
							                          {"name": "page", "value": "member_notify"},
						 {"name": "member_notify_id", "value": "member_notify_id", "fromDB": "true"}]
}

If any of the values that you want to send to the server is a field in the data (Json object) that was retrieved (see data_url), then you must provide the name of the field and the “fromDB” option.

{"name": "member_notify_id", "value": "member_notify_id", "fromDB": "true"}

As I stated above, the “doDeleteRow” is the only built-in function, but you can use the ‘func’ option to call any function that you create. Just remember to supply the parameters for the function.

url: The ‘url’ option can be used without the “func” option. Again, a hyperlink is created, so when a user clicks on the link, they can be sent to whatever url is supplied.

display.type = ‘select’

When creating a dropdown box, the db_map is formatted a bit differently.

db_map: {"type": "db", "value": "member_id", "label": "name"}

The “value” is the option value and label is what is actually displayed in the dropdown.

Regular Expressions

If you create a list where type = “regex”, you have much more flexibility in what is displayed. The plugin will display everything that is displayed within the “value” option. If you want to display database fields that are contained in the Json object that is retrieved from the server, you must enclose the values in the <im></im> tags.

$("#"+div).imList({
	display: {"type": "div", "name": "catSelect", "id": "catSelect", "class_name": ""},
	header_cols: [{"caption": cap, "width": "100%", "align": "left"}],
	header_class: 'caption',
	data_url: 'includes/controllers/dbActionController.php',
	width: '80%',
	data: [{name: "action", value: "doGroupCount"}, {name: "page", value: pg}, {name: "tType", value: tType} ],
	db_map: [{"type" : "regex", "value": "<input type='checkbox' name='chbc_category_id' value='category_id' onclick='getChecked()' />cat_desc (count) "}]
});

In the example above, the a checkbox will be displayed in the div. The name of each checkbox (name=’chbc_category_id’) will be ‘chbc_’ + the category_id that is returned from the server (show data returned). When the checkbox is clicked, a function “getChecked” is called. ‘getChecked” is a separate function and not built into the plugin.

<imList>

If you want to create a list within a list, you can use the <imList></imList> tags. When using <imList>, the values must be a Json object. The <imList> tags must be contained within the <im></im> tags. In the example below, I want to create multiple checkboxes within a div.

//
{"type": "regex", "value": "<a href='venues/index.php?tType=1&id=<im>venue_id</im>' class_name='venueTitle'><im>venue_name</im></a><br />
<im>address1</im><im>address2</im><br /><im>city</im>, <im>state_abbrev</im> <im>zip_code</im><br /><im>tag_line</im><br />
<span class_name='resultType'><imList>{'name': 'member_music', 'db_field': 'music_desc', ‘format': [{'type': 'affix', 'name': 'suffix', 'value': ', '}]}</imList></span>",
"class_name": "resultName", "sub_map": [{"name": "member_music", "db_map": [
{"name": "member_music", "db_field": "music_desc", "form": false, "format": [{"type": "affix", "name": "suffix", "value": ", "}]}]}]}

imList Options

name: The name of the member in the Json object that is returned from the server.
db_field: The name of the field with the member.
format: Used with checkboxes. Format can have the following options:

• type: The only format type that can be used is “affix”.
• affix: When using the “affix” option, the “name” option will be either “prefix” or “suffix”. With “prefix”, the plugin will search for prefix value + db_field value. In the example above, the db_field value is “music_desc”, so the plugin will display the value of the music_desc separated by a comma and a space.

{'type': 'affix', 'name': 'suffix', 'value': ', '}

You can get the imList plugin from Google Code or JQuery Plugins. Enjoy.