Shawn Burke's Blog : Agility

The Toolkit in action: Hooking up the CasdcadingDropDown

sburke — Fri, 14 Apr 2006 18:17:00 GMT

The "Atlas" Control Toolkit makes it super easy to add great usability features to your website.

One of the things people regularly want to do is to create a "cascading" set of DropDownLists, where the value of each populates the values below. The "Atlas" Control Toolkit contains a great extender to make this super easy to set up. It does all of the population of the lists using an async call to a web service, which allows you to filter and cache the data on the server side and easily integrate it into your page.

Go here to download and install the toolkit, and the Atlas April CTP if you don't already have it. Once you've got it installed, you can see demos of all the controls in the toolkit. Note that, like Atlas, this toolkit is an early version. If you find issues, please report them in the Atlas Toolkit Forum so we can fix them for the next release.

But say I want to hook up a set of drop down lists. First, I create a new Atlas Website, and add a reference to the toolkit assembly. You'll find the assembly (called AtlasControlTookit.dll) in the "AtlasControlToolkit\bin" directory where you installed the tookit. When prompted to replace the "Microsoft.Web.Atlas.DLL", choose 'No'.

In the default.aspx page and add some dropdowns to it:

<div>

Make: <asp:DropDownList ID="ddlMake" runat="server"/><br/>

Model: <asp:DropDownList ID="ddlModel" runat="server"/><br/>

Color: <asp:DropDownList ID="ddlColor" runat="server"/>

<br />

<asp:Button ID="Button1" runat="server" Text="Submit" />

</div>

Now, at the top of your ASPX page, register a prefix for the reference to the tookit:

<%@ Register Assembly="AtlasControlToolkit" Namespace="AtlasControlToolkit" TagPrefix="atlasToolkit" %>

And then add the extender itself:

<atlasToolkit:CascadingDropDown ID="CascadingDropDown1" runat="server">

</atlasToolkit:CascadingDropDown>

At runtime, the extender will make callbacks to a web service we specify. In that web service, it expects a WebMethod with the following signature (note that parameter names must match too!):

[WebMethod]

public CascadingDropDownNameValue[] GetColorsForModel(string knownCategoryValues, string category)

The knownCategoryValues parameter will return a string containing the currently selected category values, as well as the category to retrieve values for. For example, if the extender is populating the "Color" field, you will be passed the values for the "Make" and "Model" fields, as well as "Color" to specify the field to return values for.

The CascadingDropDown class has a helper method for unpacking the category values:

StringDictionary kv = CascadingDropDown.ParseKnownCategoryValuesString(knownCategoryValues);

This method will return a StringDictionary containing the name/value pairs of the currently selected values. So imagine you've got a database with tables for the Make (manufacturer), Model, and Color information, and you're accessing that database through a DataSet to which you've added methods for getting each set of values.

The web method to get the available colors for a given model would look like this:

[WebMethod]

public CascadingDropDownNameValue[] GetColorsForModel(

string knownCategoryValues, string category) {

StringDictionary kv = CascadingDropDown.ParseKnownCategoryValuesString(knownCategoryValues);

int modelId;

if (!kv.ContainsKey("Model") || !Int32.TryParse(kv["Model"], out modelId))

{

throw new ArgumentException("Couldn't find make.");

}

CarsTableAdapters.ColorTableAdapter adapter = new

CarsTableAdapters.ColorTableAdapter();

Cars.ColorDataTable colorTable = adapter.GetColorsForModel(modelId);

List<CascadingDropDownNameValue> values = new

List<CascadingDropDownNameValue>();

foreach (DataRow dr in colorTable) {

values.Add(

new CascadingDropDownNameValue(

(string)dr["Color"],

dr["ColorID"].ToString()));

}

return values.ToArray();

}

So it's simple to return the values. Now let's hook up our extender:

<atlasToolkit:CascadingDropDown ID="CascadingDropDown1" runat="server">

<atlasToolkit:CascadingDropDownProperties

TargetControlID="ddlMake"

Category="Make"

PromptText="Select a manufacturer"

ServicePath="CarsService.asmx"

ServiceMethod="GetCarMakes" />

</atlasToolkit:CascadingDropDown>

If you look at this it's pretty simple. TargetControlID specifies which control we're extending, in this case it's the drop down that specifies the manufacturer or "make" of the car. PromptText specifies the text to show in the dropdown when no value is selected, and the ServicePath and ServiceMethod attributes tell the extender which web service to call to fetch it's values.

