One of my major sites that I work with is a purely data driven site where all the text, page layout and editable HTML content is customisable and driven from settings within a database. On a number of sites that use this product a number of the controls are list boxes that are all linked together in a hierarchal chain where the selected value(s) of one list will determine the available options in another. A good example is a chain of locations such as Country, Region and Town. When you select England from the Country list the Region list is populated with the various options within that country. There are various ways you can acomplish doing this including:

• Submitting the page on each list item selection. Gathering the data from the server and then reloading the page showing the appropriate options in the subsequent list.
• Populating client side arrays with all possible values for each list in the chain when the page first loads. Then when selections are made a function call will do lookups within the various arrays and populate the list accordingly.
• Use AJAX so that when a selection is made on one list the data for the subsequent list is gathered behind the scenes and a callback function populates the subsequent list.

Each option has its own merits but I use the last option because its user friendly and fast. I recently had to rewrite the way I handled these linked lists and a demo of the Javascript object is on this page. The features and functionality that the object supports is listed below:

1. No limit on the number of lists linked together in a chain.
2. Handle multiple groups of linked lists on one page.
3. Ability to customise per list the wording for default options such as "Please Select", "Any", "No Records".
4. On loading a list any options that were previously selected must be re-selected e.g saved options.
5. An option that on first loading a page populates a child list with all possible options even though nothing in the parent list maybe selected.

Linked List Demonstration

The example form below shows the linked list object working running 2 groups of linked lists together with each group containing 3 lists Country > Region > Town / City. I have also outputted my debug code into a div at the bottom of the page as its always helpful to see whats going on as you play about with an example.

To get the linked list code working on your site is pretty simple if you follow these steps:

• Download the Javascript source code and install it on your site. The file contains a number of helper functions that add and remove events and handle AJAX calls so you may want to remove those and use your own. The code also makes use of my Browser Object.
• Add your listbox controls to your HTML source code. The top most list that is the parent of all the other lists in that chain will be populated when the page renders however the other lists will be getting populated through the object and you just need to define the select e.g
  

  
  <select name="lstRegion" id="lstRegion" size="3" multiple="multiple">
  <option value="">Select a Country</option>
  </select>
  

• You will need a server side script (ASP, .NET, PHP) to handle the AJAX request that the Javascript object makes when a lists onChange event fires. It should accept multiple values from the parent and return a dataset containing the child options. My example uses a basic string format of:
  INPUT: cat=value1&value2&value3 e.g cat=1&2&3
  OUTPUT: ID|DESC e.g 1|London (records are seperated by a newline character \n)
  You can change this code to use JSON or another data format but I have kept it simple as the demo is not about AJAX.
• For each listbox that needs to participate in the linked list object you should use the following Javascript that references the linked list object.

			
// Set up a linked list group containing 3 lists
// Params for AddList(page, name, childName, isTop, isRequired, popAllChild, selItems, AnyOption, AnyValue, NoRecords, PleaseSelect);
ListGroup.AddList('set1', 'lstCountry_1', 'lstRegion_1', true, false, true, '', 'Any Country', '', 'No Records','');
ListGroup.AddList('set1', 'lstRegion_1', 'lstTown_1', false, false, true, '', 'Any Region','', 'No Records', 'Select Country');
ListGroup.AddList('set1', 'lstTown_1', '', false, false, false, '','Any Town', '', 'No Records', 'Select Region');

And thats it. The ListGroup object will create all necessary listeners to handle the onChange events and make sure that when the page is loaded the top list fires its change event which will in turn populate all its children. The possible parameters which modify the lists behaviour are outlined below:

• Page: The name of the page/include file you are creating the group on. Helps identify the groups in case multiple sets appear on the same page.
• Name: The id of the listbox you want to link.
• ChildName: If the selected options within this list determine the available options within another list then you need to specify the id of the list that should be re-populated when the onChange event fires on this list.
• isTop: Indicates whether this list is the initial parent at the top of a linked list chain.
• isRequired: If the list is a required field then the user must select one or more options. There will be no "Any" option and the top option will contain the wording supplied for the PleaseSelect option. If the list is not required then the top option will contain the value set in AnyValue and the wording set in AnyOption.
• popAllChild: If set to true and the list has a related child list then when the page first loads the child list will be automatically populated with all possible options as if its parent has had all its options selected.
• selItems: A comma delmited string of values that need to be selected when the list gets populated.
• AnyOption: When the list is not required the text set for this value will appear in the first option of the listbox.
• AnyValue: When the list is not required the value for the first option of the listbox.
• NoRecords: The text that should appear in a child list if its parent has selected options but none are available in the child related to those values.
• PleaseSelect: When the list is a required field this is the text that appears as the top option to get the user to pick a valid option.

Post Comments

As this script is not part of the blog if you would like to post comments please click this link and then respond to the following article.