Chained Selects Step-by-step: Define the list group

yxScripts.com

To implement Chained Selects, we usually:

  1. define the content of 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 definition of list group 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

A list group is like a folder tree. Imagine that we want to "chain" three select lists and we 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, 'option-label')

    • 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 is optional and can be ignored. If supplied, it can be any value except those considered as false in JS such as "", null and 0 (1 would be handy).

    The 'option-label' parameter is optional, but if given, the default-selected parameter should also be provided (use 0 if it's not a default option).

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

    • 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 is optional and can be ignored. If supplied, it can be any value that is not false.

    The 'option-label' parameter is optional.

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)

For example if we have the following content for a list group:

  • Toyota
    • Car
      • Avalon
      • Camry
      • Celica
      • Corolla
    • SUVs/Van
      • 4Runner
      • Highlander
      • Land Cruiser
      • Sienna
    • Trucks
      • Tacoma
      • Tundra
  • Honda
    • Car
      • Accord
      • Civic
      • S2000
    • SUVs/Van
      • CR-V
      • Pilot
      • Odyssey
  • Chrysler
    • Car
      • PT Cruiser
      • Sebring
    • SUVs/Van
      • Town & Country
      • Voyager

This is a list group with three levels: the vehicle makers, the vehicle types and the vehicle models, which we can map to three select lists.

So we can define the first level as:

// define a list group
addListGroup("vehicles", "makers");

// and its top list
addList("makers", "Toyota", "Toyota", "toyota-list");
addList("makers", "Honda", "Honda", "honda-list");
addList("makers", "Chrysler", "Chrysler", "chrysler-list");

which means we have a list group named as "vehicles" and it has a top level list named as "makers", which has three options: "Toyota", "Honda" and "Chrysler", and each of these options has a sub-list which is named as "toyota-list", "honda-list" and "chrysler-list" respectively.

Now we can define the second level lists one by one:

// sub-list for toyora
addList("toyota-list", "Car", "Car", "toyota-car");
addList("toyota-list", "SUVs/Van", "SUVs/Van", "toyota-suv/van");
addList("toyota-list", "Trucks", "Trucks", "toyota-truck");

// sub-list for honda
addList("honda-list", "Car", "Car", "honda-car");
addList("honda-list", "SUVs/Van", "SUVs/Van", "honda-suv/van");

// sub-list for chrysler
addList("chrysler-list", "Car", "Car", "chrysler-car");
addList("chrysler-list", "SUVs/Van", "SUVs/Van", "chrysler-suv/van");

Since we have some third level lists of vehicle models under the second level lists of vehicle types, we are still using addList() here for the options in these lists.

Finally we have the third level lists as below:

// sub-list for toyota car
addOption("toyota-car", "Avalon", "Avalon");
addOption("toyota-car", "Camry", "Camry");
addOption("toyota-car", "Celica", "Celica");
addOption("toyota-car", "Corolla", "Corolla");

// sub-list for toyota suv/van
addOption("toyota-suv/van", "4Runner", "4Runner");
addOption("toyota-suv/van", "Highlander", "Highlander");
addOption("toyota-suv/van", "Land Cruiser", "Land Cruiser");
addOption("toyota-suv/van", "Sienna", "Sienna");

// sub-list for toyota truck
addOption("toyota-truck", "Tacoma", "Tacoma");
addOption("toyota-truck", "Tundra", "Tundra");

// sub-list for honda car
addOption("honda-car", "Accord", "Accord");
addOption("honda-car", "Civic", "Civic");
addOption("honda-car", "S2000", "S2000");

// sub-list for honda suv/van
addOption("honda-suv/van", "CR-V", "CR-V");
addOption("honda-suv/van", "Pilot", "Pilot");
addOption("honda-suv/van", "Odyssey", "Odyssey");

// sub-list for chrysler car
addOption("chrysler-car", "PT Cruiser", "PT Cruiser");
addOption("chrysler-car", "Sebring", "Sebring");

// sub-list for chrysler suv/van
addOption("chrysler-suv/van", "Town & Country", "Town & Country");
addOption("chrysler-suv/van", "Voyager", "Voyager");

The "addOption()" is used here as the options in third level lists have no sub-lists.

And you might have noticed, the first parameter in "addList()" and "addOption()" calls refer to some "list-name"s, the "addList()" calls also have a fourth parameter for the name of a sub-list. These names should be unique and they are used to link an option in a "parent" list to the options in a "child" list.


If we can work out the UL/LI structure of the list content, we can use the parser (parser.html) that comes with the CS package to generate the list content for us, just replace the UL/LI part in the parser.html with the one we need and we can generate something like below:

addListGroup("demo", "cs-top");

addList("cs-top", "Toyota", "Toyota", "cs-sub-1");
addList("cs-top", "Honda", "Honda", "cs-sub-5");
addList("cs-top", "Chrysler", "Chrysler", "cs-sub-8");

addList("cs-sub-1", "Car", "Car", "cs-sub-2");
addList("cs-sub-1", "SUVs/Van", "SUVs/Van", "cs-sub-3");
addList("cs-sub-1", "Trucks", "Trucks", "cs-sub-4");

addOption("cs-sub-2", "Avalon", "Avalon");
addOption("cs-sub-2", "Camry", "Camry");
addOption("cs-sub-2", "Celica", "Celica");
addOption("cs-sub-2", "Corolla", "Corolla");

addOption("cs-sub-3", "4Runner", "4Runner");
addOption("cs-sub-3", "Highlander", "Highlander");
addOption("cs-sub-3", "Land Cruiser", "Land Cruiser");
addOption("cs-sub-3", "Sienna", "Sienna");

addOption("cs-sub-4", "Tacoma", "Tacoma");
addOption("cs-sub-4", "Tundra", "Tundra");

addList("cs-sub-5", "Car", "Car", "cs-sub-6");
addList("cs-sub-5", "SUVs/Van", "SUVs/Van", "cs-sub-7");

addOption("cs-sub-6", "Accord", "Accord");
addOption("cs-sub-6", "Civic", "Civic");
addOption("cs-sub-6", "S2000", "S2000");

addOption("cs-sub-7", "CR-V", "CR-V");
addOption("cs-sub-7", "Pilot", "Pilot");
addOption("cs-sub-7", "Odyssey", "Odyssey");

addList("cs-sub-8", "Car", "Car", "cs-sub-9");
addList("cs-sub-8", "SUVs/Van", "SUVs/Van", "cs-sub-10");

addOption("cs-sub-9", "PT Cruiser", "PT Cruiser");
addOption("cs-sub-9", "Sebring", "Sebring");

addOption("cs-sub-10", "Town & Country", "Town & Country");
addOption("cs-sub-10", "Voyager", "Voyager");

Of course, the names of the list/sub-lists are no longer very meaningful.


We could specify more than one default option in a list. If such a list is mapping to a single-choice form select list, only the last default option will be taken. If the list is mapping to a multiple-choice form select list, all the default options will be selected.

So if we want the "Honda" as the default selected option in the first level list, we could have:

...
addList("makers", "Toyota", "Toyota", "toyota-list");
addList("makers", "Honda", "Honda", "honda-list", 1); // make it default option
addList("makers", "Chrysler", "Chrysler", "chrysler-list");
...

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

[ Implement the list group ] [ Back to main page ]

# # #