Logo
doctype [?]
[strict] [loose] [none]

Dynamic Option Lists / Dependent Selects


Including The Script

To use any of the functionality of this library, you first need to include the source file in your HTML page and call the init method to setup the code when the page loads.

Include the source file in your page
<script type="text/javascript" src="dynamicoptionlist.js"></script>
Call the initDynamicOptionLists function in your body's onLoad tag
<body onLoad="initDynamicOptionLists()">

Creating The Object

To create the DynamicOptionList object, pass the names of the fields that are dependent on each other, with the parent field first.

Create the object by passing field names
var dol = new DynamicOptionList("Field1","Child1","Child2");
Or create an empty object and then pass the field names
var dol = new DynamicOptionList();
dol.addDependentFields("Field1","Child1","Child2");

Adding Dependent Field Sets

Sometimes you may have multiple sets of fields which all share the same parent/child relationship and data. You can assign multiple sets of inputs which function off the same object, so the parent/child data doesn't need to be repeated for each set of parent/child fields.

dol.addDependentOptions("Field1","Child2-1","Child2-2");

Referencing The Form

By default, the script will automatically find the form where your select objects exist. But you can explicitly set it if you wish, either by form name or index.

dol.setFormName("MyForm");
dol.setFormIndex(1);

Defining Options

Now define the options that will exist in sub-lists. This is done in a very logical way - you say for an option in the parent, populate the child with specific options. When selecting which parent option you're dealing with, you can either select by its value or its display text. This command says, for an option in the parent list that has value="Value1", if it is selected then populate the child list with the given sub-options.

dol.forValue("Value1").addOptions("Suboption1","Suboption2","Suboption3");

And you can also say, for an option in the parent list that has display text of "Text1", if it is selected then populate the child list with the/ given sub-options.

dol.forText("Text1").addOptions("Suboption1","Suboption2","Suboption3");

For multi-level lists, you just continue the chain... This says, if an option with value "Value1" is selected in the first list, then an option with values "Value2" is selected in the second list, populate the third list with these options.

dol.forValue("Value1").forValue("Value2").addOptions("1","2","3");

If the options you want to add should have different values and display text, you can do that to.

dol.forValue("Value1").addOptionsTextValue("Text2","Value2");

Setting Other Options

When an option is selected from the first list, and the options in the second list are populated, you may want to have one of the options in the child list be selected by default. This doesn't define what value will be shown in the second list when the page loads, but rather which one will be selected when a given parent option is chosen.

dol.forValue("Value1").setDefaultOptions("MyValue");

When the page first loads, you may set the values of the dependent select lists to be selected by default. For example, when a user is editing an existing record where they've already selected from the parent/child relationships. This is different from the default option in that this value is only selected when the page loads. If the user changes selections, this will be lost.

dol.forField("Field1").setValues("MyPreselectedValue");

By default, if there are is no option which should be selected in the child list, the code will automatically select the first option in the list. If you want it to instead set selectedIndex = -1 (nothing selected - works in most browsers but not all) than you can tell it to do that instead.

dol.selectFirstOption = false;

Notes

  • There seems to be an issue with Netscape6, if you hit Reload on the page. It doesn't happen every time, and I can't figure out why it happens at all.
  • If your select objects have onChange handlers in them, you'll need to manually add a call to the DynamicOptionList code to trigger the population of the child list. For example:
    <select onChange="yourfunction(); dol.change(this)">