We can also do this hook up from the designer. If you switch to design view, and select the "ddlModel" DropDownList, you can make these hookups in the property browser at design time:

Note the "ParentControlID" property which specifies which DropDownList is the "parent" for this one. By setting these parent values, you can chain or "cascade" these values, and the CascadingDropDown extender will automatically manage setting, clearing, and loading the data for you.

If you set up the ddlModel and ddlColor lists as well and go back to source view, you'll see:

<atlasToolkit:CascadingDropDown ID="CascadingDropDown1" runat="server">

<atlasToolkit:CascadingDropDownProperties

TargetControlID="ddlMake"

Category="Make"

PromptText="Select a manufacturer"

ServicePath="CarsService.asmx"

ServiceMethod="GetCarMakes" />

<atlasToolkit:CascadingDropDownProperties

TargetControlID="ddlModel"

ParentControlID="ddlMake"

PromptText="Please select a model"

ServiceMethod="GetModelsForMake"

ServicePath="CarsService.asmx"

Category="Model" />

<atlasToolkit:CascadingDropDownProperties

TargetControlID="ddlColor"

ParentControlID="ddlModel"

PromptText="Please select a color"

ServiceMethod="GetColorsForModel"

ServicePath="CarsService.asmx"

Category="Color"/>

</atlasToolkit:CascadingDropDown>

Once you've completed your web service methods, your cascading drop down is complete!

Finally, in order for the values to be submitted, EventValidation needs to be disabled for the page. EventValidation ensures that the values in each control match the values that were present when the page was rendered, but since these drop downs are populating on the client side, this is never true. We’re working on a way to resolve this issue (I'm not happy about it either!), but please ensure that you understand this and validate the data appropriately in your post back when using this control.

"Atlas" Control Toolkit available for download

sburke — Thu, 13 Apr 2006 00:43:00 GMT

Here. Okay, yeah, it took a little longer than I'd hoped but we made some improvements in the meantime.

Check out all the details on the Atlas website, and we've created a forum for the toolkit as well. The controls in the toolkit are basically preview quality. They work at basic scenarios and we'll be releasing refreshes to deal with issues as we find them. But what's more important to me is that they'll hopefully give you examples to start writing controls of your own.

The toolkit includes full source for all of the controls, plus the sample website that demonstrates them. The source is licensed under the Microsoft Permissive License which allows you to modify and reuse the code as you see fit.

The toolkit also includes a VSI that sets up an "Atlas Control Project" template on your machine (VB and C# versions) that will help you get started writing your own controls.

But the best part is yet to come. We're doing something new and different here - this set of controls is more than just a add-on pack, it's going to be the kernel of a shared source project that we're starting around it. Basically, my mission is to band together with our users (you!) and turn this tookit into the biggest, baddest set of web client UI extensions around. We're still working out the details for how this is going to work but it shouldn't be too much longer. Whether you are building an website that you want to bring to life or you want to hack out some radial JavaScript, this project will be the place for you. Stay tuned.

In any case, start dreaming of the cool Atlas controls and extenders that you want to write and make it happen!

Atlas talks at MIX and my new project

sburke — Tue, 21 Mar 2006 02:47:00 GMT

Shanku (Atlas/ASP.NET PUM) just finished giving his Atlas talk where he went through the major parts of Atlas and did a bunch of demos.

He also demo'd some of the stuff that my team has been working on. I've been hinting about exactly what it is, and it's been now (cryptically) mentioned by Shanku and Scott in a few places.

I'm on a mission to make developing Atlas controls and extenders as easy as possible, as soon as possible. I spent a few weeks fiddling with Atlas and I noticed a very common pattern:

Control Extender -> XML Script -> Behavior

Control Extenders, as I mentioned earlier, are server-side controls that hook up server-side UI controls with client side behaviors. The glue between them is XML script that gets parsed on the client side and attaches the behavior to the running browser element.

ControlExtender derive from a class called ExtenderBase, and have a collection of objects that derive from TargetProperies. From my last post, an extender for the ConfirmButton behavior might look like this in the ASPX:

<myns:ConfirmButtonExtender ID="cbe" runat="server">

<myns:ConfirmButtonProperties TargetControlID="Button1" ConfirmText="hello?" />

</myns:ConfirmButtonExtender>

So basically what's here is a class that derives from ExtenderBase that has a collection of type ConfirmButtonProperties. Each ConfirmButtonProperties object has a property called ConfirmText.

The first thing I realized is that if you just named the properties in the ConfirmButtonProperties the same as the ones in your Javascript file, we could easily just walk that object and automatically generate the XML script for you. Cool! That's one less thing to learn, right?

That was just the start. I also realized we could do a bunch of other stuff automatically. Things like...

Knowing which properties referred to controls and then automatically fixing up the IDs at page-render time so they are client ID's in the XML Script (ASP.NET often encodes the ID of your server control to reflect nesting, etc, so "Button1" may not be "Button1" anymore when the browser sees it).
Automatically generating the script reference and packaging it up so you don't have to ship a JS file seperately from your ExtenderControl assembly.
Easily wrapping existing client behaviors so they are usable from the designer and you can program against them in the server-side model.
Encapsulate sending state back and forth between the client and the server so your client side script had some way of sending information back to the server in the event of a postback
Building "Atlas-aware" server side controls that render Atlas client behaviors behind the scenes for great UI experiences
Have your ExtenderControl be able to specify the scripts that it's dependant on and have those automatically downloaded before your control is instantiated so the user doesn't need to know/remember to set them up.

So it kind of grew from there. The more we built the more cool ideas we had. We started writing controls and adding functionality to the base classes, and before long, cranking out awesome Atlas controls/behaviors was a snap.

See, my last post was about how much I dig the Atlas Javascript framework. So my goal here was two-fold:

1) To make the page-builder experience as familiar as possible for an ASP.NET developer

2) Cut out all the steps that I could so all you had to learn to get started was how to work in the Javascript framework. No XML, no script references, none of that. IJW - It Just Works. You can learn the other stuff later, but you're not forced to learn it up front.

