Get Started with the AJAX Control Toolkit (VB)

hushedsnailInternet and Web Development

Nov 12, 2013 (3 years and 8 months ago)

79 views

Get Started with the AJAX Control Toolkit
(VB)

Tutorials

By Microsoft ASP.NET Team
|
May 12, 2009

Learn all you need to know to get started using the AJAX Control Toolkit.

The AJAX Control Toolkit contains more than 30 free controls that you can use in your ASP.NET

applications. In
this tutorial, you learn how to download the AJAX Control Toolkit and add the toolkit controls to your Visual
Studio/Visual Web Developer Express toolbox.

Downloading the AJAX Control Toolkit

The AJAX Control Toolkit is an open source pro
ject developed by the members of the ASP.NET community and
the ASP.NET team. The AJAX Control Toolkit is hosted at CodePlex.com which is the Microsoft website for
hosting open source projects.

Navigate to the following URL to go directly to the AJAX Contro
l Toolkit CodePlex page:

http://AjaxControlToolkit.CodePlex.com

Click the Downloads link (see Figure 1) to see a list of different versions of the AJAX Control Toolkit. For
example, you can

download the version of the toolkit that contains the AJAX Control Toolkit controls.
Alternatively, you can download the full version of the Toolkit that contains the controls, a sample site, and the
source code for the controls.


Figure 01
: Downloading

the AJAX Control Toolkit
(
Click to view full
-
size image
)

After you download the file, you need to unblock the file. Right
-
click the file, select
Properties, and click the
Unblock

button (see Figure 2).


Figure 02
: Unblocking the AJAX Control Toolkit ZIP file
(
Click to view full
-
size image
)

After you unblock the file, you can unzip the file: Right
-
click the file and select the
Extract All

menu option.
Now, we are ready to add the toolkit to the Visual Studio/Visual Web Developer toolbox.

Adding the AJAX Control Toolkit to the Toolbox

The eas
iest way to use the AJAX Control Toolkit is to add the toolkit to your Visual Studio/Visual Web
Developer toolbox (see Figure 3). That way, you can simply drag a toolkit control onto a page when you want to
use it.


Figure 03
: AJAX Control Toolkit appears

in toolbox
(
Click to view full
-
size image
)

First, you need to add an AJAX Control Toolkit tab to the toolbox. Follow these steps.

1.

Create a new AS
P.NET Website by selecting the menu option File, New Website. Double
-
click the
Default.aspx in the Solution Explorer window to open the file in the editor.

2.

Right
-
click the Toolbox beneath the General Tab and select the menu option
Add Tab

(see Figure 4).

3.

E
nter a new tab named AJAX Control Toolkit.


Figure 04
: Adding a new tab
(
Click to view full
-
size image
)

Next, you need to add the AJAX Control
Toolkit controls to the new tab. Follow these steps:



Right
-
click beneath the AJAX Control Toolkit tab and select the menu option
Choose Items (see Figure
5)
.



Browse to the location where you unzipped the AJAX Control Toolkit and select the AjaxControlToolk
it.dll
assembly.


Figure 05
: Choose items to add to the toolbox
(
Click to view full
-
size image
)

After you complete these steps, all of the toolki
t controls will appear in your toolbox.

Upgrading to a New Version of the Toolkit

If you were using an older release of the Toolkit and now need to move to a later version here are the
recommended steps:



Binaries
-

Delete the old version of the
AjaxControlToolkit.dll assembly from your website Bin folder.



Toolbox Items
-

Delete the AJAX Control Toolkit tab and follow the steps above to re
-
create the tab with
the new version of the AjaxControlToolkit.dll assembly.

=================================
==================================================

Using AJAX Control Toolkit Controls and Control
Extenders
(VB)

Tutorials

By Microsoft ASP.NET Team
|
May 12, 2009

Learn how to add AJAX Control Toolkit controls and extenders to your ASP.NET pages.

The AJAX Control
Toolkit contains a set of controls and control extenders. In this brief tutorial, you learn how to
add both controls and control extenders to an ASP.NET page.

For instructions on installing the AJAX Control Toolkit and adding the AJAX Control Toolkit to th
e Visual
Studio/Visual Web Developer toolbox, see the tutorial
Get Started with the AJAX Control Toolkit
.

Using AJAX Control Toolkit Controls

An AJAX

Control Toolkit control works just like a normal ASP.NET control. You can drag the control from the
toolbox onto an ASP.NET page. You can add the control to the page in either Design view or Source view.

