CF_ThreeSelectsRelated

Create dynamic select boxes. Contents of second and third boxes are defined by previous box selection.

SYNTAX:

<CF_ThreeSelectsRelated
      query = "GetData"
      HTMLAfter2 = "<BR>"
      Name1 = "Sel1"
      Name2 = "Sel2"
      Name3 = "Sel3"
      Value1 = "CustomerID"
      Value2 = "ID"
      Value3 = "BookID"
      Display1 = "Company"
      Display2 = "Category"
      Display3 = "Title"
      Default1 = "1"
      Size1 = "3"
      Size2 = "3"
      Size3 = "5"
      Width1 = "150"
      Width2 = "150"
      Width3 = "300"
      ForceWidth1 = "40"
      ForceWidth2 = "40"
      ForceWidth3 = "90"
      AutoSelectFirst = "No"
      Mulitple3 = "Yes">

ATTRIBUTES:

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, Name3
The names of the 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, etc. 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, etc.

Display1, Display2, Display3
Required. The columns in QUERY that will populate the SELECT elements. This is what the user sees on the page.

Value1, Value2, Value3
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, then the column you specify for VALUE2. So, if for example you specify DISPLAY1="CustomerID" and DISPLAY2="OrderID" for this tag, you must have ORDER BY CustomerID, OrderID 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, Default3
Optional. Values that determine which items in the SELECT lists are pre-selected when the web page appears. So, if VALUE1="CustomerID" and DEFAULT1="5", then first SELECT will appear with Customer 5 pre-selected.

Multiple3
Optional. Yes or No. If MULTIPLE3="YES", then the user can choose more than one item from the third SELECT list (by holding down the Ctrl key in Windows, and some other strange key on the Mac... I think it's an iconic representation of Steve Jobs' head or something).

Note that there is no MULTIPLE1 or MULTIPLE2 (this would be hard... maybe next time around).

Type1
Optional. RADIO or SELECT. If omitted, the default is SELECT. If TYPE1="RADIO", the first SELECT will be rendered as a series of Radio buttons rather than a SELECT list. In such a case, WIDTH1, SIZE1, FORCEWIDTH1, and EMPTYTEXT1 are all ignored.

Note that there is no TYPE2 or TYPE3.

Size1, Size2, Size3
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.

SIZE1 has no effect if TYPE1="RADIO".

Width1, Width2, Width3
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.

WIDTH1 has no effect if TYPE1="RADIO".

ForceWidth1, ForceWidth2, ForceWidth3
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.

FORCEWIDTH1 has no effect if TYPE1="RADIO".

ForceWidthChar
If you want to use some other character than nonbreaking spaces for FORCEWIDTH (above), specify that character here. So FORCEWIDTHCHAR="=" would cause the last OPTION in the SELECT to be "padded" with 30 = signs instead of 30 spaces, etc.

EmptyText1, EmptyText2, EmptyText3
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.

EMPTYTEXT1 has no effect if TYPE1="RADIO".

ExtraOptions2, ExtraOptions3
Netscape browsers tend to act strangely when the number of options in a SELECT list changes after the web page appears, and the SIZE of the SELECT is 1. Instead of making the drop-down list be long enough to hold the options, the drop-down list retains its original length. So if there is only one or two options in the SELECT when the page first appears, tiny scroll bars are forced to appear in the drop-down list, which look kind of silly. To get around this, you can supply a number here--that number of empty options will be added to the SELECT lists when the web page is first displayed. So if SIZE2="1" and you know that the number of choices in the second select will be small when the form appears, and the number of choices is likely to get bigger as the user interacts with the form, then you may want to add an EXTRAOPTIONS2="5" parameter to assure that the second select behaves intuitively.

Note that there is no EXTRAOPTIONS1.

Message1, Message2, Message3
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 the first and select boxes be required, use onSubmit="return require_Name1AndName2()". To make all three be required, use onSubmit="return require_Name1AndName2AndName3()". The text inside the quotes for these onSubmit items is Javascript, so it's case sensitive!

If you want a custom message to appear to the user when they are not allowed to proceed, provide that text here as MESSAGE1, MESSAGE2, or MESSAGE3. Otherwise, the default message will be used: "You must choose an option for NAME."

HTMLAfter1, HTMLAfter2
Insert any HTML code that you want to be output between the first and sencond SELECTs (for instance, a
tag to put a line break between them) for HTMLAFTER1. If omitted, the second select will appear directly to the right of the first. Same with HTMLAFTER2.

HTMLAfterEachRadio1
If TYPE1="RADIO", you can insert any HTML code that you want to be output after each RADIO button that is generated onto your form. For instance, HTMLAFTEREACHRADIO1="<BR>" would cause each Radio button to appear on a new line, with the radio buttons themselves neatly aligned.

OnChange
You can put any Javascript code that want to execute when the user makes a selection from the third 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.

AutoSelectFirst
YES or NO (default is YES). If YES, then when the user selects an item from the second SELECT, the first item of the third SELECT is selected automatically. In general, you will want to use AUTOSELECTFIRST="YES" when SIZE3="1" and NO when SIZE3 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.