LA.NET [EN] : JQuery

JQuery: full control with the $.ajax function

luisabreu — Wed, 19 Aug 2009 14:17:59 GMT

In the previous posts, we’ve met several helper methods which simplify the code needed to perform remote out-of-band requests. In this post, we’ll be introducing the all mighty $.ajax method. This method is used by all the other methods we’ve seen until now and gives you complete control over the request.

Currently, you’re supposed to use an anonymous object to pass all those definitions (which are really a lot!). To illustrate the use of this method, we’ll be consuming a ASP.NET web service which returns JSON. We’ll start with the service code (defined on the SayHiService.asmx(.cs) file):

[WebService(Namespace = "http://tempuri.org/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[System.ComponentModel.ToolboxItem(false)]
[System.Web.Script.Services.ScriptService]    
public class SayHiService : System.Web.Services.WebService {
    [WebMethod]
    public User SayHello(String name) {
        return new User {
            Name = name,
            Date = DateTime.Now
        };
    }
}
public class User {
    public String Name { get; set; }
    public DateTime Date { get; set; }
}

We’ve created a simple User class that will return a user and the current time at which the request was received on the server. If you’re into ASP.NET AJAX, then you’ll know that it uses JavascriptSerializer to serialize the return value into JSON. In the client side, you’re expected to transform the returned JSON into an object by using the Sys.SerializationJavaScriptSerializer JS class.

If you’re consuming ASP.NET web services from client code, there are some aspects you should keep in mind:

the returned object is wrapped into an anonymous object with a single property (called d). This means that you’ll always receive a JSON string which looks like “{ ‘d’: … }”;
DateTime fields are transformed into /Date(x)/, where x is the number of ms elapsed since Jan. 1, 1970 at midnight UTC. In practice, this means that you’ll have to recover x and transform it into a valid JS Date object;
don’t forget that the web service needs to receive a JSON payload too. This means that you need to set the content type and you do need to serialize (into JSON) the arguments you’re passing from the client. If the method doesn’t receive any parameters, you should send the ‘{}’ string or it won’t work;
by default, the web service will only respond to POST requests (if you want to open it up to GET requests, you need to use the ScriptMethodAttribute on the web service definition)

If you used the Sys.SerializationJavaScriptSerializer JS class, you don’t have to worry with these details. However, you might not want to load the MS AJAX file just to do the parsing of the returned JSON (btw, I’ve used this approach in an previous post about ASP.NET MVC and JSON). And that’s what we’ll do in this post: we’ll use JQuery and the JSON plugin (which you can download from here) to interact with the previous web service. Here’s the final code of this page:

<input type="text" />
<input type="button" value="Server" />
<div></div>
<script type="text/javascript">
    $(function() {
        $("input[type=button]").click(
                
                function(evt) {
                    $.ajax({
                        url: "SayHiService.asmx/SayHello",
                        type: "post",
                        data: $.toJSON({ name: $("input[type=text]").val() }),
                        contentType: "application/json; charset=utf-8",
                        dataType: "json",
                        success: function(data) {
                            var user = data.d;
                            //update date                            
                            user.Date = new Date( parseInt(user.Date.match( /\d+/ )[0] ) );
                            var html = "Nome: " + user.Name + "--- Date: " + user.Date;
                            $("div").html(html);
                        }
                    });
                });
    });
    
</script>

Some observations about the previous code:

when calling the web service, you need to indicate the method that you want to invoke. That’s why we passed “SayHiService.asmx/SayHello” to the url property;
since I didn’t change the default server configuration, we need to ensure that the request will be made through a POST request (notice the type property);
we’re using the $.toJSON utility function to serialize an object which contains the information we want to send back to the server;
by passing json to the dataType, we’ll be getting a JS object in our success calback method;
the callback method starts by recovering the returned object (remember that we need to access the d property of an anonymous object). Then I used the most simple regular expression possible to recover the x from within the /Date(xxxx)/ string returned from the server side (as a side note, I’m betting that there are better ways of doing this, but regular expressions aren’t really my thing…);
you probably should pass a function to the error property so that you cna be notified about errors that have occurred during the request.

I guess there’s more to say about this method, but I think that the previous snippet covers what you’ll be using in 99% of the times. If you have the time, then do take a look at all the available options because there’s some interesting stuff going on there.

And that’s it. Keep tuned for more on JQuery.

JQuery: deferred script loading

luisabreu — Wed, 19 Aug 2009 11:18:25 GMT

Deferred script loading is a technique which can be used to reduce the initial loading time of any page. The idea is to load only the basic JavaScript code that is necessary for the initial loading operations of the page and then perform additional downloads for features that the user *might* use after initial rendering.

This is a fairly known and common technique and you’ll even find a pattern called On-demand JavaScript on the AJAX patterns web site. JQuery helps by introducing the utility $.getScript function. To illustrate its use, lets assume that we’ve got a button that won’t be *heavily* used and that relies on several JavaScript lines of code. This is a scenario where the user experience can be improved by using deferred script loading.

We’ll be simulating this by using a simple JS file (called hi.js) with the following code:

function sayHi(name) {
    alert(name);
}

Since we’re facing lots of JS lines (please imagine it:)) and this code isn’t necessary for the initial load of the page, we’ve decided to run it only when needed, ie, only when someone clicks the say Hi button. Here’s the code we might ended up writing:

<input type="text" />
<input type="button" value="Server" />
<script type="text/javascript">
    $(function() {
        $("input[type=button]").click(            
                function(evt) {                        
                    if( !window.sayHi ) {
                        evt.target.disabled = "disabled";
                        $.getScript("hi.js", function() {
                            sayHi($("input[type=text").val());
                            evt.target.disabled = "";
                        });
                    }
                    else{
                        sayHi( $("input[type=text").val() );
                    }
                });
    });
</script>

It might seem complicated, but it’s not. Since we’re loading an JS file, we need to make sure that we’ll only load it once (loading several times the same user file doesn’t really do much for improving the user experience, right?). The easiest way to do that is to check for the existence of the sayHi function (it will be defined after the successful load of the JS file). To ensure that the user won’t click the button twice before the file is loaded, we need to disable it and enable it when the JS code has been loaded and evaluated (which is perfect for the callback function we can pass to the $.getScript function).

And that’s it. Keep tuned for more on JQuery.

JQuery: the $.getJson method

luisabreu — Wed, 19 Aug 2009 10:44:09 GMT

In the previous post, we’ve met the $.get and $.post methods. At the time, we’ve seen how we could easily load a JSON payload returned from the server. If you know that you’ll be getting JSON and that the request will be an HTTP GET, then you can use the $.getJson utility function instead of the $.get function.

To illustrate its use, we’re going to reuse the previous example and we’ll only be updating the client code of the page:

<script type="text/javascript">
    $(function() {
        $("input[type=button]").click( 
            function(){
                $.getJSON("HowdyHandler.ashx", 
                      { name: $("input[type=text]").val()},
                      function(data){
                        $("div").html("Hi <b>" + data.name + "</b>" );
                     } );
            });
    
    });
</script>

As you can see, the only difference is that the $.getJSON function receives only three parameters (when compared with the code we had to receive JSON with the $.get function). This isn’t surprising because this method reuses the $.get method internally for doing its work. Here’s its current implementation:

getJSON: function( url, data, callback ) {
    return jQuery.get(url, data, callback, "json");
}

And that’s it for today. Keep tuned for more on JQuery.

JQuery: the $.get and $.post methods

luisabreu — Wed, 19 Aug 2009 10:27:23 GMT

In this post we’ll keep looking at JQuery’s helper methods for remote calls and we’ll see how we can use the get and post functions for performing HTTP GET and POST requests. Both functions (notice that these are utility functions and not JQuery object methods!) expect several parameters:

$.get( url, [data], [callback], [type] )
$.post( url, [data], [callback], [type] )

The first three parameters are the same as the ones we’ve met in a previous post when we looked at the load method. type is new and lets you indicate the type of response returned from the server. It’s important to set this if you’re getting non HTML/text content from the server side. Currently, it supports the values “xml", "html", "script", "json", "jsonp" and "text".

To show you how easy it is to use this utility function, we’ll start by creating a new handler which expects to retrieve a name from the request and returns an HTML snippet:

public class HowdyHandler : IHttpHandler {
    public void ProcessRequest(HttpContext context) {
        context.Response.ContentType = "text/html";
        context.Response.Write(
                String.Format("Hi <b>{0}</b>!", context.Request["name"]) );
    }
    public bool IsReusable { get { return false; } }
}

Nothing special here, right? Now, take a look at the following HTML snippet:

<body>
    <input type="text" />
    <input type="button" value="Server" />
    <div></div>
</body>
<script type="text/javascript">
    $(function() {
        $("input[type=button]").click( 
            function(){
                $.get("HowdyHandler.ashx", 
                      { name: $("input[type=text]").val()},
                      function(data){
                        $("div").html(data);
                     });
            });
    
    });
</script>

We’ve got a textbox and a button which will fire the AJAX request. If you run the previous snippet, you’ll see that you’ll end up doing an HTTP GET request and that you’ll get the “Hi name” message in the div.

Even though getting HTML from the server is handy, it’s not something that I’d do in a typical web app. In my opinion, the server side should only return info and the HTML formatting should be done by client side code (ie, code running in the browser). In these scenarios, I’ll probably tend to use JSON for the response. Lets update our handler to do that:

public void ProcessRequest(HttpContext context) {
    context.Response.ContentType = "application/json";
    context.Response.Write(
            String.Format("{{ 'name': '{0}' }}", context.Request["name"]) );
}

And now, we need to update our $.get call so that it knows that the response will be in JSON:

<script type="text/javascript">
    $(function() {
        $("input[type=button]").click( 
            function(){
                $.get("HowdyHandler.ashx", 
                      { name: $("input[type=text]").val()},
                      function(data){
                        $("div").html("Hi <b>" + data.name + "</b>" );
                     },
                     "json");
            });
    
    });
</script>

With this approach, we build the HTML in the client side. Since we’ve said that the response will be in JSON (notice that last parameter of the $.get function), data will now reference a JS object built from the JSON that is returned from the server.

The $.post utility function is really similar to the $.get function. The main difference is that you end up doing an HTTP POST request instead of a GET. And that’s it for this post. Keep tuned for more on JQuery.

JQuery: getting started with AJAX

luisabreu — Mon, 17 Aug 2009 13:34:59 GMT

Today marks the beginning of using JQuery for handling AJAX requests. This is going to be a short post and we’ll be talking about the load method. The load method is able to perform get or post requests to replace the contents of the elements contained in the wrapped set with the response returned from the server side. As you’ve probably guessed, this method will only be usable in certain (few!) scenarios, where you’ll be writing the returned contents directly into one or more HTML elements (in my opinion, returning HTML from the server is a bad practice and you should avoid it at all costs).

To illustrate the use of the load method, we’ll start by creating a new ASP.NET handler (which I’ll be appropriately calling DumbHandler) which returns the current server time:

public class DumbHandler : IHttpHandler {
    public void ProcessRequest(HttpContext context) {
        context.Response.ContentType = "text/html";
        context.Response.Write(
           String.Format("<p><span>{0}</span></p>", DateTime.Now));
    }
    public bool IsReusable { get { return false; } }
}

Now that we’ve got the handler, we can concentrate on the client code. The load method expects until three parameters:

the url of the “page” that will be requested;
an optional data parameter that might contain an anonymous object with name/value pairs (results in a post request) or a string of name/value pairs (means you’ll be using a get request);
an optional callback method which will be fired when the AJAX request ends and each of the wrapped elements is updated with the returned content. Notice that this will also be called when you get an error in the request.

With this info, lets get started and build our first client AJAX script:

<p id="main">This is a paragraph</p>
<p>This is another paragraph</p>
<input type="button" value="Replace content" id="bt" />
<script type="text/javascript">
    $(function() {
        $("input[type=button]").click(function() {
            var url = "DumbHandler.ashx";
            $("#main").load(url);
        });
    });    
</script>

The idea is simple: we handle the click event by performing a remote request through the load method. Since we’re only passing the url, this means that we’ll be performing a GET request and that the returned contents will be “written” inside our p#main paragraph.

Lets suppose that I need to pass additional info to the server. If we want the info to be sent through GET, then we need to pass that information through the data parameter as a string. Here’s how we’d do that:

$("input").click(function() {
    var url = "DumbHandler.ashx";
    $("#main").load(url, "user=Luis");
});

Really simple, right? Ok, but what if we needed to get that info form form fields? In that case, the serialize method is the way to go. To illustrate this method, let’s start by adding a form to our HTML page:

<form>
    <label for="name">Name:</label>
    <input type="text" name="name" />
    <br />
    <label for="age">Age:</label>
    <select name="age">
        <option value="1">10-20</option>
        <option value="2">21-30</option>
        <option value="3">31-40</option>
        <option value="4">41+</option>
    </select>
    <br />
</form>
<p id="main">This is a paragraph</p>
<p>This is another paragraph</p>
<input type="button" value="Replace content" id="bt" />

And here’s the changes we need to make to get the serialized info from our form fields:

$("input").click(function() {
    var url = "DumbHandler.ashx";
    $("#main").load(url, $("form").serialize());
});

If you want, you can only load a subset of the returned HTML. To do that, you need to filter the returned HTML by using a special selector delimited by SPACE on the url string. To show how this works, lets update our handler so that it returns the info that is sent through the AJAX request:

public void ProcessRequest(HttpContext context) {
    context.Response.ContentType = "text/html";
    var name = context.Request["name"];
    var age = context.Request["age"];
    context.Response.Write(
            String.Format("<p>Name:<span>{0}</span> at {1} </p>", 
                           name, age));
}

As you can see, we return an html snippet which looks like <p>Name: <span>XXXX</span> at YYY<p>. Lets assume that we’re only interested in showing the span element. That can be easily achieved by using the following url:

var url = "DumbHandler.ashx span";

Notice the space delimiting the url from the selector…

As I’ve said, you can also pass a callback method. This method will receive three parameters:

the response text returned from the current request;
the text status (success is passed when everything runs ok);
a reference to the current XMLHttpRequest object that was responsible for executing the server side call (this lets you get more info about possible errors).

As you’ve probably guessed, the this reference will point to the “current” updated element of the wrapped set (don’t forget that the method ends up being called after each element of the wrapped set has been updated with the info returned from the server).

And I guess this concludes this first query on JQuery and AJAX. Stay tuned for more.

JQuery: running custom animations

luisabreu — Fri, 14 Aug 2009 13:45:15 GMT

In the previous posts, we’ve met several methods which run some predefined animations. Instead of trying to add methods for all possible animations, JQuery has decided to introduce a helper function which you can reuse for animating several css properties (notice that you can only animate properties which expect numeric values).

Currently, there are two “overloads” of the animate method:

animate(props, duration, easing, callback)
animate(props, options)

As you can see, there are a lot of things going on here:

props is an anonymous object which indicate the css properties that should be animated and their final values. It’s possible to use em or % as units and you can even use relative animations by passing –= or += to decrement or increment the current value of the specified css property;
duration is used for defining the duration of the animation. It’s an optional parameter and, in 1.3, if you set it to 0, JQuery will synchronously set the elements to their end state. Before you ask, the answer is yes, you can also use the magic strings we’ve met in the past (slow, normal and fast);
easing indicates the name of a previously registered function for performing the easing. According to the docs, there are two predefined easing functions: “linear” and “swing”;
callback references a callback function which will be called for each of the elements when the animation ends;
options is used on the second “overload” and it expects an anonymous object for setting the animation. Currently, you can define values for duration, easing, complete, step (method reference which will be called for each step of the animation) and queue (boolean value which indicates if the animation should be queued or started immediately).

There are some properties which probably deserve additional info. Easing influences the processing of frames and relies on mathematical calculations. I’m not really into this stuff, so I’ll leave further investigation of it to you :)