And now I've been having fun writing (eeeek!) Javascript and building behaviors that you can easily integrate into new or existing web pages. We're going to give out source for the ones that we've built:

CollapsiblePanel - point this extender at a Panel control, give it a maximum and minimum size, and you'll get the roll-up/roll-down behavior on the client. You can specify which control you "click" to make it collapse/expand, and it can expand horizontially or vertically.
HoverMenu - This is what Shanku demo'd today. Basically, when you hover over control on the page, another control will be made visible and shown at a position of your choosing near your control. Think of a normal GridView scenario where there is an Edit/Delete link by each row. Now think of having those links appear as the user mouses-over each row. You can also specify a CSS class to apply to the target when you over over it so it can highlight, etc.
TextboxWaterkmark - Some websites have greyed out "Type Here" text in textboxes when they're empty. This extender does that. Just tell it which textbox to show the text and what the text should be and it handles the rest.
ToggleButton - basically an image-checkbox, you can have better UI than plain checks in your application. It's still a checkbox under the covers so you can databind to it, etc as usual.
ConfirmButton - this is the most demo I showed in my prior post. Point it at a Button or LinkButton, set the text that you want to show, and it'll handle the rest. If the user clicks "cancel", the click won't happen.
PopupControl - a hosting popup control that lets you have popup UI in your webpage. For example, you can easily create a Date Picker by dropping a calendar control into this.
DragPanel - allows you to make a panel draggable and choose which control is the "handle" that users use to drag it around.
ReorderList - a server-side databound control that generates extenders at render-time and demonstrates how to create an Atlas-aware server side control. In this case, it renders a list of items that the user can drag-drop reorder right in the browser.
CascadingDropDown - an extender that makes doing a sequence of drop down lists a snap (Make -> Model -> Color, for example). It uses the Atlas web-service support to do the population of the lists asyncronously, and manages everything on the client side including clearing child items when a parent value changes (e.g. if you've selected "Ford", and "Mustang" and change to "Cheverolet", the Model field returns to "Please choose a model"), and actually disables fields that are farther down the chain which forces users to select in the right order. It's super cool and can be hooked up to existing lists on the page.

In most of these cases you can also use the Javascript portion side as a standalone for non-ASP.NET scenarios as well.

We're working on getting this stuff packaged up so I can get it posted here soon and on the Atlas site before long. As soon as that happens, I'll post a walkthrough of exactly how to use it so you can see first-hand why I've been having so much fun doing it.

UPDATED: Forgot CascadingDropDown...