The GetSelectList method returns a string containing HTML code necessary to create a country selection list box for use on a web-based form.
For example, it is quite common on a web form to have a field called "Country" that contains a drop down list of all the countries for the visitor to select from. This method generates the HTML required to build this form field and have the visitor's country automatically selected by default.
Syntax:
listboxHTML = chObj.GetSelectList [selectTagSuffixAsStr] [, fieldNameAsStr]
[, useNamesInListAsBool] [, codesForListAsStr] [, countryToAutoSelAsStr]
[,prefixStrAsStr]
Note: Use of any of these optional parameters requires the Professional or Enterprise Edition of CountryHawk.
selectTagSuffixAsStr: Use this field to pass in any string you wish to be included after the opening SELECT tag generated by this method. Consider this output:
<select name="country" XXXXX>
By default there will be no text where XXXXX appears above. However you may wish to insert JavaScript or DHTML tags and attributes to be applied to this field. For example, assume you wish to fire a JavaScript event after the user changes the select list, and that you want to set the field to a style sheet class defined elsewhere in your page. In this case you would pass in a string similar to this for the selectTagSuffixAsStr parameter:
"onChange='myEvent()' class=myClass"
This would result in that string being inserted where the XXXX appears above, like so:
<select name="country" onChange='myEvent()' class=myClass>
fieldNameAsStr: Use this parameter if you wish to change the field name assigned by the component from "country" to something else. For example, if you wish to use the name "EndUserCountry" because that's what your current web form already uses, pass that as a string to this parameter. Instead of:
<select name="country">
this would result:
<select name="EndUserCountry">
useNamesInListAsBool: Pass in True if you wish to use the country names as the values posted by the form, instead of the country code which is the default. For example, with the default value of False this method generates:
<select name="country"><option value="US">United States ... </select>
If you pass in True for this parameter, this will generate:
<select name="country"><option value="United States">United States ... </select>
Tip: If you wish to use the country names (say for example you are recording the name in a database and for readability you prefer to record Aruba instead of AW) then there is a more efficient way to do that rather than using True for this parameter. In that case you should still pass in False for this parameter, and then just use the CountryName method to translate the code into the name. This enables you to still get the country name as a value to work with, without having to weigh down your HTML with all the extra characters for the country name. For example, there are about 245 countries, each with names of an average of about 12 characters. That's about 10 characters more per name in the list than
is needed for the country codes, which is only 2 characters. 10 characters times 245 countries means that by using the country names this will require an extra 2K of HTML in your web page. Granted that is a very small amount, but if you are concerned about maximizing the load times and efficiency of your pages as much as possible, 2K saved is 2K saved.
codesForListAsStr: By default the list and order of countries that appears in the select list is obtained from the select.hosts property in the countries.properties file. However there may be times when you wish to override this with a different list at run-time. For example, if you only wish to include a different set or order of countries at run-time. Another common use is if you use the component on a shared web server through your ISP. In this case your preferences may be different than the global preferences set in the countries.properties file. To use this parameter, pass in a list of two-letter country codes separated by spaces. If you pass in an invalid country code, the component will raise an error. If specified, this must contain a list of valid country codes separated by spaces (i.e. "US CA UK").
countryToAutoSelAsStr: By default the component will automatically select the user's country as the default selection in the list. However there may be times when you wish to override this behavior and explicitly tell the component which country to select. To change the default, pass in the two-letter country code for the country you wish to be selected.
rrefixStrAsStr: This field is handy if you wish to add a prefix to each country name that is displayed in the list. For example, you may want to add a couple of spaces to the left of the country name for cosmetic purposes. Or you may want to add a marker next to each name, such as "-> ".
Returns:
The HTML markup used to create the country select list field for your web form.
Example:
<%
'Add an HTML drop down list box for country selection to a form
set chObj = Server.CreateObject("cyScape.countryObj)
%>
<html><form action="here.asp" method="post">
Your name: <input type=text size=30 name=username><br>
Select country:
<% response.write chObj.GetSelectList %>
<input type="submit" value="Submit">
</form></html>
Note: As can be seen in the above example, this method returns just the HTML necessary for the country selection field itself. You need to write out the HTML necessary to create the form, such as the opening and closing <FORM> tags, as well as all other fields you want included in the form. At the point where you want the country selection field added to the form you must write out the value returned by the GetSelectList method.
Tip: See the ch_listbox.asp sample for more information. In addition, the ch_listbox_custom.asp sample demonstrates how to use all of the optional parameters for the GetSelectList method.
See Also:
About the Properties and Methods Guide