If you use the “overload” which uses the options object, then you’ll also be able to decide if animations should be run in parallel. By default, animations are run synchronously, that is, if you call animate several times, one animation will only start after the other has finished (don’t confuse calling animate several times with animating several properties at once in a single animate call). If you’d like to run an animation at the time of invocation, then you’ll need to set the options’ queue property to false.

I’m sorry, but I’m not really into design and effects, so I guess that the sample code for this post we’ll have to be even dumber than the ones I’ve presented in the past. Take a look at the following code which animates an existing paragraph:

<p id="paragraph">This is a paragraph</p>
<input type="button" value="Move and grow" id="bt" />
<script type="text/javascript">
    $(function() {
        $("input").click(function() {
            $("p").css("position", "relative")
                  .css("backgroundColor", "green")
                  .animate( {left:100,
                                    width: "-=20%",
                                    height: 300
                                    },
                                    200);
                });
    });    
</script>

Clicking the button kicks off a series of custom animations. We start by moving the P element so that it stays 100px left of the original position. Then, we decrease its current height by 20% and set its height in 300px. The whole thing should run in 200 ms.

I’ll change the previous example slightly in order to show you how you could kick several. Take a look at the following code:

<script type="text/javascript">
    $(function() {
        $("input").click(function() {
            $("p").css("position", "relative")
                  .css("backgroundColor", "green")
            //.animate({ left: 100 }, 100)
                  .animate({
                      left: 100,                     
                      width: 300
                  },
                    5000)
                .animate({
                        height: 100
                    },
                    {
                        duration: 5000,
                        queue: false
                    });
        });
    });    
