Adding Client Capabilities to Server Controls Using the ASP.NET AJAX Control Toolkit - Part 2/Page 4
Â
Adding Client Capabilities to Server Controls Using the ASP.NET AJAX Control Toolkit [con't]
Animations Using the Declarative Method
The declarative approach to animation in the toolkit provides a nice extensibility path for consumers of your extender. In our previous example, we hard coded all the animation functionality inside our extender, providing little support for developer customization. In some cases, this might be all that is needed. In other cases, however, you might need to provide a more robust solution that provides a JavaScript-free way to customize animations. In this section, we replicate the same functionality we created in the preceding section, but we provide a more extensible approach consumers of our extender can use when they are configuring it in the designer. The extender we create has just one feature: the capability to run a FadeIn animation when the onLoad event of an associated image control occurs. This new extender will be used in addition to the ImageRotator extender we created earlier, which had no animation functionality. This refined approach to adding animation support builds on the principle that many extenders can be placed on a single control to provide combined client-side capabilities. To get started, let's take a look at what the declarative syntax or our control will look like before we go into the implementation details. Just as in the preceding section, as we cover how to add this new animation functionality we gloss over the topics we have already covered, focusing only on implementing the declarative animation pieces.
Overview of Declarative Syntax
To get started, let's look at the HTML source we will be working toward being able to work with in our ImageAnimation extender. The source in Listing 11.14 contains an ImageAnimationExtender tag that contains in its body an Animations tag. As you might guess, the approach here is to add various animations that are driven by events raised by the image control we are extending. In our case, we are working with the OnLoad event and adding a Sequence animation that will call a child Fade animation. A Sequence animation is designed to run all its child animations one at a time until all have finished. So, what this source tells us is that our extender will have an animation that will be tied to the OnLoad event of the image control and will run the child Fade animation whenever the OnLoad event occurs.
Listing 11.14 AnimationImageExtender Declarative Syntax
Providing Declarative Support in Your Extender Class
The AnimationExtenderControlBase class provides most of the functionality we need to parse the Animation tag and all its contents. This class provides internal methods that convert the XML representation of the animation into JSON format, which our behavior will then use to run the animation, and also provides the Animation property that we see in Listing 11.15. The following sections cover the steps needed to ensure the extender will work correctly.
|
Add Attributes to the Class
This type of extender has a couple of added class attribute entries of interest to us. The first is the inclusion of the RequiredScript attribute for the AnimationExtender type. The AnimationExtender class provides a lot of the client-side functionality we will be using in our extender control, and by using this type in our RequiredScripts attribute, we are guaranteed that the scripts will be present on the client for us to use. The second attribute is the System.Web.UI.Design.ToolboxItem attribute, which enables our control to show up in the toolbox of Visual Studio. It might seem strange that we have to add this because all our other extenders didn't. If we look at the attributes on the AnimationExtenderControlBase class, however, the support for viewing in the toolbox has been turned off. Therefore, we must reset this value on our control so that it will show up in the toolbox.
Create a Property for the Event
The pattern when creating extenders of this type is to add a property for each event you want to interact with. In our case, we are working with the OnLoad event, so we create a property named OnLoad (to make it easy to understand what the event is). If we were to choose other events, we would name them based on the DOM event they represent. The property accessor for these events must use the GetAnimation and SetAnimation methods to ensure proper data conversion into JSON as the data is stored and retrieved out of the extender's view state.
Add Attributes to the Event Property
The event property must have the Browsable, DefaultValue, Extender ControlProperty, and DesignerSerializationVisibility attributes applied to it. The Browsable attribute stops the property from showing up in the Properties window and therefore excludes the property from being assigned in the Properties window. This is needed because no editor is associated with this property, and we don't want users to try to add anything into the Properties window that would corrupt the values. The Designer SerializationVisibility attribute with a value of DesignerSerialization Visibility.Hidden is used to indicate that the property value should not be persisted by the designer because the Animation property will take care of that for us. The DefaultValue attribute indicates to the designer that the default value will be null, and the ExtenderControlProperty attribute is used to register the property with the ScriptComponentDescriptor.
Listing 11.15 ImageAnimationExtender Class
Adding Declarative Support to Your Behavior Class
The ImageAnimationBehavior class, shown Listing 11.16, provides all the client-side functionality for our extender with support from the animation script files associated with the AutomationExtender class. These associated scripts provide support for converting the JSON representation of the FadeIn animation that was captured on the server to an actual animation, support for associating the animation with the high-level OnLoad event, and support for playing the animation when the OnLoad event occurs.
You need to complete a few steps for each event you plan to work with:
|
Add Variables to the Class
Each event that your behavior will work with needs a variable that references the GenericAnimationBehavior for the event and a delegate that will be called for the event that will be processed. In the ImageAnimationBehavior class, we use the _onLoad variable to store a reference to the GenericAnimationBehavior class and the _onLoadHandler variable to store a reference to the delegate that will handle the onLoad event. The guidelines established so far in the toolkit use a naming convention that includes the event name in all the variable names.
Create Functions
The behavior needs a series of functions for each event you will work with. The get_OnLoad and set_OnLoad functions in our case take care of working with the JSON-based data for the FadeIn animation and utilize the functionality provided by the GenericAnimationBehavior class to store and retrieve that data. The get_OnLoadBehavior function returns a reference to the GenericAnimationBehavior instance that was created for our FadeIn animation, providing the ability to work with the behavior that directly exposes the play, stop, and quit methods common to all animations.
Add Handlers
Handlers must be added for each event the behavior will process and should correspond to the events exposed on the extender control. In our case, we are working with the onLoad event, so we need to create the _onLoadHandler delegate and associate it with the onLoad event of the image using the $addHandler shortcut. The opposite of this must happen in the dispose of our behavior, when we use the $removeHandler shortcut to ensure proper memory cleanup.
Listing 11.16 ImageAnimationBehavior Class
Final Thoughts
The HTML source for our sample, shown Listing 11.14, contains a Fade animation that targets the BannerImage control and runs for a duration of .3 seconds. We could have chosen almost any type of animation as long as it occurred when the OnLoad event fired on the BannerImage image control. This flexibility provides a JavaScript-free way to set up animations of any type when a pattern such as this is used. In fact, this is exactly how the Animation extender works; and if it weren't for the way it handles the OnLoad event, we would have used it in our example.
Summary
The AJAX Control Toolkit comes with quite a bit of functionality that you can use to create truly interactive extenders that require much less coding than if you were to use the ASP.NET 2.0 AJAX Extensions directly. As you learned in this chapter, the toolkit provides a much richer environment for creating extender controls than using the ASP.NET 2.0 AJAX Extensions alone. In addition, the toolkit includes myriad controls you can either use or build on, making the toolkit a compelling alternative.
This chapter is an excerpt from the book, Advanced ASP.NET AJAX Server Controls For .NET Framework 3.5 by Adam Calderon and Joel Rumerman, published by Addison-Wesley Professional, June 2008, ISBN 0321514440, Copyright 2008 Pearson Education, Inc.
Digg This
Add to del.icio.us[previous]
URL:
Find a programming school near you