There is one special requirement when using the
controls from the AJAX Control Toolkit. The page must contain
a ScriptManager control. The ScriptManager control is responsible for including all of the necessary JavaScript
required by the AJAX Control Toolkit controls.

For example, the AJAX Control Toolk
it tab includes a control named the Editor control. This control displays a
rich HTML editor. Follow these steps to add the Editor control to a page:

1.

Create a new ASP.NET page named ShowEditor.aspx

2.

Select the ScriptManager control from beneath the AJAX Ex
tensions tab in the toolbox and drag the
control onto the page.

3.

Select the Editor control from beneath the AJAX Control Toolkit tab in the toolbox and drag the control
onto the page (see Figure 1). The Designer should look like Figure 2.

4.

Run the web site b
y selecting the menu option
Debug, Start Debugging

or hitting the F5 key.

5.

You should see the page in Figure 3.


Figure 01
: Selecting the HTML Editor control
(
Click to view full
-
size image
)


Figure 02
: Visual Studio Designer with ScriptManager and Edit control
(
Click to view full
-
size image
)


Figure 03
: The DisplayEditor.aspx page
(
Click to view full
-
size image
)

Using AJAX Control Toolkit Control Extenders

The AJAX Control Toolkit a
lso contains control extenders. As its name suggests, a control extender extends the
functionality of an existing control. For example, the ConfirmButton control extender extends the standard
ASP.NET Button control. The extender changes the Button control�
s behavior so that the Button displays a
confirmation dialog when you click it.

A control extender, just like an AJAX Control Toolkit control, requires a ScriptManager control. You must add a
ScriptManager control to a page before you start using control
extenders in the page.

Follow these steps to use the ConfirmButton control extender:

1.

Create a new ASP.NET page named ShowConfirmButton.aspx

2.

Add a ScriptManager control to the page by dragging the control onto the page from beneath the AJAX
Extensions tab.

3.

Add a standard Button control to the page by dragging the Button from beneath the Standard tab in the
toolbox onto the Designer surface.

4.

Click the
Add Extender

task option (see Figure 4).

5.

In the Choose Extender dialog, select ConfirmButtonExtender (see Fig
ure 5) and click the OK button.

6.

Select the Button control in the Designer and expand the Extenders, Button1_ConfirmButtonExtender
node in the Properties window (see Figure 6). Assign the value
�Really?�

to the ConfirmText property.

7.

Run the page by selectin
g the menu option
Debug, Start Debugging

or hit the F5 key.


Figure 04
: The Add Extender task option
(
Click to view full
-
size image
)


Figure 05
:

Selecting the ConfirmButton control extender
(
Click to view full
-
size image
)


Figure 06
: Setting a ConfirmButton property
(
Click to view full
-
size image
)

When the page opens, you should see a button. When you click the button, you get the confirmation dialog in
Figure 7.


Figure 07
: Displ
aying the confirmation dialog
(
Click to view full
-
size image
)

Notice that you normally do not drag a control extender onto a page. Instead, you us
e the
Add Extender

task
option to add an extender to a control that you have already added to a page. Notice, furthermore, that you set
control extender properties by opening the property sheet for the control being extended.

A single ASP.NET control can b
e extended by multiple control extenders. The property sheet for the control
being extended will list all of the control extenders associated with the control.

====================================================================================

Creating a Custom AJAX Control Toolkit Control
Extender
(VB)

Tutorials

By Microsoft ASP.NET Team
|
May 12, 2009

Custom Extenders enable you to customize and extend the capabilities of ASP.NET controls without having to
create new classes.

In this tutorial, you
learn how to create a custom AJAX Control Toolkit control extender. We create a simple, but
useful, new extender that changes the state of a Button from disabled to enabled when you type text into a
TextBox. After reading this tutorial, you will be able to

extend the ASP.NET AJAX Toolkit with your own control
extenders.

You can create custom control extenders using either Visual Studio or Visual Web Developer (make sure that
you have the latest version of Visual Web Developer).

Overview of the DisabledButto
n Extender

Our new control extender is named the DisabledButton extender. This extender will have three properties:



TargetControlID
-

The TextBox that the control extends.



TargetButtonIID
-

The Button that is disabled or enabled.



DisabledText
-

The text t
hat is initially displayed in the Button. When you start typing, the Button displays
the value of the Button Text property.

You hook the DisabledButton extender to a TextBox and Button control. Before you type any text, the Button is
disabled and the TextB
ox and Button look like this:


(
Click to view full
-
size image
)