</script>

Try changing the value of queue property and see what happens. Since I’ve set the animation to 5 seconds, it should be enough for understanding what’s going on.

And that’s it! Keep tuned for more on JQuery!

JQuery: sliding

luisabreu — Thu, 13 Aug 2009 08:59:30 GMT

In this post, we’ll take a look at the JQuery methods used for sliding animations. We’ve got 3 methods for executing sliding animations:

slideDown: shows all the hidden elements contained in the wrapped set of the JQuery object.
slideUp: hides all visible elements defined in the wrapped set.
slideToggle: toggles the elements between hidden and visible.

The methods expect the traditional speed (you can pass an integer or one of the “magic” strings we’ve met in the past) and (optional) callback function parameters. If you didn’t notice, these methods are really similar to the show/hide/toggle methods we’ve met in a previous post.

The slide methods affect several css properties. Besides changing the height, the latest version of JQuery (1.3 when I wrote this) will also animate the vertical padding and vertical margins of the elements in order to ensure a smoother transition between visible and hidden (notice that element will also be removed from the display at the end of the animation). Here’s a small sample that shows how easy it is to add sliding to an element:

<html xmlns="http://www.w3.org/1999/xhtml" >
<head runat="server">
    <title></title>
    <style type="text/css">
        p{ 
            border: solid 1px red;
            height: 100px;
            margin:10px;
        }           
    </style>
    <script src="jquery-1.3.2.js" type="text/javascript"></script>
