Blog For .NET

I’ve been digging deep into the asp.net ajax javascript framework and wanted to share one of the cool controls i was able to make using the asp.net ajax library and the AjaxControlToolkit animation framework. The guys over at codeplex have put together a pretty nice animation framework. It’s been pretty hard for me to find any useful reference material on the animation framework outside of using it really server side. I wasn’t able to find anything about creating your own custom animation classes although the animation framework has obviously a ton of sample code. Eventually i found my best resource to be VS2008 javascript intellisense with the aniamtion framework referenced into my class. Enough of the details, i could rant all day an may do so later but lets get into some of the cool stuff.

javascript references for intellisense

/// 
/// 
/// 
/// 
/// 
/// 
/// 

/// 

specifically this sample doesn’t use the intellisense from all of these references but this is generally what i start with as my js references for any javascript class i’m looking to create. And yes, the intellisense builder requires that the js file references be in an order of dependence. Ok, now we can finally move on to what i’m actually trying to blog about. The scroll to animation.

Type.registerNamespace("boudreau");boudreau.scrollTo = function(element) {
    boudreau.scrollTo.initializeBase(this, [element]);
       this.animation = null;
}
boudreau.scrollTo.prototype = {
    initialize: function() {
    ///

    /// creates our animation and adds a click handler.
    ///
        boudreau.scrollTo.callBaseMethod(this, ‘initialize’);
        this.animation = new $AA.InterpolatedAnimation(this.get_element(), 2, 25, “scrollTop”);
// Important: Notice that the value is passed as a function.
        // This overrides the animation’s getAnimatedValue function.
        this.animation.getAnimatedValue = this.__getAnimatedValue;
    },

dispose: function() {
    ///

    /// Does the cleanup work
    //
        this.animation.dispose();
        boudreau.scrollTo.callBaseMethod(this, ‘dispose’);
    },

scrollTo : function( target ) {
    ///

    /// scrolls the container to to the target element.
    ///

        var container = this.get_element();
        // If we wanted the item to scroll to the middle of the
        // container we set offset = middle.
        var middle = ($common.getContentSize(container).height / 2.0 );

        // For now we just use a 40 pixel offset so it isn’t hugging
        // the top of the container.
        var offset = 40;

        //set start and ending positions of the scroll window.
        this.animation.set_startValue(container.scrollTop);
        this.animation.set_endValue(target.offsetTop - 40);

        //let the framework do it’s job.
        this.animation.play();

    },

__getAnimatedValue : funtion ( percentage ) {
        ///

        ///  This method is run in the context of the animation object.  Therefore it’s
        ///  important to understand that when this function is executing that “this”
        ///  referes to the animation object, NOT the boudreau.scrollTo object.
        ///  Besides that this function performs a simple linear interpolation.
        ///
        ///
        /// It’s important to note the reason we have to define this function is that it’s a
        ///  MustOverride on the InterpolatedAnimation object.
        ///  The reason i used InterpolatedAnimation is so that i could
        ///  implement a non-linear animation.
        ///

        return this.get_startValue() + (this.get_endValue() - this.get_startValue()) * (percentage * / 100);

    }

}

boudreau.scrollTo.registerClass(’boudreau.scrollTo’, Sys.UI.Behavior);

if (typeof(Sys) !== ‘undefined’) Sys.Application.notifyScriptLoaded();

That’s the code.
If you aren’t comfortable with prototypical development in javascript then you’ll you should brush up on that. [Blog Link, WWW Link?] But if you are then lets dive into the details.

The Behavior
scrollTo object derives from microsoft’s Sys.UI.Behavior which is used to extend the functionality of a particular DOM element. This behavior acts on the scrollable container you define as the target element. If someone asked me what this behavior did i’d tell them ” It’s a javascript object that holds a reference to a DOM element, the container, (This is what we get from microsoft ajax library.) The javascript object knows hows to scroll, with animation, to a given target element inside the container. ” If you can decipher that you’ve got it. On to the gory details.

The constructor - new $AA.InterpolatedAnimation()
In the init method we define a new InterpolatedAnimation first off $AA is a shorthand for AjaxControlToolkit.Animation, it saves us some 20 chars to type, and download for that matter. The constructor used above takes some 7 parameters but we are only passing in 4 because i’m happy with the default values for the others for now. The first, the target element, is the object that should contain the scrollBar you want to animate. The second and third are fps and duration respectively (which i won’t discuss cause they are pretty self explanitory.) the fourth parameter is the property of the the target element you want to animate using the InterpolatedAnimation. Kind of important to understand what’s going on here, this parameter is what the interpolated animation updates when it is told to .play(). So, in our case we want to animate the scrollTop property of the target element. scrollTop is just a javascript property that gets/sets the top of the content area in a scrollable window. Alright, that’s creating the animation. Hopefully you see what’s going on here, lets recap. We are creating an interpolated animation object inside of our behavior and telling it what property on what element we want to animate. Next we’ll look at the scrollTo function and see how the behavior does the work.

The worker - scrollTo()
the scrollTo() method does all the work of finding and scrolling to the correct distance inside the container. At the end we hope to see that our target element is 40 px below the scrollTop of the container content window. First we define the properties on the animation that will be interpolated, the start and end scrollTop value of the container. These two properties on the InterpolatedAnimation are the values you want the animation to interpolate across. (remember how we set scrollTop as the property in the constructor.) Our InterpolatedAnimation is going to interpolate the values between start_value and end_value on the container element (the scrollable element) and update the property scrollTop with the value at each step in the animation. This is how it works, if you don’t understand the previous explanation read it again, it’s the magic and hopefully you can tell there is no real magic at all!

// For now we just use a 40 pixel offset so it isn't hugging
// the top of the container.
var offset = 40;

//set start and ending positions of the scroll window.
this.animation.set_startValue(container.scrollTop);
this.animation.set_endValue(target.offsetTop - 40);

this.animation.play();

So that’s pretty much it, after you

$create(boudreau.scrollTo, null,null,null, $get(scrollableElementId))

a scrollTo behavior on a scrollable element you use

$find(scrollableElementId).scrollTo(element_to_scroll_to_in_container)

to produce a nice smooth scroll to the target element inside the scrollable container.

No Comments yet »