After you start typing text, the Button is enabled and the TextBox and Button loo
k like this:


(
Click to view full
-
size image
)

To create our control extender, we need to create the following three files:



DisabledButtonExtender.vb
-

This file is the server
-
side control class that will manage creating your
extender and allow you to set the properties at design
-
time. It also defines the properties that can be set
on your extender. These properties are accessi
ble via code and at design time and match properties
defined in the DisableButtonBehavior.js file.



DisabledButtonBehavior.js
--

This file is where you will add all of your client script logic.



DisabledButtonDesigner.vb
-

This class enables design
-
time func
tionality. You need this class if you want
the control extender to work correctly with the Visual Studio/Visual Web Developer Designer.

So a control extender consists of a server
-
side control, a client
-
side behavior, and a server
-
side designer class.
You l
earn how to create all three of these files in the following sections.

Creating the Custom Extender Website and Project

The first step is to create a class library project and website in Visual Studio/Visual Web Developer. We�ll
create the custom extender
in the class library project and test the custom extender in the website.

Let�s start with the website. Follow these steps to create the website:

1.

Select the menu option
File, New Web Site
.

2.

Select the
ASP.NET Web Site

template.

3.

Name the new website
Website1
.

4.

Click the
OK

button.

Next, we need to create the class library project that will contain the code for the control extender:

1.

Select the menu option
File, Add, New Project
.

2.

Select the
Class Library

template.

3.

Name the new class library with the name
CustomExtenders
.

4.

Click the
OK

button.

After you complete these steps, your Solution Explorer window should look like Figure 1.


Figure 01
: Solution with website and class library project
(
Click to view full
-
size image
)

Next, you need to add all of the necessary assembly references to the class library project:

1.

Right
-
click the CustomE
xtenders project and select the menu option
Add Reference
.

2.

Select the .NET tab.

3.

Add references to the following assemblies:

1.

System.Web.dll

2.

System.Web.Extensions.dll

3.

System.Design.dll

4.

System.Web.Extensions.Design.dll

4.

Select the Browse tab.

5.

Add a reference
to the AjaxControlToolkit.dll assembly. This assembly is located in the folder where you
downloaded the AJAX Control Toolkit.

You can verify that you have added all of the right references by right
-
clicking your project, selecting Properties,
and clicking
the References tab (see Figure 2).


Figure 02
: References folder with required references
(
Click to view full
-
size image
)

Creating the Custom Con
trol Extender

Now that we have our class library, we can start building our extender control. Let�s start with the bare bones
of a custom extender control class (see Listing 1).

Listing 1
-

MyCustomExtender.vb

Imports

AjaxControlToolkit


Imports

System.ComponentModel


Imports

System.Web.
UI

Imports

System.Web.
UI
.WebControls




<Assembly:

System.Web.
UI
.WebResource("CustomExtenders.MyControlBehavior.js",

"text/javascript")>






<ClientScriptResource("CustomExtenders.MyControlBehavior",

"CustomExtenders.MyControlBehavior.js")>

_

<TargetControlType(GetType(TextBox))>

_

Public

Class

MyControlExtender



Inherits

ExtenderControlBase





<ExtenderControlProperty()>

_


<DefaultValue("")>

_


Public

Property

MyProperty()

As

String



Get



Return

GetPropertyValue("MyProperty",

"")



End

Get



Set(ByVal

value
As

String)



SetPropertyValue("MyProperty",

value
)



End

Set



End

Property


End

Class


There are several things that you
notice about the control extender class in Listing 1. First, notice that the class
inherits from the base ExtenderControlBase class. All AJAX Control Toolkit extender controls derive from this
base class. For example, the base class includes the TargetID p
roperty that is a required property of every
control extender.

Next, notice that the class includes the following two attributes related to client script:



WebResource
-

Causes a file to be included as an embedded resource in an assembly.



ClientScriptResour
ce
-

Causes a script resource to be retrieved from an assembly.

The WebResource attribute is used to embed the MyControlBehavior.js JavaScript file into the assembly when
the custom extender is compiled. The ClientScriptResource attribute is used to retri
eve the
MyControlBehavior.js script from the assembly when the custom extender is used in a web page.

In order for the WebResource and ClientScriptResource attributes to work, you must compile the JavaScript file
as an embedded resource. Select the file in

the Solution Explorer window, open the property sheet, and assign
the value
Embedded Resource

to the
Build Action

property.