</head>
<body>
<p>This is a paragraph</p>
<p>This is a paragraph</p>
<p>This is a paragraph</p>
<input type="button" value="slide down/up" />
<script type="text/javascript">
    $(function() {
        $("input").click(
            function() { $("p").slideToggle(500); });
    });    
</script>
</body>
</html>

If you run the previous snippet, you’ll notice that clicking the button ends up sliding the p elements of the page (I’ve added a default height to all the paragraphs to make the transition more visible). If you’re interested in hiding the elements at page load, then you can simply set their CSS display property to none.

And that’s it. Keep tuned for more on JQuery.

JQuery: fading elements

luisabreu — Wed, 12 Aug 2009 10:29:44 GMT

In this post we’ll keep looking at the animations and we’ll see how to add fading effects to an element. Unlike showing and hiding, which affect several css properties of the element, fading will only affect the opacity (alpha filters if you’re running IE) and display of an element. Currently, JQuery offers 3 methods: fadeIn, fadeOut and fadeTo.

Here’s a small sample that shows how you can use the fadeIn and fadeOut methods:

<p id="div2">div 2</p>
<input type="button" value="fade in/out" />
<script type="text/javascript">
    $(function() {
        $("input").toggle(
                    function() { $("p").fadeOut(300); },
                    function() { $("p").fadeIn(300); }
                    );
    });    
</script>

If you run the previous snippet, you’ll see that odd clicks change the element’s opacity in 300 ms and then it will be “removed” from the view (ie, its display will be set to none at the end of the animation). Fading in performs the opposite operation, changing the opacity from 0 to 1. Both methods can receive two parameters:

the first indicates the speed to run the animation. You can specify it in milliseconds (like we did in the previous snippet) or you can use one of the “magic” strings: slow, fast or def (stands for default). Notice that passing anything different from slow or fast is the same as passing def;
the second identifies a callback function which will be fired when the animation ends. You can use the this reference inside the function to get a reference to the DOM element that was animated.

If you’ve set an initial opacity to the element by applying a style, then that value will be retained by these methods and fading in will always recover the element’s initial opacity.

If you’ve run the previous sample, you’ve probably noticed that fading in and out result in setting the opacity to 1 and 0 respectively. In other words, those methods will always show or hide an element. If you need to go half way (ex.: change the opacity to 0.5), then you should use the fadeTo method. Let’s update the previous sample so that it fades an element between 0.2 and 0.8:

<script type="text/javascript">
    $(function() {
        $("input").toggle(
                    function() { $("p").fadeTo(300, 0.2); },
                    function() { $("p").fadeTo(300, 0.8); }
                    );
    });    
</script>

The fadeTo method expects until 3 parameters:

the first indicates the speed (it’s used in the same way as the speed parameter used in the fadeIn and fadeOut methods. Notice that you can also use the same “magic” strings we’ve mentioned above);
the second indicates the final value of the opacity and should have a value between 0 and 1;
finally, you can pass an (optional) callback method which will be fired when the animation completes.

There’s a really important difference between fadeTo and the previous fade methods: fadeTo won’t do anything to the css display property of the element that is being animated.

And that’s it. In the next post we’ll take a look at sliding. Keep tuned for more on JQuery.

JQuery: getting started with effects

luisabreu — Tue, 11 Aug 2009 10:00:02 GMT

