<CF_TwoSelectsRelated>

11/98-The "Evaluate is not FirstGroup" error that some people were reporting has been fixed.
2/00 - Added DEFAULT1 and DEFAULT2 parameters.
8/00 - Added escaping for quote marks and other "funny" characters in data.
8/00 - The value of each option is now provided in its JavaScript constructor, which should improve peformance a bit.
8/00 - Added EXTRAOPTIONS2 parameter.

Parameters - All optional except where noted.
NOTE: Most of the parameters are in pairs (for instance, the pair NAME1 and NAME2). The first parameter affects the first SELECT list, and the "2" parameter affects the second SELECT list.

QUERY	Required. The name of the query from which the SELECT elements will be populated. The query is probably generated by a CFQUERY tag, but could also be generated by other Cold Fusion tags that return query result sets.
NAME1, NAME2	The names of the two SELECT list elements to be included on the form. The SELECT element with NAME1 will appear first on the page, and the one with NAME2 will be second. For instance, if you use NAME2="Selection", then whatever the user chooses in the second SELECT will be available to for your use as #Form.Selection# in the next template. If omitted, NAME1 will be TwoSelectsRelated1 and NAME2 will be TwoSelectsRelated2.
DISPLAY1, DISPLAY2	Required. The columns in QUERY that will populate the SELECT elements. This is what the user sees on the page.
VALUE1, VALUE2	The columns in QUERY that provide the values for the second SELECT element when submitted. If omitted, the column you supply for DISPLAY is used. Provide this parameter if, for instance, you wanted a category "code" to be submitted to the next Cold Fusion template, but want the user to be able to choose the category by its friendly DISPLAY name. It is critical that the query's results be sorted by the column you specify for VALUE1. To put it another way, all the rows that have a given value in this column must be together in the result set. So, if for example you specify DISPLAY1="Master_Cat" for this tag, you must have ORDER BY Master_Cat in the CFQUERY you specified in QUERY. (If you find this confusing, see the CF Documentation that explains the GROUP parameter of the CFOUTPUT tag--the theory is the same.)
DEFAULT1, DEFAULT2	Default values for the two SELECT elements. If you provide a value for DEFAULT1, then the first SELECT element will appear with corresponding element pre-selected.  More practically, if you provide values for DEFAULT1 and DEFAULT2, both SELECTs will appear pre-selected with the correct seelctions.  Note that the decision to preselect an item is based on its value, not on what it displays (that is, the DEFAULT1 value is compared against VALUE1, not DISPLAY1).  Generally used in the "edit" page of a database app, where you want to show the values that are currently in the database, allowing the user to change them if they want.  Similar conceptually to the DEFAULT attribute of ColdFusion's own CFSELECT tag; see your CFML reference for details. Don't provide DEFAULT2 without providing DEFAULT1; it just doesn't make any conceptual sense.
SIZE1, SIZE2	Just like the SIZE attribute of a normal SELECT form element. If omitted, the default is 1, which makes the SELECT appear as a "drop-down list". Instead of supplying a number, you can also supply the word "Auto". If SIZE1="Auto", the first select will be the same size as the number of options it has (no scrollbars). If SIZE2= "Auto", the second select will be the same size as the first select.< /P>< /P>
WIDTH1, WIDTH2	The width of the SELECT element, using CSS measurement syntax. For instance, WIDTH1="150px" would make the first SELECT be 150 pixels wide. As of this writing, IE4 is the only browser that "obeys" this width.
FORCEWIDTH, FORCEWIDTH2	For browsers that don't obey WIDTH, you can use FORCEWIDTH to control the width of the SELECT boxes, although with somewhat less precision. Each SELECT element will have an "empty" OPTION at the bottom... the number you supply for FORCEWIDTH causes the "display text" of this last OPTION to be "padded" with nonbreakingspace characters. So FORCEWIDTH="30" causes the SELECT to be at least 30 spaces wide... how wide that actually is depends on the font the browser uses to display the SELECT. Also, if any of the items in DISPLAY are "wider" than SIZE number of spaces, then the SELECT will be that wide instead.
FORCEWIDTHCHAR	If you want to use some other character than nonbreaking spaces for FORCEWIDTH (above), specify that character here.SoFORCEWIDTHCHAR="=" would cause the last OPTION in the SELECT to be "padded" with 30 = signs instead of 30 spaces, etc.
EMPTYTEXT1, EMPTYTEXT2	If you want to force the user to make a choice from one of the SELECT elements, provide a short message here. The text you supply will appear as the first choice in the corresponding SELECT element. For instance, you might use EMPTYTEXT1="(choose a category)" so that the user will be compelled to click on something to proceed.
EXTRAOPTIONS2	Optional. If not provided, EXTRAOPTIONS2 defaults to 5 if SIZE2 is 1 and EMTPYTEXT1 is provided. Otherwise it defaults to 0. These defaults should provide the expected behavior for the majority of circumstances. In Netscape browsers (pre-6.0), if your data or use of the EMPTYTEXT parameters is such that the second SELECT box only has one item in it when the page, you could find that the second SELECT behaves strangely. You'd get little tiny scroll bars instead of the drop-down list you expect. This is because Netscape can't change the number of OPTIONS displayed in a drop-down at "run-time". This option is kind of a "poor man's" fix for this problem... you can supply a number for EXTRAOPTIONS2, which will cause that number of "blank" options to be added to the second SELECT box when the page is first drawn. The idea is that those options will be re-used by Netscape for the display of items when you choose items from the first SELECT box. Note that this will have no discernable effect in Microsoft browsers; it also has no effect if SIZE2 is not 1. Also note that there is no EXTRAOPTIONS1 parameter.
MESSAGE1, MESSAGE2	You can demand that the user pick an item from a SELECT box before proceeding. If they do not pick an item, they cannot submit the form. Also, if the item they choose has no value (if the value you supplied for the VALUE parameter is blank or null), they cannot submit the form. This means that the extra item generated by the EMPTYTEXT or FORCEWIDTH choices do not "count" as a choice. To make input be required, add a javascript onSubmit handler to the FORM tag that this tag is in. The syntax is onSubmit="return require_Name1()" (where Name1 is whatever you supplied for NAME1 in this tag). See example below. To make both boxes be required, use onSubmit="return require_Name1AndName2()". If you want a custom message to appear to the user when they are not allowed to proceed, provide that text here as MESSAGE1 or MESSAGE2. Otherwise, a default message will be used.
HTMLBETWEEN	Insert any HTML code that you want to be output between the two SELECT elements (for instance, a <BR> tag to put a line break between them). If omitted, the second select will appear directly to the right of the first.
ONCHANGE	You can put any Javascript code that want to execute when the user makes a selection from the second SELECT in here... it will be passed directly through to the onChange handler of the second SELECT tag itself. For instance, ONCHANGE="alert('You picked '+this.options[this.options.selectedIndex].text)" would display a dialog box to the user when they made their selection. Keep in mind that this is Javascript code you're providing here, which means that it's case-sensitive. There are two "magic" values that you can supply for ONCHANGE as "shortcuts" to writing this kind of javascript code yourself: ONCHANGE="Submit!" will cause the form to be submitted automatically when the user makes a selection. Use this when you don't want to make the user click a Submit button to submit the form. ONCHANGE= "Jump!"will cause the current window's URL to change to the value of the second select item. When you use this, it's assumed that the column you specified for VALUE2 has URLs in it, otherwise you will most likely get a "Not Found" type of error in your browser.< /LI>< /LI>
AUTOSELECTFIRST	YES or NO (default is YES). If YES, then when the user selects an item from the first SELECT, the first item of the second SELECT is selected automatically. In general, you will want to use AUTOSELECTFIRST="YES" when SIZE="1" and NO when SIZE is greater than 1. Try it out... it's easier to see than to explain.
FORMNAME	The name (as specified in the NAME parameter of the FORM tag) of the form that this CF_TwoSelectsRelated tag is in. If omitted, defaults to FORMNAME="forms[0]", which will be fine unless there is another form on the same page above the current form. Note that form names are case-sensitive as far as javascript is concerned, so if you supply this parameter, make sure that the capitalization matches the FORM's NAME parameter exactly, or else all sorts of javascript errors will occur.

Example 1

Example 2