Ajax Control Toolkit
CascadingDropDown Demonstration
Make
Model
Color

[No response provided yet]
CascadingDropDown Description

CascadingDropDown is an ASP.NET AJAX extender that can be attached to an ASP.NET DropDownList control to get automatic population of a set of DropDownList controls. Each time the selection of one the DropDownList controls changes, the CascadingDropDown makes a call to a specified web service to retrieve the list of values for the next DropDownList in the set.


CascadingDropDown enables a common scenario in which the contents of one list depends on the selection of another list and does so without having to embed the entire data set in the page or transfer it to the client at all.


All the logic about the contents of the set of DropDownList controls lives on the server in a web service. This web service can use any suitable method for storing and looking up the relevant data.


The sample web service used here reads the data set from a simple hierarchical XML data file. The sample data file shows that the DropDownList items can have distinct names and value (values are optional in the sample). It also demonstrates that items can have an optional optionTitle attribute which will be displayed as a tooltip over the item in some modern browsers. Finally, an item can be selected by default. In the XML file, the Racing Blue option for the BMW is selected by default.


There is also a walkthrough showing how to use a CascadingDropDown with a database.

CascadingDropDown Properties

The control above is initialized with this code. The italic properties are optional:

<ajaxToolkit:CascadingDropDown ID="CDD1" runat="server"
    TargetControlID="DropDownList2"
    Category="Model"
    PromptText="Please select a model"
    LoadingText="[Loading models...]"
    ServicePath="CarsService.asmx"
    ServiceMethod="GetDropDownContents"
    ParentControlID="DropDownList1"
    SelectedValue="SomeValue" />
  • TargetControlID - The ID of the DropDownList to populate.
  • Category - The name of the category this DropDownList represents.
  • PromptText - Optional text to display before the user has selected a value from the DropDownList.
  • PromptValue - Optional value set when PromptText is displayed.
  • EmptyText - Optional text to display when the DropDownList has no data to display.
  • EmptyValue - Optional value set when EmptyText is displayed.
  • LoadingText - Optional text to display while the data for the DropDownList is being loaded.
  • ServicePath - Path to a web service that returns the data used to populate the DropDownList. This property should be left null if ServiceMethod refers to a page method. The web service should be decorated with the System.Web.Script.Services.ScriptService attribute.
  • ServiceMethod - Web service method that returns the data used to populate the DropDownList. The signature of this method must match the following:
    [System.Web.Services.WebMethod]
    [System.Web.Script.Services.ScriptMethod]
    public CascadingDropDownNameValue[] GetDropDownContents(
           string knownCategoryValues, string category) { ... }
    Note that you can replace "GetDropDownContents" with a naming of your choice, but the return type and parameter name and type must exactly match, including case.
  • ContextKey - User/page specific context provided to an optional overload of the web method described by ServiceMethod/ServicePath. If the context key is used, it should have the same signature with an additional parameter named contextKey of type string:
    [System.Web.Services.WebMethod]
    [System.Web.Script.Services.ScriptMethod]
    public CascadingDropDownNameValue[] GetDropDownContents(
           string knownCategoryValues, string category, string contextKey) { ... }
    Note that you can replace "GetDropDownContents" with a name of your choice, but the return type and parameter name and type must exactly match, including case.
  • UseContextKey - Whether or not the ContextKey property should be used. This will be automatically enabled if the ContextKey property is ever set (on either the client or the server). If the context key is used, it should have the same signature with an additional parameter named contextKey of type string (as described above).
  • ParentControlID - Optional ID of the parent DropDownList that controls the contents of this DropDownList.
  • SelectedValue - Optional value to select by default. This needs to exactly match the string representation of a value in the DropDownList.
  • UseHttpGet - Optional value which determines whether to use HttpGet or HttpPost method for the postback to the server.
  • EnableAtLoading - Optional value which determines whether or not the dropdownlist control is disabled when the control is waiting to get data from the service.
Copyright © 2006-2013 Microsoft Corporation. All Rights Reserved.