JQuery offers support for basic effects, like showing, hiding, fading and sliding. Besides that, it also facilitates the construction of new animations by introducing some custom methods which you can reuse to produce some basic animations. Today we’ll be concentrating on two methods: show and hide. Both these methods have two “overloads”: one takes no parameters and the other expects a timeout and an optional callback method (notice that Javascript doesn’t really support the OO overload concept since there’s only a single method which runs some tests on the passed arguments).

Let’s start by looking at what happens when you call the methods and don’t pass any parameters. Calling hide is the same as setting the style’s display to none. Calling show results in setting the style’s display to the default element's style or in recovering the previous default style (more about this in the next paragraphs). Take a look at the following snippet:

<span class="test">span 1</span>
<span>Another span</span>
<div class="test" id="div2">div 2</div>
<input type="button" id="show" value="show" />
<script type="text/javascript">
    $(function() {            
        $("#show").toggle(
                        function(){$(".test").hide();}, 
                        function(){$(".test").show();} );
    });    
</script>

If you run the previous snippet, you’ll notice that the hide method effectively hides all the elements. Calling show ends up setting the style’s display property to the default value of each of the wrapped set elements. As I said before, if you had an initial value applied to the display property when you called hide, that value will be preserved and remembered for a future show call. When that happens, that initial style will be applied again. Take a look at the next snippet:

<span class="test" style="display: block">span 1</span>
<span>Another span</span>
<div class="test" id="div2">div 2</div>
<input type="button" id="show" value="show" />
<script type="text/javascript">
    $(function() {
        $("#show").toggle(
                        function() { $(".test").show(); },
                        function() { $(".test").hide(); } );
    });    
</script>

As you can see, we’re using our old toggle event function helper to alternate between functions for the click event. If you run this sample, you’ll notice that invoking hide still removes the wrapped set elements from the view (by setting the display property to none) and that when you call show, the span retains its initial display value.

If you change the order of the calls (ie, if you change the order of the functions in the toggle method), you’ll end up loosing the initial display of the span. If you don’t believe me, then replace the previous script with the next:

<script type="text/javascript">
    $(function() {
        $("#show").toggle(
                        function() { $(".test").show(); },
                        function() { $(".test").hide(); } );
    });    
</script>

And now hiding/showing will always result in getting the default span’s display.

You’re probably wondering what’s going on with hide and show. It’s not that complicated…in fact, it’s really simple. When you call hide, you end up saving the current display value to a named data slot that is added to each of the wrapped set elements (by using the internal jQuery.data function – we’ll come back to this method in future posts).

Whenever the show method is invoked, it starts by trying to get the previously stored display value from that named slot. If it finds one, it will apply it to the style’s display property. If it can’t find it, then it will simply create a new element of that type (ie, with the same tag name) so that it can get its default style’s display value (notice that this means that you end up adding/removing a new element to the body element to get that information). This is the default behavior you get when you don’t pass any parameters to these methods.

If you decide to use the other “overloads” of these methods, you’ll really be adding animation effects. As I’ve said at the beginning of the post, the second “overload” of this method expects:

a mandatory speed parameter, which defines the total time that will be taken to show/hide the element in milliseconds;
an optional callback function which will be called when the animation ends.

Lets update the previous snippet so that it uses these overloads:

<span class="test">span 1</span>
<span>Another span</span>
<div class="test" id="div2">div 2</div>
<input type="button" id="show" value="show" />
<script type="text/javascript">
    $(function() {
        $("#show").toggle(
                        function() { $(".test").hide(500); },
                        function() { $(".test").show(500); } );
    });    
</script>

Running the previous code should result in an animation that changes the width, height, opacity, padding, margins and display of the element. This leads to a more graceful smoothing effect. Instead of specifying the speed in milliseconds, you can also use one of three predefined strings: slow, normal or fast.

If you want, you can also pass a callback function to both the hide and show methods. The function doesn’t receive any parameters and you can access the “animated” DOM element by using the this reference. You should also keep in mind that most of the previous references made about the show and hide methods that take no parameters still hold: the only exception is that calling show on a visible element with a predefined display value doesn’t override that value with the elements default style’s display value.

I know that I’ve said this post would only be about show and hide, but I guess there’s still time (and space) for introducing the toggle method. Take a look at the next snippet:

<span class="test" style="display: block">span 1</span>
<span>Another span</span>
<div class="test" id="div2">div 2</div>
<input type="button" id="show" value="show" />
<script type="text/javascript">
    $(function() {
        $("#show").click(function() { $(".test").toggle(); });
    });    
</script>

The previous snippet produces the same effect as our initial snippet. If you want, you can also pass values for speed and for a callback method:

<script type="text/javascript">
    $(function() {
        $("#show").click(function() { $(".test").toggle("300"); });
    });    
</script>

As you can see, toggle can be used as click helper or as an animation helper that hides and then shows the wrapped set elements. The passed arguments decide which version will be used (notice that passing two functions results in getting the event method).

And that’s it for today. Keep tuned for more on JQuery.

JQuery: utility functions X – extending objects

luisabreu — Mon, 10 Aug 2009 14:06:34 GMT

This is the last post of the day on JQuery and we’re going to talk about extending objects with the extend utility function. The idea is simple: how can you add properties from an object to another and get a new object? For instance, suppose you’ve got these two anonymous objects:

var student = { name: "Luis", age: 20 };
var address = { street: "some street", civilParish: "somewhere"};

And now you’d like to add the address’ properties to the student object. You can do that by using the extend function:

var extendedStudent = $.extend(student, address);

If you’re using a debugger, you’ll notice that student has been “expanded” with the two properties defined on address:

Notice that this method expects more parameters that the ones that we used in the previous snippet. If you pass several objects, you’ll end up adding the properties of all those objects to the first object. If some of the copied objects have properties with the same name, then the values of the last objects will override the initially copied values of the previous ones.