Notice that the control extender also includes a TargetControlType attribute. This attribute is used to specify
the type of contro
l that is extended by the control extender. In the case of Listing 1, the control extender is
used to extend a TextBox.

Finally, notice that the custom extender includes a property named MyProperty. The property is marked with
the ExtenderControlProperty a
ttribute. The GetPropertyValue() and SetPropertyValue() methods are used to
pass the property value from the server
-
side control extender to the client
-
side behavior.

Let�s go ahead and implement the code for our DisabledButton extender. The code for this
extender can be
found in Listing 2.

Listing 2
-

DisabledButtonExtender.vb

Imports

System.ComponentModel


Imports

System.Web.
UI

Imports

System.Web.
UI
.WebControls


Imports

AjaxControlToolkit




<Assembly:

System.Web.
UI
.WebResource("CustomExtenders.DisabledButtonBehavior.js",

"text/javascript")>






<Designer(GetType(DisabledButtonExtender))>

_

<ClientScriptResource("CustomExtenders.DisabledButtonBehavior",

"CustomExtenders.DisabledButtonBehavior.js")>

_

<TargetContr
olType(GetType(TextBox))>

_

Public

Class

DisabledButtonExtender



Inherits

ExtenderControlBase





<ExtenderControlProperty()>

_


<DefaultValue("")>

_


<IDReferenceProperty(GetType(Button))>

_


Public

Property

TargetButtonID()

As

String



Get



Return

GetPropertyValue("TargetButtonID",

"")



End

Get



Set(ByVal

value
As

String)



SetPropertyValue("TargetButtonID",

value
)



End

Set



End

Property





<ExtenderControlProperty(),

DefaultValue("")>

_


Public

Property

DisabledText()

As

String



Get



Return

GetPropertyValue("DisabledText",

"")



End

Get



Set(ByVal

value
As

String)



SetPropertyValue("DisabledText",

value
)



End

Set



End

Property




End

Class




The DisabledButton extender in Listing 2 has two properties named TargetButtonID and DisabledText. The
IDReferenceProperty applied to the TargetButtonID property prevents you from assigning anything other than
the ID o
f a Button control to this property.

The WebResource and ClientScriptResource attributes associate a client
-
side behavior located in a file named
DisabledButtonBehavior.js with this extender. We discuss this JavaScript file in the next section.

Creating
the Custom Extender Behavior

The client
-
side component of a control extender is called a behavior. The actual logic for disabling and enabling
the Button is contained in the DisabledButton behavior. The JavaScript code for the behavior is included in
Listi
ng 3.

Listing 3
-

DisabledButton.js

Type.
registerNamespace
('CustomExtenders');




CustomExtenders.DisabledButtonBehavior

=

function(
element
)

{





CustomExtenders.DisabledButtonBehavior.
initializeBase
(this,

[
element
]);





this.
_targetButtonIDValue
=

null;



this.
_disabledTextValue
=

null;




}




CustomExtenders.DisabledButtonBehavior.
prototype
=

{





initialize
:

function()

{



CustomExtenders.DisabledButtonBehavior.
callBaseMethod
(this,

'initialize');





// Initalization code



$addHandler
(this.
get_element
(),

'keyup',



Function.
createDelegate
(this,

this.
_onkeyup
));



this.
_onkeyup
();



},





dispose
:

function()

{



// Cleanup code





CustomExtenders.DisabledButtonBehavior.
callBaseMe
thod
(this,

'dispose');



},





// Property accessors



//



get_TargetButtonID
:

function()

{



return

this.
_targetButtonIDValue
;



},





set_TargetButtonID
:

function(
value
)

{



this.
_targetButtonIDValue
=

value
;



},





get_DisabledText
:

function()

{



return

this.
_disabledTextValue
;



},





set_DisabledText
:

function(
value
)

{



this.
_disabledTextValue
=

value
;



},





_onkeyup
:

function()

{





var

e
=

$get
(this.
_targetButtonIDVa
lue
);



if

(
e
)

{



var

disabled
=

(""

==

this.
get_element
().
value
);



e
.
disabled
=

disabled
;



if

(

this.
_disabledTextValue
)

{



if

(
disabled
)

{



this.
_oldValue
=

e
.
value
;



e
.
value
=

this.
_disabledTextValue
;



}



else



{



if(this.
_oldValue
){



e
.
value
=

this.
_oldValue
;



}



}



}



}



}




}




CustomExtenders.DisabledButtonBehavior.
registerClass
('CustomExtenders.DisabledButtonB
ehavior',

Aja
xControlToolkit.BehaviorBase);




