// =================================================================== // Author: Matt Kruse // WWW: http://www.mattkruse.com/ // // NOTICE: You may use this code for any purpose, commercial or // private, without any further permission from the author. You may // remove this notice from your final code if you wish, however it is // appreciated by the author if at least my web site address is kept. // // You may *NOT* re-distribute this code in any way except through its // use. That means, you can include it in your product, or your web // site, or any other form where the code is actually being used. You // may not put the plain javascript up on your site for download or // include it in your javascript libraries for download. // If you wish to share this code with others, please just point them // to the URL instead. // Please DO NOT link directly to my .js files from your site. Copy // the files to your server and use them there. Thank you. // =================================================================== // HISTORY // ------------------------------------------------------------------ // Feb 15, 2005: Documentation Fix // March 31, 2004: First release /* DESCRIPTION: This library allows you to easily create select boxes whose contents depend on the value in a parent select box. It supports default options, preselected options, single or multiple-select lists, multiple form fields referencing the same list structure, form resetting, and most importantly, it's backwards-compatible way back to Netscape 4! COMPATABILITY: Netscape 4+, IE, Opera >5 (O5 didn't support new Option()), and should work on all other newer browsers. USAGE: // Create a new object, passing in the fields that make up the dynamic set // of lists. var dol = new DynamicOptionList("Field1","Child1","Child2"); // Or, you can create it empty, and pass in sets of select objects later var dol = new DynamicOptionList(); dol.addDependentFields("Field1","Child1","Child2"); // Once you have the list object defined, you can additional sets of dependent // fields, too. These sets will act as separate groups of related fields, but // will all use the same options and data. dol.addDependentOptions("Field1","Child2-1","Child2-2"); // 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); // 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 dislplay // text, you can do that dol.forValue("Value1").addOptionsTextValue("Text2","Value2"); // 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. 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; // MODIFYING THE HTML // If you are supporting Netscape 4.x browsers, you will need to insert a call to // the library to populate options. This is because Netscape4 will not expand the // size of the select box as new options are added, so you have to "pad" the list // with blank options in order for it to work right. // This is the ONLY change you should need to make to your HTML. To do this, just // add a javascript block between your tags like this: // You only need to pass it the name of the select options that it should print // options for. 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,