There’s also a first optional boolean parameter which you can use to indicate if you’re doing a deep or a shallow copy of the properties of the objects. This parameter is optional and you’ll end up with a shallow copy when you don’t specify a value.

And that it’s for today. I guess we’ve covered most of the current utility functions and now we’re ready to look at animations. Keep tuned for more on JQuery.

JQuery: utility functions IX – transforming arrays

luisabreu — Mon, 10 Aug 2009 13:51:49 GMT

The map utility function can be used to translate all the elements contained in the array into other set of items. You’ll find this method useful when you need to transform a collection of items A into items. The function expects two parameters:

an array of items that is going to be translated;
a callback function which will be called for each item and is responsible for transforming the existing item into a new item.

Here’s a simple example which doubles all the integers contained on an array named arr:

var arr = [1, 2, 3, 4];
var doubled = $.map(arr, function(item) { return item * 2; });
alert(doubled);

You might be thinking that this is so simple that you could do it by using a simple for. Fair enough…and if I told you that I’d like to receive only the double of elements which aren’t divisible by four? Here’s how you’d do that:

var arr = [1, 2, 3, 4];
var doubled = $.map(arr, function(item) { if( item % 4 === 0 ) return null; return item * 2; });
alert(doubled);

Returning null removes an item from the final array. Ok, I can hear you thinking! Yes, this is still doable with a simple for and using continue for the cases that don’t matter…And what if I told you that I want the first three multiples of all numbers which aren’t divisible by four? (and I’m talking about a flat array, not an array of arrays). Here’s how you’d do it with this utility method:

var arr = [1, 2, 3, 4];
var doubled = $.map(arr,
function(item) {    
    var items = [];
    var i = 0;
    while (i++ < 3) {
        items[i ] = item * i;
    }
    return items;
});

Simple and easy, right? For the sake of completeness, I’d like to point out that the callback function receives two arguments: the first (which was used in all the previous samples) references the current item of the array that is being enumerated; the second returns the current position within the array. Keep tuned for more on JQuery.

JQuery: utility functions VIII – creating arrays from other objects

luisabreu — Mon, 10 Aug 2009 13:30:39 GMT

The utility function makeArray is a helper which is used internally by JQuery to transform collections of nodes into arrays. Even though this function is “public”, you’re not expected to use it much. Here’s its current internal implementation:

makeArray: function( array ) {
    var ret = [];
    if( array != null ){
        var i = array.length;
        // The window, strings (and functions) also have 'length'
        if( i == null || typeof array === "string" || jQuery.isFunction(array) || array.setInterval )
            ret[0] = array;
        else
            while( i )
                ret[--i] = array[i ];
    }
    return ret;
}

As you can see, the code function starts by getting the length and checking the current type of the array parameter. If you’re passing a function (isFunction helper), a string, a window object or if the length doesn’t exist, you’ll end getting an array with a single element.

In the remaining scenarios, you’ll go through all the elements in the array and you’ll copy them to an array. Notice that in Javascript it’s possible to have an object which isn’t an array but that does behave like one. Let me present a simple example of this:

var arr = (function() {
   return $.makeArray(arguments);
})(1, 2, 3);

So, what I’m doing here? Simple: I’m creating and executing an anonymous function and saving the returned result on the arr variable. The anonymous function will pass arguments to the makeArray function and you’ll get back a “real” array. If you debug the previous code, you’ll see that arguments behaves like an array but it’s not an array:

As you can see, the arguments object has indexes and you even have a length property. However, things stop working if you try to use a method that exists on arrays. For instance, if you use the push method, you’ll end up getting an exception.

The node lists which you get back from the methods like getElementsByTagName behave like arrays but aren’t really arrays. In those cases, you can easily get an array by using this utility function. And that’s all for this post. Keep tuned for more on JQuery.

JQuery: utility functions VII – concatenating arrays

luisabreu — Mon, 10 Aug 2009 10:23:25 GMT

In this post we’re going to take a look at the merge utility function. This function expects two arrays that will be merged. The method returns a reference to the first array augmented with the elements contained on the second (which remains unchanged). Here’s a small snippet that shows how to use this function:

var arr = [0, 1, 2];
var anotherArr = [-1, -2, -3];
var merged = $.merge(arr, anotherArr);

The important thing here is that you shouldn’t forget that merged points to arr and that arr now has the items contained by anotherArr. Notice also that this function doesn’t remove duplicates. If you need that you’ll need to use the $.unique method (though it only works with DOM nodes). Keep tuned for more on JQuery.

JQuery: utility functions VI – checking if an item is in an array

luisabreu — Mon, 10 Aug 2009 09:34:49 GMT

In the last post we’ve seen how to get all the items that comply with a specific filter. In this post, we’re going to see how to see if an item is in an array. The easiest way to do that is to use the inArray function. Take a look at the following snippet:

var arr = [0, -2, 4, 6, - 9];
var positives = $.inArray(4,arr);

The inArray method expects two parameters: the item that is going to be checked and the array that is going to be enumerated. Internally, the utility function relies on the the === operator for seeing if any of the array’s items matches the first parameter.

Notice that inArray returns an integer. It will return non negative integer that represents the position of the passed item. If it doesn’t find a matching item, it will simply return –1. And that’s it. Keep tuned for more on JQuery.

JQuery: utility functions IV – interacting through arrays

luisabreu — Fri, 07 Aug 2009 14:07:30 GMT

In this post, we’re going to look at the each utility function. This function expects two parameters: an object which is going to be enumerated and a callback function reference which is going to be called for each item in the enumerated set. It’s important to understand that this is different from the each jQuery method (which is used for interacting over each element of the wrapped set).