The JavaScript file in Listing 3 contains a client
-
side class named DisabledButtonBehavior. This class, like its
server
-
side twin, includes two properties named TargetButtonID and DisabledText which you can access using
get_TargetButtonID/set_TargetButtonID and get_DisabledText/set_DisabledText.

The initialize() method associates a keyup event handler with the target element for the behavior. Each time you
type a letter into the TextBox associated with this behavior, the
keyup handler executes. The keyup handler
either enables or disables the Button depending on whether the TextBox associated with the behavior contains
any text.

Remember that you must compile the JavaScript file in Listing 3 as an embedded resource. Selec
t the file in the
Solution Explorer window, open the property sheet, and assign the value
Embedded Resource

to the
Build
Action

property (see Figure 3). This option is available in both Visual Studio and Visual Web Developer.


Figure 03
: Adding a
JavaScript file as an embedded resource
(
Click to view full
-
size image
)

Creating the Custom Extender Designer

There is one last class that we need

to create to complete our extender. We need to create the designer class in
Listing 4. This class is required to make the extender behave correctly with the Visual Studio/Visual Web
Developer Designer.

Listing 4
-

DisabledButtonDesigner.vb

Imports

AjaxControlToolkit.Design






Public

Class

DisabledButtonDesigner



Inherits

ExtenderControlBaseDesigner(Of

DisabledButtonExtender)




End

Class


You associate the designer in Listing 4 with the DisabledButton extender with the Designer attribute.You need
to apply the Designer attribute to the DisabledButtonExtender class like this:

<Designer
(
GetType
(
DisabledButtonDesigner
))
>

_

<ClientScriptResour
ce
(
"CustomExtenders.DisabledButtonBehavior"
,
"CustomExtenders.DisabledButtonBehavior.js"
)
>

_

<TargetControlType
(
GetType
(
TextBox
))
>

_

Public Class DisabledButtonExtender


Inherits ExtenderControlBase

Using the Custom Extender

Now that we have finished

creating the DisabledButton control extender, it is time to use it in our ASP.NET
website. First, we need to add the custom extender to the toolbox. Follow these steps:

1.

Open an ASP.NET page by double
-
clicking the page in the Solution Explorer window.

2.

Righ
t
-
click the toolbox and select the menu option
Choose Items
.

3.

In the Choose Toolbox Items dialog, browse to the CustomExtenders.dll assembly.

4.

Click the
OK

button to close the dialog.

After you complete these steps, the DisabledButton control extender should

appear in the toolbox (see Figure
4).


Figure 04
: DisabledButton in the toolbox
(
Click to view full
-
size image
)

Next, we need to create a new
ASP.NET page. Follow these steps:

1.

Create a new ASP.NET page named ShowDisabledButton.aspx.

2.

Drag a ScriptManager onto the page.

3.

Drag a TextBox control onto the page.

4.

Drag a Button control onto the page.

5.

In the Properties window, change the Button ID propert
y to the value
btnSave

and the Text property to the
value
Save*
.


We created a page with a standard ASP.NET TextBox and Button control.

Next, we need to extend the TextBox control with the DisabledButton extender:

1.

Select the
Add Extender
task option to op
en the Extender Wizard dialog (see Figure 5). Notice that the
dialog includes our custom DisabledButton extender.

2.

Select the DisabledButton extender and click the
OK

button.



Figure 05
: The Extender Wizard dialog
(
Click to view full
-
size image
)

Finally, we can set the properties of the DisabledButton extender. You can modify the properties of the
DisabledButton extender by modifying the propertie
s of the TextBox control:

1.

Select the TextBox in the Designer.

2.

In the Properties window, expand the Extenders node (see Figure 6).

3.

Assign the value
Save

to the DisabledText property and the value
btnSave

to the TargetButtonID property.


Figure 06
: Setting
extender properties
(
Click to view full
-
size image
)

When you run the page (by hitting F5), the Button control is initially disabled. As soon as yo
u start entering text
into the TextBox, the Button control is enabled (see Figure 7).


Figure 07
: The DisabledButton extender in action
(
Click to

view full
-
size image
)

Summary

The goal of this tutorial was to explain how you can extend the AJAX Control Toolkit with custom extender
controls. In this tutorial, we created a simple DisabledButton control extender. We implemented this extender
by creati
ng a DisabledButtonExtender class, a DisabledButtonBehavior JavaScript behavior, and a
DisabledButtonDesigner class. You follow a similar set of steps whenever you create a custom control extender.