Ajax Control Toolkit CascadingDropdown

Modified on 2010/04/15 19:41 by Stephen Walther — Categorized as: Uncategorized

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).

CascadingDropDown Server Reference

The properties in italics 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.

CascadingDropDown Client Reference

Sys.Extended.UI.CascadingDropDownBehavior Class

Summary - The CascadingDropDownBehavior object is used to populate drop downs with values from a Web service.
Parameters - Sys.UI.DomElement element

Events

selectionChanged(handler) - Add or removes an event handler for the selectionChanged event.
- Parameters - A function representing the event handler.
populating(handler) - Add or removes an event handler for the populating event.
- Parameters - A function representing the event handler.
populated(handler) - Add or removes an event handler for the populated event.
- Parameters - A function representing the event handler.

Methods

initialize() - Initializes the components and parameters for the CascadingDropDown control behavior.
dipose() - Disposes the CascadingDropDown control behavior's resources.
raiseSelectionChanged(eventArgs) - Raises the selectionChanged event.
- Parameters - Sys.Extended.UI.CascadingDropDownSelectionChangedEventArgs eventArgs
raisePopulating(Sys.CancelEventArgs) - Raises the populating event.
- Parameters - A Sys.EventArgs object representing event arguments for the populating event.
- Remarks - The populating event can be used to provide custom data to CascadingDropDown instead of using a Web service. To do this, cancel the event (using the CancelEventArgs) and pass your own data to the _setOptions method.
raisePopulated(eventArgs) - Raises the populated event.
- Parameters - A Sys.EventArgs object representing event arguments for the populated event.

Properties

ParentControlID - Gets or sets a string containing the ID of the parent drop down in a hierarchy of drop downs.
Category - Gets or sets a string containing the category of this drop down.
PromptText - Gets or sets a string containing the prompt text that is displayed as the first entry in the drop down.
PromptValue - Gets or sets a string containing the value for the option displayed by a DropDownList showing the PromptText.
EmptyText - Gets or set a string containing the text for the option displayed when the list is empty.
EmptyValue - Gets or sets a string containing the value for the option displayed when the list is empty.
LoadingText - Gets or sets a string containing the loading text to to be displayed when getting the drop down's values from the Web service.
SelectedValue - Gets or sets a string containing the selected value of the drop down.
ServicePath - Gets or sets a string containing the path of the Web service.
ServiceMethod - Gets or sets a string containing the name of the method to invoke on the Web service.
contextKey - Gets or sets a string containing user or page specific context provided to an optional overload of the Web method described by ServiceMethod or ServicePath.
- Remarks - If the context key is used, it should have the same signature with an additional parameter named contextKey of type string.
useContextKey - Gets or sets a boolean value that determines whether or not the ContextKey property should be used.
- Remarks - The useContextKey property 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.

Sys.Extended.UI.CascadingDropDownSelectionChangedEventArgs Class

Summary - Event arguments used when the selectionChanged event is raised.
Parameters - String oldValue, String newValue

Properties

oldValue - Gets a string containing the previous selection.
newValue - Gets a string containing the new selection.