Traditionally, you use indexes for going through all the items in an array. There are also some times where you need to enumerate all the properties of an object. In those cases, you’ll generally use the for in loop. If you want, you can reduce the code needed by using the each method. When you’re using an array, you’ll be writing a function that receives one parameter:

var arr = [1, 2, 3];
$.each(arr, function(val) { alert(val); });

On the other hand, if you’re enumerating properties, then you’ll need (at least) two parameters: one for the property name and another for the value:

var obj = { name: "John", age: 12 };
$.each(obj, function(prop, val) { alert(prop + ":" + val) });

You probably won’t find much value in using the functionality of this method, but you’ll notice that it does reduce the amount of required typing. Before ending, there’s still time for saying that returning false from the method results in stopping the enumeration of the existing items.

And that’s it. Keep tuned for more on JQuery.

JQuery: utility functions – testing helpers

luisabreu — Fri, 07 Aug 2009 13:32:17 GMT

One of the things you might need to do is check if a reference is an array or a function. JQuery introduces two simple utility functions for performing these checks: the isArray and the isFunction methods. Both of them expect a single parameter which is used to perform the adequate test. Here’s a really dumb example that shows how to use the isFunction function:

var sayHi = function(name) {
    alert(name);
}
if ($.isFunction(sayHi)) {
    sayHi("Luis");
}

As you can see, we check the sayHi variable and we’ll only invoke it when it is, in fact, a function. These are really simple and rely on the typeof operator for checking the type of an existing reference. For instance, here’s the code for the previous isFunction helper:

isFunction: function( obj ) {
    return toString.call(obj) === "[object Function]";
}

And I guess that sums it up. Keep tuned for more on JQuery.

JQuery: utility functions II – trimming strings

luisabreu — Fri, 07 Aug 2009 13:21:02 GMT

In this post we’re going to talk about the helper trim method. This is really a simple function which removes any leading or trailing whitespaces from the passed string. Notice that the method uses regular expressions and considers white spaces as any char that matches spaces, form feed, new line, return, tab and vertical tab characters.

Using the function is really simple, as you can see from this snippet:

var someText = "    Hello there";
alert("-" + $.trim(someText) + "-");

And that’s it. Keep tuned for more on JQuery.

JQuery: utilities functions I – browser detection

luisabreu — Fri, 07 Aug 2009 10:54:15 GMT

Today we’re going to start looking at the JQuery utilities function. The utilities function include several low level helper methods used on JQuery’s core. The good news is that you can also reuse them in your own code. In this post we’re going to take a look at the browser detection helper functions.

Before v1.3, JQuery had several helper objects for getting info about the the browser where your pages were loaded. These objects were called browser, boxModel and styleFloat and they can (still) be accessed through properties on the jquery object ($.browser, $.boxModel and $.styleFloat). With v1.3, these old objects have been deprecated by a new property called support which contains most of the information you had in the previous properties. The advantage of the new support object is that it relies on feature detection instead of browser sniffering.

Here is a quick preview of the properties you’ll find in the support object:

boxModel: returns true if the page renders the box model according to the W3C Spec;
cssFloat: true if style.cssFloat gives you access to the current CSS float value of an element;
hrefNormalized: returns true when the browsed does not normalize href attribute values;
htmlSerialize: true when the browser serializes link elements when innerHTML is used;
leadingWhitespace: true if the browser preserves leading whitespace when innerHTML is used;
noCloneEvent: true if the browser does not clone event handlers when elements are cloned;
objectAll: equal to true when getElementsByTagName(“*”) returns all descendants;
opacity: true if a browser can properly interpret the opacity style property (IE still relies on alpha filters);
scriptEval: true when appendChild or createTextNode executes injected inline scripts;
style: returns true only when getAttribute(“style”) returns the inline style specified on an element;
tbody: true when browsers allow tables without tbody elements (IE adds the tbody element if you don’t explicitly add one to your HTML).

As you can see, many of these features won’t be used on day to day programming. However, if you’re a plug-in writer or if you intend to write Javascript code that isn’t browser specific, then these methods might help you in a couple of more uncommon scenarios.

I guess that one of things that might have bitten you in the past is the box model. Currently, you can resume the problem to IE being able to render HTML element’s boxes in a standard way or in the quirks mode way (so that it is compatible with previous versions of the browser). With the W3C box model, the width/height defines the width/height of the content while IE’s quirk mode uses the width/height values for defining the total size of the element’s box.

You’ll see no difference on sizes until you start using padding, margins or border widths. When you do that, you’ll notice that the in quirks mode the box will be fixed to the initial size specified through the width and height values). If you want to do your own calculations regarding the correct width and height and you need to make it work across several browsers, you can rely on this property for using the correct values.

cssFloat might also be useful when you need to know how to get to the float style of a specific element. Take a look at the next example:

<div>
    <div id="left">left</div>
    <div id="right">right</div>
</div>
<input type="button" id="change" value="Swap" />
<script type="text/javascript">
    $(function() {
        $("#change").click(function(evt) {
            var lft = $("#left")[0];
            var rgt = $("#right")[0];
            if ($.support.cssFloat) {
                lft.style.cssFloat = "right";
                rgt.style.cssFloat = "left";
            }
            else {
                lft.style.styleFloat = "right";
                rgt.style.styleFloat = "left";
            }
        });
    });    
</script>

The code shows how you can use the cssFloat property to change the initial floating applied to the element. Notice that I’m doing this only for demonstrating purposes because if this was a real app, I’d really use the css method (it would reduce the number of lines of code needed, which is always a good thing, right?).

