JQuery Plugin: imPagePopulate

Depending upon the number of elements on a page, retrieving data from a database and populating a web page with the data can be a very tedious task. In the past, I have always used server-based technologies (PHP, Coldfusion, etc) to populate a page. After growing tired of creating the structures over and over again, I decided to create a JQuery plugin that would do the work for me. Most of the page population plugins I have seen only populate form elements. The imPagePopulate plugin will not only populate form elements, it will populate any HTML element on a page.

You use the imPagePopluate to map the data that comes from the server with the elements on the page. To use the plugin, do the following:

         data_url: '../includes/controllers/dbActionController.php',
         data: [{name: "action", value: "doGetJson"}, {name: "page", value: "members"}, {name: "member_id", value: memId} ],
         db_map: [{"name": "first_name", "db_field": "first_name", "form": true},
                        {"name": "last_name", "db_field": "last_name", "form": true},
                        {"name": "zip_code", "db_field": "zip_code", "form": true},
                        {"name": "gender", "db_field": "gender", "form": true},
                        {"name": "birth_year", "db_field": "birth_year", "form": true}],
         sub_map: [{"name": "member_music", db_map: [
                          {"name": "member_music", "db_field": "music_cat_id", "form": true, "format": [{"type": "affix", "name": "prefix", "value": "chb_"}]}]}]
         add_elements: [{"id": "frmProfile", db_map: [
                  {"name": "profile_name", "db_field": "profile_name", "form": true},
                  {"name": "address1", "db_field": "address1", "form": true},
                  {"name": "address2", "db_field": "tAddress2", "form": true},
                  {"name": "city", "db_field": "city", "form": true},
                  {"name": "state_id", "db_field": "state_id", "form": true},
                  {"name": "country_id", "db_field": "country_id", "form": true},
                  {"name": "zip_code", "db_field": "zip_code", "form": true},
                  {"name": "phone", "db_field": "phone", "form": true},
                  {"name": "website", "db_field": "website", "form": true},
                  {"name": "email", "db_field": "email", "form": true},
                  {"name": "personal_info", "db_field": "personal_info", "form": true}

‘#frmBasicInfo’: The container for the plugin is the form that you want to populate.
data_url: The URL where you will retrieve the address
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 Database Map

db_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":"8", "member_type_id":"1", "first_name":"Les", "last_name":"Green", "user_name":"lesgreen
@grasshopperpebbles.com", "address1":"441 wherever st", "address2"
:"", "city":"", "state_id":"", "phone":"", "country_id":"", "zip_code":"22123", "gender":"M", "member_dir":"lesgreengrass"
, "status":"A", "join_date":"2008-11-11 08:44:46", "mod_date":"2008-11-11 08:44:46", member_music: [
{ "music_cat_id":"1", "music_desc":"80s Music" },  { "music_cat_id":"10", "music_desc":"Rock" },  {
"music_cat_id":"14", "music_desc":"R&B" },  { "music_cat_id":"15", "music_desc":"Dance/Electronic" }]}]

The db_map uses the following format to map each element on the page:

{"name": "first_name", "db_field": "first_name", "form": true}

name: The name of the element.
db_field: The name of the database field that is returned in the Json object.
form: Tells the plugin whether the name option is a form element (input, textarea, etc). If “form” is false, the plugin will search for any HTML element with the given name.

The Sub Map

sub_map: The sub_map option is used for repeating fields such as multiple checkboxes. In the example data above (the Json object), the “member_music” field contains all the music interest that was saved by the member. The form contains a table that displays multiple checkboxes (see imCheckBoxDB).

The plugin will use the sub_map information to populate (check) all the checkboxes that pertain to the data that was saved.

sub_map: [{"name": "member_music", db_map: [
                 {"name": "member_music", "db_field": "music_cat_id", "form": true, "format": [{"type": "affix", "name": "prefix", "value": "chb_"}]}]}]

name: The name of the Json member.
db_map: The beginning of the database map for the sub_map
db_field: The name of the database field that is returned in the Json object.
form: Form element (true or false).
format: The format option can be used for the sub_map or the parent db_map. In this case, the data returned contains the id (music_cat_id) and description (music_desc) of each music category as stored in the database for each user. In the example above, the id (music_cat_id) for each category is just a number:

{ "music_cat_id":"1", "music_desc":"80s Music" },  //etc

I don’t want to name each of the checkboxes on my form with just a number, instead I will use a prefix:

<input id=”chb_1" name="chb_1" type="checkbox" value="80s Music" />
<input id=”chb_2" name="chb_2" type="checkbox" value="Jazz" />
<input id=”chb_3" name="chb_3" type="checkbox" value="Rock" />
<input id=”chb_4" name="chb_4" type="checkbox" value="Reggae" />
<input id=”chb_5" name="chb_5" type="checkbox" value="Blues" />

Keep in mind, the plugin is searching the page for the HTML elements. So in this case, I will use the format option to let the plugin know that checkboxes have a prefix of “chb_1”.

[{"type": "affix", "name": "prefix", "value": "chb_"}]

type: The type option will be 1 of 2 values, “affix” or “math”.
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_cat_id”, so the plugin will search for “chb_” + 1, “chb_” + 2, etc. The plugin will check each checkbox that is listed in the result.

math: The math option is not generally used in the sub_map. This option can be used to display calculated fields using the value of the data that is returned from the server.

{"name": "total ", "db_field": "sold", "form": true, "format": [{"type": "math", "name": "round"}]}

In the example above, the “total” field will display rounded value of the “sold” field that is returned from the database.

The following are the math options:


When using multiply, divide, add, or subtract, you must provide an additional value. This value will be used in the calculation with the field:

{"name": "total ", "db_field": "sold", "form": true, "format": [{"type": "math", "name": "multiply", "value": "20"}]}

Additional Elements

add_elements: The additional elements option is used when you have multiple forms on a page. You provide the id of the form element and the db_map for the form:

{"id": "frmProfile", db_map: [
{"name": "profile_name", "db_field": "profile_name", "form": true}, //etc.

Success Option

You also have the option of calling a function after the page has completed populating. Adding this option is simple:

success: loadComplete

The function that you call should not be enclosed with apostrophes if it is contained within JQuery’s  $(document).ready.

function pageLoaded() {
	alert('I know you are a Stargate SG-1 Fan!!');
		data_url: 'get_data.php',
		data: [{name: "action", value: "doCalc"}],
		db_map: [{"name": "first_name", "db_field": "first_name", "form": true},
				{"name": "last_name", "db_field": "last_name", "form": true},
				{"name": "address1", "db_field": "address1", "form": true},
				{"name": "address2", "db_field": "address2", "form": true},
				{"name": "city", "db_field": "city", "form": true},
				{"name": "states", "db_field": "states", "form": true},
				{"name": "zip_code", "db_field": "zip_code", "form": true},
				{"name": "home_phone", "db_field": "home_phone", "form": true},
				{"name": "email", "db_field": "email", "form": true},
				{"name": "viewed", "db_field": "dvd_sold", "form": true, "format": [{"type": "math", "name": "multiply", "value": "3"}]},
				{"name": "hobby1", "db_field": "hobby1", "form": false},
				{"name": "hobby2", "db_field": "hobby2", "form": false}],
		add_elements: [{"id": "frmTrueLove", db_map: [
				{"name": "tFirstName", "db_field": "love_first", "form": true},
				{"name": "tLastName", "db_field": "love_last", "form": true}
		//apostrophe’s needed
		success: 'pageLoaded'

The Plugin can be  downloaded from Google Code or JQuery Plugins.

Click here to view examples of using the imPagePopulate plugin.

Be Sociable, Share!

Checkout My New Site - T-shirts For Geeks