Chained Selects

Copyright 2004    Xin Yang

Select a vehicle: 

Chained Selects lets you "chain" multiple form select lists together so that the selection in a "parent" list can tailor the options available in a "child" list.

Chained Selects supports unlimited number of form select lists in a "chain", as well as unlimited number of "chains" in a page. A selection list persistent feature is also available, through session only cookies.

To implement Chained Selects, you will need to:

  1. define the structure of your select options, which would be referred to as a list group
  2. include the Chained Selects function script (chainedselects.js) in the page
  3. embed the definitions of list groups in the page, or include it if put in a JS file
  4. set up the form select lists as usual (or just set up some empty select lists)
  5. bind the form select lists to a list group when the page is loaded

Installation:

To install Chained Selects, refer to the "Example" or "Example2" folders within the zip file. Each folder holds a fully self contained example of Chained Selects, from the HTML required to put on your page, to the two .js files that also need to be uploaded. Study the "config .js" file to customize the list contents.

Included within the zip file is also parser.html. You may run this file offline to help generate the HTML for your menu links, to then be inserted in config.js. However, this is completely up to you.

Documentation:

A list group is like a folder tree. Imagine that you want to "chain" three select lists and you would prepare options for them. It's just like mapping a three-level folder tree to three select lists, the folders/items at top-level will populate the first select list, and when a top-level folder is selected, its sub-folders/sub-items will populate the second select list, and same goes for the third select list.

To define a list group, Chained Selects introduces the following function calls:

  • addListGroup("list-group-name", "first-list-name")

    • The "first-list-name" is like the root of the folder tree, and the "list-group-name" will be referred to later when we are to bind form select lists to this list group.

  • addList("first-list-name", "option text", "option value", "sub-list-name", default-selected)

    • This is like adding a top-level folder to the folder tree. This option will populate the first select list binded to the list group.

    The "default-selected" parameter can be ignored. If supplied, it can be any value (1 would be handy).

  • addOption("first-list-name", "option text", "option value", default-selected)

    • This is like adding a top-level item to the folder tree. This option will populate the first select list binded to the list group.

    The "default-selected" parameter can be ignored. If supplied, it can be any value.

The "addList()" and "addOption()" will be re-used to define options for the second select list and the rest of select lists:

  • addList("sub-list-name", "option text", "option value", "nested-sub-list-name", default-selected)
  • addOption("sub-list-name", "option text", "option value", default-selected)

As you might notice, the first parameter in "addList()" and "addOption()" calls refer to some "list-name"s, the "addList()" calls also have a fourth parameter for names of nested sub-lists. These names should be unique.

When you finish the definition of a list group, you can define another with the "addListGroup()" call again, followed by a bunch of "addList()" calls and "addOption()" calls.

For any list (identified by a "list-name") in a list group, we could specify at most one item (could be a sub-list or an option in this list) with "default-selected" (if more than one item given the "default-selected" parameter, the last one will be taken), so that when this list is used to populate a form select list, the specified item will be selected by default.


Once you have a list group, you can bind form select lists to it and populate the select lists with options defined in the list group. To do so, you can have:

  • <body onload="initListGroup('list-group-name', select-list-1, select-list-2, ..., 'cookie_name')">

The 'cookie_name' parameter is optional, if provided, will be used as the name prefix of the cookies to store the last selections and resume them for re-visits within the same browser session.

If you implement a list group into more than one page with the same 'cookie_name' parameter, those pages can share the last selections within the same browser session. If different 'cookie_name' parameters are used, each page will be able to have its own copy of last selections.

If you have more than one list group in a single page, you should have different 'cookie_name' parameters for each list group.

If you want to re-use a list group for different sets of select lists in a single page, you can do so like this:

  • <body onload="initListGroup('MyList', select-list-1, select-list-2, 'cookie-A'); initListGroup('MyList', select-list-3, select-list-4, 'cookie-B')">

Usually the number of select lists should be equal to the number of maximum nested levels in a list group. For a selection that doesn't have sub-options for its "child" select list, its "child" select list and all the "grand-child" select lists will be emptied.

When a select list is emptied, you can choose to just leave it there, to disable it or to hide it.

To disable empty lists, you can embed the following line before the include line of the function script:

  • var disable_empty_list=true;

    • a disabled list will be enabled when there are some options to pupolate it.


To hide empty lists, you can embed the following line before the include line of the function script:

  • var hide_empty_list=true;

    • a hidden list will become visible when there are some options to pupolate it.

# Update History:

  • added the ability to re-use a list group ... 2004-08-23.
  • fixed a bug in sub-list sharing ... 2004-08-13.
  • added the "cookie_name" parameter ... 2004-07-17.
  • added the "default-selected" parameter ... 2004-06-18.
  • first release ... 2004-04-28.