Getting the href url is generally done through the href property. However, we’ve already seen in a previous post that most properties get their values from an attribute bag. In most cases, properties can be seen as a shortcut. However, that’s not the case of the href property. When you access the href property, you’ll always get the complete url. That might not happen if you access the value through the attribute bag. Take a look at the following snippet:

<a href="another.html">Another page</a>
<input type="button" id="show" value="show" />
<script type="text/javascript">
    $(function() {
        $("#show").click(function(evt) {
            var a = $("a")[0];
            alert($.support.hrefNormalized + " - " + a.getAttribute("href"));
        });
    });    
</script>

If you run this code in a IE 7 or below, you’ll notice that the browser normalizes the url you’ve passed to the href attribute. That doesn’t happen when you’re using IE8 or any of the other main browsers (I haven’t tested it in safari).

leadingWhitespace still produces different results when you compare IE with the other browsers. What this means is that IE8 still doesn’t respect leading whitespaces when you add content through the innerHTML property. Object cloning is also different in IE. The noCloneEvent property shows us that IE will clone event handlers when you clone an element (in other words, it returns false). That doesn’t happen in most of the other browsers. And the same thing happens for most of the remaining properties presented on the previous list (and that’s why I won’t go into details on all those properties).

At the beginning of this post I said that the great advantage of the support object was that it relied on feature detection. In practice, this means that the code won’t use the traditional navigator object for getting information about the browser. If you look at JQuery’s code, you’ll notice that it creates several dumb elements in order to initialize the properties of the support object. This is great because the results returned from this detection process are way more accurate than the ones you’ll get with the navigator object (just remember that most browsers allow you to set a custom user agent string!). If you’re interested in seeing how it’s done,then you’ll have to scroll until line 3114 of the JQuery’s JS file.

And that’s it for today. Keep tuned for more on JQuery.

JQuery: common “event pairs” helpers

luisabreu — Wed, 05 Aug 2009 09:48:45 GMT

There are certain scenarios where you handle events in “pairs”. For instance, I guess we’ve all written JavaScript code for handling mouse over and mouse out events (which, btw, is also commonly known as hovering). Take a look at the following snippet:

<div>
Mouse over turns green! Mouse out turns black...
</div>
<script type="text/javascript">
    $(function() {
        $("div").bind("mouseover", function() {
           $(this).css("color", "green");
        });
        $("div").bind("mouseout", function() {
           $(this).css("color", "black");
        });
});    
</script>

If you run the previous sample, you’ll see that putting the mouse cursor over will result in changing the div’s text color to green and removing it will turn it back to black. JQuery simplifies the code we need to write in these scenarios by introducing the hover method. Here’s how the code would look if we used that method:

<script type="text/javascript">
    $(function() {
        $("div").hover(
        function() { $(this).css("color", "green"); },
        function() { $(this).css("color", "black");});
});    
</script>

The hover method expects two parameters: the first function will be invoked when the mouse enters the target and the second will be called when the cursor leaves that target.

Besides this helper, there’s also the toggle method. This method receives two or more functions and will call each function one at a time for each click done over any of the container’s wrapped set elements. The next snippet keeps changing the text color of all divs for each click:

$(function() {
    $("div").toggle(
    function() { $(this).css("color", "green"); },
    function() { $(this).css("color", "red"); },
    function() { $(this).css("color", "blue"); },
    function() { $(this).css("color", "black");});
});

Notice that there are no restrictions to the number of functions you can pass to the toggle method (and you’ll typically pass at least two when using this method.

And that’s all for now. Keep tuned for more on JQuery.

JQuery: more on the triggerHandler method

luisabreu — Wed, 05 Aug 2009 09:14:10 GMT

In the previous post I’ve shown you some code on how to use the triggerHandler method. At the time, I said that events would bubble even though the docs say that they won’t. I based my conclusions on a small simple test I’ve written. ingmar added more information on a comment saying that if you have a more complex tree, you won’t get the “correct” bubbling. For instance, with the following structure:

<div>
    <p>This is some hidden content</p>
    <p>And more hidden content</p>
</div>

you’ll get the following bubbling: P->BODY->HTML. So, what’s happening here? Well, it’s simple: I was wrong. The fact is that the bubbling I was seeing was coming from my button’s click event and not from the triggered element. Let’s take another peek at the script code I’ve written:

<script type="text/javascript">
    $(function() {
        $("*").not("input").click(function(evt) {
            alert(evt.currentTarget.tagName + " clicked");
            return "hi";
        });
        $("#trigger").click(function() {
            $("p").trigger("click");
        });
        $("#triggerHandler").click(function() {
            alert($("p").triggerHandler("click"));
        });
    });
</script>

As you can see, we’re hooking up all the elements’ click event (excluding inputs) with an anonymous function that displays an alert message with the tagName of the current target element. Now, when I wrote the small sample, I concentrated on the P’s click event and this was what I saw:

P->BODY->HTML

Since my initial markup looked like this:

<p>This is some hidden content</p>
<p>And more hidden content</p>

I completely forgot that the click event of the button would also propagate through the tree until it reaches the top element. Notice that when you dispatch an event from within an existing handler, that handler will be “suspended” until that “new” event is completely dispatched. When that happens, the “previous” event that was in “stand by” wakes up and goes through its normal lifecycle. So, if I had written this code:

$("#triggerHandler").click(function(evt) {
    alert($("p").triggerHandler("click"));
    evt.stopPropagation();
});

it would have been obvious that there was no bubbling coming from the P’s click event that has been dispatched through that anonymous function. I guess that the moral of the story is that I should pay more attention to the samples I’m writing during my JQuery tests. Thanks go to ingmar for putting me in the right track. Keep tuned for more on JQuery.