Hide the sketches?

Downloading the ASP.NET Ajax Control Toolkit:

The first step we need to take to use the ASP.NET AJAX Control Toolkit, is to download the latest version of the toolkit.  The version we will be downloading and installing will be version 3.0.30512 for ASP.NET 3.5 Service Pack 1.  Download the most current release from CodePlex.com. (**The ASP.NET 2.0 compatible version of the toolkit can be found here.) CodePlex.com is Microsoft’s hosting site for open source projects.  On the downloads page, you will find three different versions of the toolkit.

• AJAXControlToolkitBinary.zip - This package simply contains the binary files (.dlls) for the toolkit, which you can drop into your project and use as is.
• AJAXControlToolkitSource.zip – This package contains the full source for the toolkit, sample pages using the controls, and the binary files needed to drop into your project.  With this package you can modify the controls to extend/alter their functionaly for your custom application.
• AJAXControlToolkitScriptFilesOnly.zip -    This package contains only the javascript, stylesheets, and images for the toolkit.  This package is designed for purely client-side development.

For this tutorial we only want to get started with the base controls, so we want to download the binary files (AJAXControlToolkitBinary.zip).  Once the download is complete we will need to unlock the files.  To do this:

1. Navigate to the directory where you just saved the .zip file.
2. Right-click on the file and select “Properties.”
3. Click on “Unblock” and then click “Ok.”

Click "Unblock" and then click "Ok."

Now, we can right-click on the .zip file and “Extract All…” to extract the contents into our desired directory.

After extracting the files you should have a directory like above.

Now we are ready to add the toolkit to Visual Studio’s toolbox for easy use in future projects.

Installing ASP.NET Ajax Control Toolkit:

We are going to add the toolkit as an expandable tab in Visual Studio’s toolbox, so that when we want to add a new AJAX Control Toolkit control to a page, we can just drag one onto the page.  This will also allow Visual Studio to automatically add the required reference tag (Allowing us to focus on thinking about design patterns, unit tests, and how we can refactor our code instead of memorizing namespaces, and control names).  So let’s add the toolkit to Visual Studio.

1. Open visual studio and either A) Open an existing website, or B) Create a new website.  It doesn’t matter which at this point, the key is just to be able to open an .aspx or .ascx file inside of Visual Studio.
   

   Open a new Website in VS 2008

2. If you created a new website, the Default.aspx page should already be open.  If you opened an existing website, open one of your aspx pages from the solution explorer.
3. Now we need to open the control toolbox.  If you see the “Toolbox” tab on the left hover over it.  If you do not see the “Toolbox” tab, select from the top menu:  View>Toolbox.  You should now see the Toolbox menu on the left hand side of Visual Studio.
   

   View > Toolbox

   

   Toolbox When Visible

4. Now we want to collapse all of the open tabs in the toolbox.  Once all the tabs are closed, right-click in the “empty” space below the tabs and select “Add Tab”, and name it “AJAX Control Toolkit”.
   

   Add a new toolbox tab.

   

   Our New Tab

5. Now that we have a new tab, we need to add our control package to it.  Right-click on the tab and select “Choose Items…” (This may take a moment).
   

   Adding Items to our tab

6. Once the dialog box pops up, click on “Browse” and find the directory where we saved the binary files earlier, and select “AjaxControlToolkit.dll”.  This will automatically add and select all of the controls within the toolkit.  Click “Ok.”
   

   Adding AjaxControlToolkit.dll

7. We should now see all of the ASP.NET AJAX Control Toolkit controls in our newly created tab, ready to be dragged right onto our page and start spicing up our website!
   

   Fully Populated AJAX Toolkit

Using ASP.NET AJAX Control Toolkit Controls:

Using our new control toolkit is quite simple.  As a quick example we will go through how to add a “CalendarExtender” control to your .aspx page.  The calendar extender control allows us to tie it to a TextBox control, so that when the text box receives focus, a small calendar will pop-up and allow the user to click on a date, which will auto-populate the text box with the selected date.

1. First, we need to add an asp:TextBox control to our page.  For this text box we need to give it an ID and make sure it is runat=”server”.
2. Second, we need to add an asp:ScriptManager to our page.  For this we should give it an ID and make sure it is runat=”server”.
3. Next we will open up our AJAX Control Toolkit tab in the “Toolbox” and drag over a “CalendarExtender”.
   

   Drag a CalendarExtender onto our page

4. For this particular control we MUST define a “TargetControlID”, which we will set to the ID we defined for our Text Box.  I have provided a code sample below, with a few optional attributes assigned as well.

1 2 3 4 5 6 7 8 9 10 11 12 13

<%@ Page Language="C#" AutoEventWireup="true"  CodeFile="Default.aspx.cs" Inherits="_Default" %> <%@ Register Assembly="AjaxControlToolkit" Namespace="AjaxControlToolkit" TagPrefix="cc1" %> ... <asp:ScriptManager ID="smManager" runat="server" /> <asp:TextBox ID="txtCalExtenderTest" runat="server" /> <cc1:CalendarExtender ID="CalendarExtender1"                                 runat="server"                                 TargetControlID="txtCalExtenderText"                                 PopupPosition="BottomLeft"                                 Format="MM/dd/yyyy"> </cc1:CalendarExtender> ...

5. That’s all we need to do.  Now you can run the website, and test out your calendar picker.  It should look like the example shown below.
   

   Using the Calendar Extender