Serialization

The .NET HttpCookie class stores multiple values in a single cookie by serializing them into a single string. For example, this code:

HttpCookie cookie = new HttpCookie("Cookie1");
cookie.Values["Val1"] = "1";
cookie.Values["Val2"] = "2";
cookie.Values["Val3"] = "3";
Response.Cookies.Add(cookie);

…will result in a cookie that looks like this:

Cookie1=Val1=1&Val2=2&Val3=3

Thus, we can see the HttpCookie serializes the Values property in a similar way to how parameters are encoded in query strings.

The JavaScript (for MS .NET and Mono)

Based on the example output Cookie1=Val1=1&Val2=2&Val3=3, we can work out some JavaScript code to generate it:

// Works with Microsoft .NET and Mono runtimes, with reservations.
var setMultiValuedCookie = function(name, values) {
    var valuePairs = [];
    for (var n in values) {
        valuePairs.push(n + "=" + values[n]);
    }
    var cookieValue = valuePairs.join("&");
    document.cookie = name + "=" + cookieValue;
};

This is more or less how the Microsoft .NET implementation of HttpCookie works. It also happens to be compatible with the Mono implementation (more on that below). The problem with this code is that it does not take into account edge cases, such as when a name or value contain the “=” or “&” characters. In those cases, things can get weird. For example, consider this code:

HttpCookie cookie = new HttpCookie("Cookie1");
cookie.Values["Val1"] = "1&Val2=2";
cookie.Values["Val3"] = "3";
Response.Cookies.Add(cookie);

Notice how only two values are set. Yet, when encoded by Microsoft’s HttpCookie class the resulting output is Cookie1=Val1=1&Val2=2&Val3=3, the exact same output that results the previous three value example in article. However, the cookie, when parsed by HttpCookie, will always be interpreted as having 3 values. This means that Microsoft’s .NET HttpCookie serialization scheme is ambiguous and care must be taken when using it with non-alphanumeric characters.

The JavaScript (just for Mono)

The Mono Project‘s HttpCookie class fares a lot better than it’s Microsoft counterpart. In the HttpCookie source, there is a nested CookieNVC class (NVC stands for NameValueCollection) with the serialization code in the overridden ToString method:

public override string ToString() {
    StringBuilder builder = new StringBuilder("");
    bool first_key = true;
    foreach (string key in Keys) {
        if (!first_key) { 
            builder.Append("&");
        }
        string[] vals = GetValues(key);        
        if (vals == null) {
           vals = new string[1] {String.Empty};
        }
        bool first_val = true;
        foreach (string v in vals) {
            if (!first_val) {
               builder.Append ("&");
            }
            if (key != null && key.Length > 0) {
                builder.Append (HttpUtility.UrlEncode(key));
                builder.Append ("=");
            }
            if (v != null && v.Length > 0) {
                builder.Append (HttpUtility.UrlEncode(v));
            }    
            first_val = false;
        }        
        first_key = false;
    }
    return builder.ToString();
}

Notice that in the Mono HttpCookie, the names and values are URL encoded in order to escape the “=” and “&” characters. This means that we can use “=” and “&” characters in the name and value of the Values property and they will be serialized unambiguously. To make our JavaScript work with the Mono HttpCookie class improvements, the name and value strings must be URL encoded using encodeURIComponent:

// Warning: Does not work well with the Microsoft .NET runtime.
var setMonoMultiValuedCookie = function(name, values) {
    var valuePairs = [];
    for (var n in values) {
        valuePairs.push(encodeURIComponent(n) + "=" + encodeURIComponent(values[n]));
    }
    var cookieValue = valuePairs.join("&");
    document.cookie = name + "=" + cookieValue;
};

And presto, we have a Mono-compatible verison of setMultiValuedCookie.

Conclusion

In this article we examined how the Microsoft and Mono versions HttpCookie class serialize multiple values into a single cookie. By looking at a sample cookies encoded by HttpCookie, as well as perusing the Mono HttpCookie source code, two JavaScript functions were written: setMultiValuedCookie, a function that serializes multi-valued cookies in manner compatible with both Microsoft and Mono .NET runtimes and setMonoMultiValuedCookie, a function that more robustly serializes multi-valued cookies but is only compatible with the Mono .NET runtime.

CoffeeDOM is intended as a natural evolution for JDOM developers. As such, there have been minimal changes to the API. CoffeeDOM adds support for Java 5 features like generics, enums, and covariant method return types, and reduces the amount of boilerplate required by making previously checked exceptions (like JDOMException) unchecked. In this article, I will briefly go over these changes.

(If you don’t want to bother with the article, you can skip right to the Google Code page or browse the Javadoc API documentation.)

Generic collections

JDOM makes heavy use of the Java Collections Framework, principally Lists and Iterators. Thus, in JDOM, to get a list of all child elements of an element, we do the following:

Element element = ...;
List<?> children = element.getChildren();
for (Object childObject : children) {
    // Cast :(
    Element child = (Element) childObject;
 
    // ...
}

See that pesky cast? How inconvenient. Another approach is to cast the List:

Element element = ...;
// Cast :(
List<Element> children = (List<Element>) element.getChildren();
for (Element child : children) {
    // ...
}

… but then we would need to either ignore a warning (not recommended) or add a @SuppressWarnings("unchecked") annotation. Neither is a desirable solution.

Fortuantely, CoffeeDOM comes to the rescue. In CoffeeDOM, all JCF classes like List, Collection, Iterable, etc. have appropriate generic parameters:

Element element = ...;
List<Element> children = element.getChildren();
for (Element child : children) {
    // ...
}

Enjoy the comfort of compile time type-checking.

Covariant method return types

In JDOM, in order to copy nodes, the built-in Object#clone() method is used:

Element element = ...;
Element clonedElement = (Element) element.clone();

Oh look, another silly cast. Fortunately, thanks to covariant method return types, CoffeeDOM eliminates this unneeded cast:

Element element = ...;
Element clonedElement = element.clone();

CoffeeDOM also removes the need for casting when using detach, setParent and getParent (in most cases).

Enums instead of int constants

This one is pretty straightforward. In JDOM, when we make a new Attribute, we can set the attribute type using an int constant like Attribute.CDATA_TYPE, Attribute.ENTITIES_TYPE, etc. Here’s a (contrived) example:

Element element = ...;
Attribute attribute = new Attribute("name", "value", 
        Attribute.UNDECLARED);
element.setAttribute(attribute);
// ...or just element.setAttribute("name", "value")

Unfortunately, modern IDEs have issues with int constants (they can’t tell which ones go with a particular method). Moreover, operations like iterating through the enum or converting from a string to a constant, are more difficult and messy.

CoffeeDOM remedies this by using Java 5′s enum structure. The above code turns into something rather similar:

Element element = ...;
Attribute attribute = new Attribute("name", "value", 
        Attribute.Type.UNDECLARED);
element.setAttribute(attribute);

…but with the added plus that we can do things like:

// Cycle through the constants.
for (Attribute.Type type : Attribute.Type.values()) {
    ...
}
 
// Get a constant from a string.
Attribute.Type type = Attribute.Type.valueOf("UNDECLARED");

Improved for-each compatibility

In Java 5, Sun juiced up the for loop by enabling it to cycle through Iterable instances. Unfortunately, since JDOM predated this enhancement, some methods return for loop unfriendly Iterator instances. This results in a lot of unneeded boilerplate:

Element element = ...;
Iterator<?> it = element.getDescendants();
while (it.hasNext()) {
    Content descendant = (Content) it.next();
    // ...
}

CoffeeDOM corrects this by making getDescendants return an Iterable instance instead, allowing it to be used with the for loop:

Element element = ...;
for (Content descendant : element.getDescendants()) {
    // ...
}

This change only affects classes implementing the JDOM Parent interface.

Unchecked exceptions

Constantly having to write exception checking code in Java can obfuscate code, especially if you’re just only re-throwing or logging checked exceptions to make the compiler happy. Consider this example in JDOM:

try {
    SAXBuilder builder = new SAXBuilder();
    Document document = builder.build("path/to/file.xml");
    XMLOutputter outputter = new XMLOutputter();
    outputter.output(doc, System.out);
} catch (IOException e) {
    e.printStackTrace();
} catch (JDOMException e) {
    e.printStackTrace();
}

To address this issue, CoffeeDOM changes CoffeeDOMException (the CoffeeDOM equivalent to JDOMException) to an unchecked exception. This reduces some of the exception noise:

// Ahhh... fewer checked exceptions.
try {
    SAXBuilder builder = new SAXBuilder();
    Document document = builder.build("path/to/file.xml");
    XMLOutputter outputter = new XMLOutputter();
    outputter.output(doc, System.out);
}  catch (IOException e) {
    e.printStackTrace();
}

Now with less noise

CoffeeDOM was designed to be an evolutionary step forward for JDOM. The main design goal of CoffeeDOM was to build on the excellent JDOM API by using modern Java features like generics, enums and covariance method return types. The result is better compile-time checking, fewer casts and less annoying exception handling.

Where do I get it? When can I use it?

CoffeeDOM is available now via Google Code as a downloadable JAR file or a Mercurial repository. It is also available from Maven Central using the following dependency markup:

<dependency>
  <groupId>org.cdmckay.coffeedom</groupId>
  <artifactId>coffeedom</artifactId>
  <version>1.0.0</version>
</dependency>

Learn more

As CoffeeDOM is brand new, there isn’t a whole lot of documentation available beyond the Javadoc reference and this article. However, since CoffeeDOM shares a similar API to JDOM, any JDOM tutorial can make a good starting point. See the JDOM documentation page for links to several tutorials that can get you started.

If code samples are your thing, the CoffeeDOM Mercurial repository has a CoffeeDOM-samples project that contains all the JDOM sample projects updated for CoffeeDOM.

As fate would have it, I have had the good fortune to have extensive experience with both C# and Java. While many articles will list things a programmer misses from C# while coding in Java (properties, LINQ, reified generics, type inference, named and optional parameters, closures, continuations), this post intends to look at things a Java programmer might miss while coding in C#.

1. Method return type covariance

Covariant method return types are one of the lesser known Java features (see Section 8.4.5 in the JLS). Basically, Java allows you to narrow the return type of a method when overriding it in a sub-class. For example:

public class Foo {
}
 
public class SubFoo extends Foo {
}
 
public class Bar {
    final Foo foo = new Foo();
    public Foo getFoo() {
        return foo;
    }
}
 
public class SubBar extends Bar {
    final SubFoo subFoo = new SubFoo();
 
    @Override
    public SubFoo getFoo() {
        return subFoo;
    }
}

Although situations where this is needed are seldom, it is a nice feature to have when you need it. An good example of its usage is in the Apache Wicket framework. All pages in Wicket typically derive from the WebPage class. Thus, when you want to access information from a custom Wicket session you need to do something like this:

public class UserInfoPage extends WebPage {
    public UserInfoPage() {
        FooSession session = (FooSession) getSession();
        String userName = session.getUserName();
        ...
    }
}

However, if you add a class above UserInfoPage called FooPage, you can use a covariant return type to eliminate the unsightly cast:

public class FooPage extends WebPage {
    @Override
    public FooSession getSession() {
        return (FooSession) super.getSession();
    }
}
 
public class UserInfoPage extends FooPage {
    public UserInfoPage() {
        FooSession session = getSession();
        String userName = session.getUserName();
        ...
    }
}

To me this is preferable to adding another method called getFooSession(). Having two methods can be confusing to a future maintainer (do I want getFooSession() or getSession()? What’s the difference?) and needlessly clutters your IDE’s code completion.

There is no equivalent in C#, short of adding a method. Will C# ever support such a feature? It’s hard to say, but probably not anytime soon. There has been a request for covariant method return types since 2004. Microsoft response then was:

We hear this request a lot. We’ll consider it for the next release.

After seven years and three major C# releases, it looks like they’re still considering it.

2. Class-like enums

This one is not a big surprise, as it is typically mentioned as one of the few things that Java has done better that C#. In C#, enums are basically glorified integral types. As such, they can’t contain any extra data without using attributes. While attributes are nice, accessing them requires quite a bit of boilerplate.

public enum MotionType {
    Stationary,
    Walking,
    Running,
    [Description("Time Travelling")],
    TimeTravelling
}
 
...
 
MotionType type = MotionType.TimeTravelling;
var description = type
    .GetType()
    .GetField(type.ToString())
    .GetCustomAttributes(typeof(DescriptionAttribute), false)
    .Cast<DescriptionAttribute>()
    .First()
    .Description;
Console.WriteLine(description);

A further restriction of C# enums if that they can’t be used as a generic constraint. For example, the following code would not compile:

public class Monster<TMotionType> where TMotionType : enum {
}

According to C# MVP Jon Skeet, this is not a restriction of the CLR, but is actually a restriction of the Microsoft C# compiler. The best you can do to work around this is to use the broader constraint where : struct, or the Unconstrained Melody library.

Java enums, on the other hand, are specialized classes. Like C# enums, Java enums can be used with switch statements and be converted to integral types. However, Java enums go far beyond these simple uses. Java enums can have instance fields, instance methods and even per-constant methods. Java generics can also be constrained to take only enums.

Here’s how the MotionType enum could be written in Java (notice how easy it is to get the description in this case):

public enum MotionType {
    STATIONARY("Stationary"),
    WALKING("Walking"),
    RUNNING("Running"),
    TIME_TRAVELLING("Time Travelling");
 
    public final String description;
    MotionType(String description) {
        this.description = description;
    }
}
 
...
 
MotionType type = MotionType.TIME_TRAVELLING;
System.out.println(type.description);

This is just scratching the surface of Java enum capabilities. I highly recommend reading Chapter 6 of Effective Java or the Oracle enum documentation.

3. Anonymous inner classes

This is another it’s-useful-when-you-need-it feature of Java that C# mostly addresses with events and delegates. The most common situation for anonymous inner classes in Java is for listeners:

Widget widget = new Widget() {
    public void onInteraction(WidgetState state) {
        ...
    }
};

In C#, this is handled using events and delegates:

Widget widget = new Widget();
widget.Interaction += state => {
    ...
};

The C# approach is superior in most cases. There’s far less clutter and it’s a lot easier to add listener support to a class in C#. Furthermore, since it’s a language feature, you can count on it being more or less the same everywhere. However, it’s not without drawbacks. You’ll notice in the previous Java example, we can guarantee that there is only one listener. Furthermore, if we declare onInteraction as abstract, we can also ensure that all concrete implementations of Widget have an onInteraction handler. The event/delegate approach as written cannot make the same guarantees.

Since C# does not support anonymous inner classes, the best we can do to emulate them is something like this:

Widget widget = new Widget(state => {
    ...
});

…or, if we wanted to make it a little more clear, we could use named parameters:

Widget widget = new Widget(onInteraction: state => {
    ...
});

Locally scoped final/readonly variables

In the book Code Complete 2, Steve McConnell recommends that you use final keyword whenever possible. The justification for this being that less mutable code is easier to keep track of mentally and less likely to be accidentally modified. Although the practice of making everything final can be weird at first, you eventually become so used to using final that you start to feel a little bit exposed whenever a variable isn’t marked final.

C# has a nearly equivalent keyword to final: readonly. However, for some reason, readonly is only usable on the field level. In the local scope, there is no direct equivalent to final in C#. The best you can do is use const, but this only works with compile-time constants, so

const string foo = Foo.getString();

…won’t work.

Conclusion

In this article we looked at four features of Java that lack direct C# equivalents: covariant method return types, class-like enums, anonymous inner classes and locally-scoped final/readonly keywords. C# is often thought of as a “better Java”. However, as this article has shown, this is not true. Java may not have as many bells and whistles as its newer cousin, but it still offers some compelling features that may never find their way into C#.

In this article we will look at how to implement non-short-circuited or “eager” versions of the JavaScript boolean operators && and ||.

As mentioned earlier, most programming languages have short-circuited boolean operators. Short-circuited operators are possible due to certain properties of conjunctions and disjunctions in Boolean logic. In Boolean logic, for a conjunction x1 && x2, if the first argument evaluates to false, the whole expression will be false, regardless of what the other argument evaluates to. Similarly, for a disjunction x1 || x2, if the first argument evaluates to true, the whole expression will be true, regardless of what the other argument evaluates to.

For a more concrete example, consider this snippet of JavaScript:

var str = null;
if (str !== null && str.length > 0) {
    alert("String is not null or empty");
} else {
    alert("String is null or empty");
}

If executed by a browser, this snippet will alert String is null or empty. It does not throw a TypeError when it hits str.length because str.length is never evaluated. The JavaScript interpreter skips it once it sees str !== null evaluates to false. This is an advantage of short-circuiting.

What if we don’t want to short the circuit?

Although short-circuiting is almost always what we want, there are rare instances where we may want to have non-short-circuited or eager evaluation. Consider this example using jQuery:

var validate = function(element) {
    if (element.val() === "") {
        element.addClass("invalid");
        return false;
    } else {
        element.removeClass("highlight");
        return true;
    }
};
 
var form = $("#comments-form");
var name = form.find("#name");
var email = form.find("#email");
var comments = form.find("#comments");
 
form.submit(function() {
    return validate(name) && validate(email) && validate(comments);
});

In this example, we are validating a comments form for a website. In order to do that, we use a validate function to verify that an HTML input is not empty. If it is empty, then we add a CSS class to highlight it and then return false to indicate validation failed. Conversely, if it’s not empty, we remove the highlight CSS class and then return true to indicate validation succeeded.

Unfortunately, this code will only highlight the first field that fails validation. Why? Because the && short-circuits the first time it evaluates an argument to false and thus the rest of the validations will not be executed.

So how do we force them run? Well, if we were using a language like Java or C#, we would simply use the & and | operators, which are eager versions of the short-circuited && and || operators. Unfortunately, although JavaScript does provide the & and | operators, they return numeric (0 or 1) instead of boolean (true or false) results.

Eager boolean operators in JavaScript

(Aside: In the following section I use the arithmetic operators * and + to emulate eager boolean operators. You can just as easily use the bitwise operators & and | in their place. The only reason I used the arithmetic operators was because I thought they would make for a more interesting article).

So we’ve established that JavaScript has no eager boolean operators. JavaScript does, however, offer us two arithmetic operators that can almost accomplish our goal: * and +. These operators, in conjunction with JavaScript’s type coercion semantics, produce the following truth tables when fed all combinations of true and false (&& and || are shown for comparison):

In the table you’ll notice that * and + operators yield almost identical truth tables to the && and || operators, with the exception being that the short-circuited operators produce boolean values (true and false) while the arithmetic operators produce integer values (0, 1 or 2). Moreover, unlike the boolean operators, the arithmetic operators are eager.

That means that, in order to use the arithmetic operators to implement eager boolean operators that produce the exact same results as the built-in boolean operators, we need to map 0 to false and map any non-0 values to true. Fortunately, this is exactly what JavaScript’s type coercion does when forced to coerce a number into a boolean, which can be accomplished by prefixing the number with two ! operators.

And there we have it. We’ve implemented eager boolean operators using JavaScript’s type coercion, the arithmetic operators * and + and the logical not operator !.

Conclusion

Boolean operators in most programming languages are short-circuited: they evaluate their terms left to right and stop (i.e. short-circuit) once they can definitively determine the truth value of expression. This behaviour is usually what we want. However, in some rare cases, we want to evaluate all terms in a boolean expression. Such an operator is called an eager boolean operator.

Although JavaScript does not provide eager boolean operators, they can be emulated by using a combination of JavaScript’s type coercion semantics and arithmetic and logical operators.

This article assumes you have read the first part of this series.

Before we start, we should take a step back and consider what we’re about to do. Our Searcher app has three parts:

• the client-side jQTouch UI,
• the client-side jQuery AJAX calls,
• the server-side PHP script (that could easily be backed by a database)

At this point we have finished the jQTouch UI. However, instead of immediately moving on to writing the jQuery AJAX calls, let’s start with the PHP script instead. This will help us understand our AJAX calls when it comes time to write them.

The PHP Script

Since our PHP script will be performing a search, let’s create a file called search.php and add a single line of boilerplate:

<?php

There’s no need for an end tag. In fact, in files containing only PHP, it is recommended that you do not include an end tag:

For files that contain only PHP code, the closing tag (“?>”) is never permitted. It is not required by PHP, and omitting it prevents the accidental injection of trailing white space into the response.

Our Searcher app needs to search for something, so let’s pretend it’s an interface for a music player and we’re searching for songs. In order to express that idea into PHP code, we need the following elements:

• a Song class to hold the artist name and the title,
• an array holding a bunch of Song objects,
• a function for searching the Song array,
• a way to get a search value from the AJAX request,
• a way to set the MIME type to JSON,
• a way to encode our Song array as JSON

First, we’ll need a class to hold the songs (place this starting at line 3 in search.php):

3
4
5
6
7
8
9
10
11

class Song {
    public $artist;
    public $title;
 
    public function __construct($artist, $title) {
        $this->artist = $artist;
        $this->title = $title;
    }
}

Let’s break it down for those not familiar with PHP classes:

• at line 3, we declare the class name
• at lines 4-5, we declare two public fields to represent the artist’s name and the title of the song,
• at lines 7-10, we declare the class constructor that we use to initialize the two fields of a Song object

Now that we have a way to model songs in our PHP script, we need to make an array of some dummy songs that we can query using AJAX:

13
14
15
16
17
18
19

$songs = array(
    new Song("Weezer", "Say It Ain't So"),
    new Song("Weezer", "Undone"),
    new Song("Cake", "Meanwhile, Rick James..."),
    new Song("The Stars", "Ageless Beauty"),
    new Song("Roy Orbison", "In Dreams")
);

Now we have something of a faux database setup. How will we search it? Why, with a search function, of course! Let’s write that now:

21
22
23
24
25
26
27
28
29
30
31
32
33
34

function search($songs, $value) {
    if (empty($value))
        return $songs;
 
    $matches = array();
    foreach ($songs as $s)
    {
        $matchArtist = stripos($s->artist, $value) !== false;
        $matchTitle = stripos($s->title, $value) !== false;
        if ($matchArtist || $matchTitle)
            $matches[] = $s;
    }
    return $matches;
}

So what does this function do? Let’s take a look line-by-line:

• at lines 22-23, we check to see if the search value is empty (i.e. an empty string or null). If that’s the case, then we just return all the songs
• at line 25, we declare the $matches array. This will contain all the songs that match the search value $value
• at line 26, we use a foreach loop to iterate through all the Song objects in the $songs array
• at lines 28-29, we check to see if the artist name or song title contain the search value $value
• at line 30-31, we add the Song object to the $matches array if it matches the artist name or song title
• at line 33, we return whatever matches (if any) we have found

Ok, so now we have a Song class, an array of Song objects, and a function that searches that array. What’s left in our PHP script? Well, as it stands, we have no way to interface with it. What we need to do now is have some sort of way to respond to the AJAX GET request that our Searcher app will send. To do that, we harness the awesome power of the $_GET superglobal:

36
37

$value = $_GET['value'];
$matches = search($songs, $value);

On the first line, we extract “value” parameter from the $_GET superglobal and assign it to the $value variable. The second line runs our search function on the $songs database and searches for songs that have an artist or title that contains the $value string.

We’re almost there! At this point we’ve managed to get an array of Song objects that match the passed search value. All we need to do now is return that PHP array of objects as a JSON-encoded array of objects. Let’s do that now:

39
40

header('Content-Type: application/json');
echo json_encode($matches);

The first line sets the the MIME type of an HTTP response. MIME types are a sort of meta data that is used to describe what sort of content is being returned. In this case, we are telling jQuery (or whatever client that issued the request) that we are returning content that is JSON formatted. The second line is a built-in PHP function that converts PHP types into a string containing their JSON counterparts. Basically, it allows us to encode our PHP objects into JavaScript and allow us to access them in a nearly identical way:

// PHP
array(
    new Song("Artist 1", "Title 1"),
    new Song("Artist 2", "Title 2")
);
 
// Becomes... (after json_encode)
// JavaScript
[
    { artist: "Artist 1", title: "Title 1" },
    { artist: "Artist 2", title: "Title 2" }
];

And we’re done the PHP script! If we want to test it, we can load execute the PHP file on our server and try different search values. For example, entering this URL should return a JSON array with two Song objects:

// URL
http://example.com/jQTouch-ajax-search/search.php?value=Weezer
 
// Response
[{"artist":"Weezer","title":"Say It Ain't So"},{"artist":"Weezer","title":"Undone"}]

The jQuery AJAX calls

The finish line is now in sight. We’ve successfully written our jQTouch UI and our PHP script. The last thing we need to do is write some jQuery AJAX calls to execute our search and load the results into our UI. In order to do that, we need to do the following:

• listen for the submission of the search form in the jQTouch UI
• when the submission happens, get the search value from the form and set it as a parameter in an AJAX call to search.php
• register a callback that will populate the jQTouch search results when the AJAX call completes

Let’s start with listening for the submit event on the search form. First, we’ll need to create a new JavaScript source file search.js and fill it with the following boilerplate:

(function($){
 
    // Put code here.    
 
})(jQuery);

What this boilerplate does is give our JavaScript script its own context so that can minimize leaking variables into the global JavaScript namespace. It also gives us access to the jQuery object in the convenient $ form, regardless of whether or not “no conflict” mode is enabled.

Recall in part 1 we defined an HTML search form that looked like this:

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

<form id="search" action="">
    <div class="toolbar">
        <h1>Search</h1>
        <a href="#" class="back">Back</a>
    </div>
    <ul class="rounded">
        <li><input type="text" name="search-text" placeholder="Search" id="search-text" /></li>
    </ul>
    <ul class="edgetoedge" id="search-results">
        <li class="sep">Results</li>                
    </ul>
</form>

Note that on line 1 we defined the id of the form as search. We’ll use that to find the form and register a handler for its submit event so that we can take action when someone tries to perform a search using the jQTouch UI.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

(function($){
 
$(function(){
 
    $("#search").submit(function(event, info) {
        var text = $("input[id=search-text]", this);
        text.blur();
 
        var results = $("#search-results", this).empty();
        results.append($("<li>", {
            "class": "sep",
            text: 'Results for "' + text.val() + '"'
        }));
 
        $.get("search.php",
            { value: text.val() },
            function(data) {
                $.each(data, function(i, song) {
                    var str = song.artist 
                        + " - "
                        + song.title;
                    $("<li>")
                        .text(str)
                        .appendTo(results);
                });
            }
        );
 
        return false;       
    });
 
});
 
})(jQuery);

There’s a lot there, so let’s break it down line-by-line:

• starting at line 3 and ending at line 32 we have the jQuery ready handler which is run once the DOM has finished loading
• starting at line 5 and ending at line 30 we bind a submit event handler to the submit event for the #search form
• at lines 6-7, we retrieve the search-text element, assign it to a variable (for later use on line 16), and then blur (i.e. deselect) the element so that the iPhone keyboard will go away
• at lines 9-13, we clear any previous items in the list that may be hanging around from a previous search and then load in a new separator (“sep”) that contains the search value
• at line 15-27, we perform our AJAX GET request to search.php with the value of the search text field as our value parameter (line 16) and a callback that adds the results to the list (lines 17-26)
• finally, at line 29, we return false to prevent the default form behaviour (i.e. submitting the form) from being carried out

And we’re done. All we need to do now and include search.php in the header of index.html so that it’ll be run:

12

<script src="search.js" type="application/x-javascript" charset="utf-8"></script>

Conclusion

In this, the final installment of How to do an AJAX search with jQTouch, we finished off the example application we started in the first part of this series.

In part 1, we covered building a UI using jQTouch. In part 2, we helped visualize our problem by pretending that we were writing a front-end UI to a server-side music player. To do that, we jumped into server side programming with PHP to write a script to serve us JSON-encoded Song objects. Once we had that setup, we moved back into JavaScript. In order to make use of the PHP script, we wrote a jQuery handler to respond to a jQTouch form submission. The handler, once triggered, issued an AJAX call to the PHP script to pull down the appropriate Song objects for display in our UI.

What Now?

With respect to the goals of this tutorial, nothing. However, if you want to pimp up the application a bit more, some things you could do are:

• Add genres and albums to the PHP Song object and then make the jQTouch UI menu have two additional options: Genres and Albums
• Try to make a Now Playing sub-menu that is activated when a Song is picked from the Search screen

Source

The source code I have written in this article is public domain, and you are free to do what you will with it. Here is a zip of the source, along with the required jQTouch source. It should work pretty much right out of the box.

In this article, we will look at how jQuery animation queues work, how to create and manipulate them, and how to use them in a meaningful way.

Queue fundamentals

Each element has its own set of queues. For example, if we execute this code:

$("#foo").fadeOut();
$("#bar").fadeOut();

The elements #foo and #bar will fade out more or less simultaneously. This is because they have their own fx queues. However, if we execute the code:

$("#foo").fadeOut();
$("#foo").fadeIn();

The element #foo will fade out and then fade in, instead of getting stuck in some sort of tug of war for opacity. This is because they are both using the fx queue of #foo, and thus run one after another.

Creating and manipulating queues

jQuery provides 5 commands for interacting with queues, which are summarized in the table below.

So how do we create a queue? We simply use a queue command that takes a queueName argument. For example, we can use the queue command and add a function to queue. Let’s try it first with the regular fx queue.

$("#foo").queue(function(next) {
    alert("I was queued!");
    next();
});

When this code is run on a page with a #foo element, it immediately emits an alert saying “I was queued!”. This is because the fx queue will dequeue elements right after they’re added. We can verify that the fx queue is being used by queuing an animation before our alert.

$("#foo").fadeOut().queue(function(next) {
    alert("I was queued!");
    next();
});

When this code is run the #foo element fades out and then an alert is shown. Now let’s try it with a custom queue.

$("#foo").queue("custom", function(next) {
    alert("I was queued!");
    next();
});

Nothing happens. Why? Because unlike the default fx queue, custom queues are not dequeued immediately. They require an explicit dequeue call to get them started.

$("#foo").queue("custom", function(next) {
    alert("I was queued!");
    next();
})
.dequeue("custom");

What’s the point?

At this point you may be wondering, what’s the point? Why would I ever need to use queues? The answer is: to implement animation time-lines. Imagine you’re making a game and you want to have an object float up wards for 2000 milliseconds. Furthermore, you would like said object to stay completely opaque for 1000 milliseconds before slowly becoming completely transparent over the remaining 1000 milliseconds. This time-line is shown below in tabular form (assuming that the object starts at top: 100px).

At first glance, it appears that the animate command could take care of this:

$("#object").animate({opacity: 0, top: "-=40"}, {duration: 2000});

Unfortunately, this code will fade the object out over 2000 ms, instead of waiting 1000 ms then fading out over the remaining 1000 ms. delay can’t help either, because it would delay the upward floating as well. At this point we can either fiddle with timeouts or, you guessed it, use queues.

1
2
3
4
5
6
7
8
9

$("#object")
.delay(1000, "fader")
.queue("fader", function(next) {
    $(this).animate({opacity: 0}, 
        {duration: 1000, queue: false});
    next();
})
.dequeue("fader")
.animate({top: "-=40"}, {duration: 2000})

In this example, we have two queues: the fx queue and the fader queue. First off, we setup the fader queue. Since we want to wait 1000 ms before fading, we use the delay command with 1000 ms (line 2). Next, we queue up an animation that fades the object out over 1000 ms (line 3-7). Pay close attention to the queue: false option (line 5) we set in the animate command. This is critical, as it ensures that the animate doesn’t use the fx queue. Finally, we unleash the queue using dequeue and immediately follow it with a regular fx-using animate call to move the top of the object up 40 pixels (line 9).

Conclusion

jQuery makes use of implicit animation queues behind the scenes whenever you run an animation. By taking advantage of jQuery queue commands, custom animation queues can be constructed that enable certain complex animation stuctures, like time-lines, that would be otherwise impossible without using intervals or timeouts.

Recently, in an effort to better understand how the Biomorph program worked, I decided to implement it myself in JavaScript using the HTML5 canvas element. The result of this endeavour can be found here. Read more to learn how to use the Biomorph program.

How do I work it?

The user interface contains 9 biomorphs arranged in a 3×3 grid. This is a biomorph generation. The centre the grid (with the blue border) contains the parent biomorph. The parent is the biomorph that the remaining 8 children biomorphs are based on. The children biomorphs are created by slightly mutating each of the eight genes in a biomorph.

In order to evolve a biomorph towards a certain goal, look at the 8 child biomorphs and select the one that is closest to looking like the biomorph you are aiming for. For example, if you’re trying to make a bat biomorph, pick the biomorph that looks most like a bat. Once you have a chosen a biomorph, click it to generate a new generation of biomorphs based on it.

If you choose the parent biomorph, you will simple be regenerating the child generation. However, since each gene can move in two directions, you have 16 possible children for each parent. Thus, if you are unhappy with your choice of children, you can try clicking the parent biomorph again to get one of the 8 other child biomorphs you haven’t seen.

Writing a simple game engine using the DOM and JavaScript poses some interesting problems that are atypical to regular website development. In this article I will discuss a few of the problems that I encountered while writing Webble and how I solved them.

Tracking Mouse Movement

In Wezzle, there is a selector that follows around the mouse cursor. This was fairly easy to implement in Java, as having a mouse movement listener isn’t too costly. In JavaScript, however, listening to the mousemove event is very expensive. In fact, listening to mousemove slows down the browser window so much that JavaScript animations become unusable. This is fine if your game does not animate while you listen to mouse movements. Unfortunately, with Webble, this was not the case. I needed to be able to follow the cursor at all times.

What was the solution? Webble has a 8×10 grid called the “board” (see image below). Each board cell can contain a tile. Overlayed on that board is a selector centered on whatever board cell the mouse cursor is on. Thus, Webble only needs to know when the mouse moves over a new board cell. This means that instead of using the mousemove event, I could instead use an invisible 8×10 grid of divs and listen for their less expensive mouseover event. This solution ended up working extremely well, allowing me to easily keep track of the mouse while simultaneously running animations.

Animation

Animation in Webble was quite painless, thanks to jQuery. For most animations, it was as easy as setting the correct parameters for the animate function. In particular, there were some situations were I needed animations to run in lockstep. In Webble, when you get a line, all the tiles in that line must animated away together. Thus, doing something like this…

// Gets all the line tiles on the board.
var tiles = board.findLineTiles();
 
// Get all the underlying DOM elements.
var elements = $(tiles.map(function(tile) { 
    return tile.element()[0]; 
}));
 
// Fade out the elements.
tiles.fadeOut(500, function() {
    // Remove tiles from internal board structure.
});

…would not work very well and would be inefficient. Why? Because if I had, say, 10 tiles to animate, jQuery would create 10 tile animations. This wasteful. Moreover, since they’re independent animations, there’s no guarantee they will be moving the same amount each animation step. This visual disparity is exacerbated when the JS engine lags.

Fortunately, the jQuery animate function provides a convenient step callback function that allows you to animate many elements in lockstep. As a result, the code above can become a single animation that looks like this:

// The elements to animate in lockstop.
var elements = ( ... same as above ... );
var elementsTail = elements.slice(1);
elements
    .eq(0)
    .animate({opacity: 0}, {
        duration: 500,
        step: function(now, fx) {
            elementsTail.css(fx.prop, fx.now);
        },
        complete: function() {
            // Remove tiles from internal board structure.
        }
    });

Audio

The Wezzle game has several sound effects that need to play at specifc times (i.e. when a tile is inserted, when a line is removed, etc.). Webble features some experimental sound support via the HTML5 audio element. Unfortunately, like HTML5 video, not everyone can agree on a format. Firefox supports Vorbis. Safari (and Safari Mobile) supports MP3. Chrome supports both. IE supports none (until IE9, in the distant, distant future). Thus, in order to support sounds across all modern browsers I needed to make both Vorbis and MP3 versions of all the sound effects. This is a minor inconvenience that could have been avoided if Apple just played nice and included Vorbis support, at the very least on desktop Safari.

Other than that issue, HTML5 audio is pretty nice to work with. All it takes to play a sound is:

var lineSound = new Audio("sounds/line.ogg");
lineSound.play();

This is a cinche compared to the hoops that need to be jumped through to get decent sound in Java. Although HTML5 audio still has a little bit further to go, I think it has a happy future in HTML5.

Conclusion

Writing games purely in HTML, CSS and JavaScript is easier than it ever has been thanks to wonderful libraries like jQuery and next generation technologies like HTML5. Although clever hacks are still required to make everything work together across browsers, I firmly believe that HTML/CSS/JavaScript combo will be a viable browser game platform in the near future.

Let’s start with a question: how does WordPress associate templates? The answer: as a secret custom field. What’s a custom field, you ask? They’re those useful little suckers under the content area in the WP editor:

But if the template is a custom field, you ask, then how come I don’t see it down there? Well, I just said they’re secret. After poking around WP database, I discovered the template for a page is determined by the custom field name _wp_page_template. My suspicion is that anything with the prefix _wp is hidden from the WP admin area and therefore secret.

Harnessing the awesome power of custom fields

On the bright side, even if you can’t see the _wp_page_template in the custom fields area, I can assure you it’s still there. And if it’s there, you can use it in any of your nefarious schemes.

Query_posts provides 3 parameters relating to custom fields: meta_key, meta_value, and meta_compare. With those in mind, imagine you have a template called Profile (profile.php), and you want to exclude any page that is a Profile from our query. In order to do that, you’d would make a query_posts call like so:

query_posts(array(
    'post_type' => 'page',
    'meta_key' => '_wp_page_template',
    'meta_value' => 'profile.php',
    'meta_compare' => '!='
));

The main thing to note here is that the template is identified by the name of the PHP file (profile.php) and not by the the name of template (Profile).

Wrap-up

Filtering your query_posts query by template is as easy as filtering by any custom field. No plugin required. Just remember: use the PHP file name as the template identifier, not the template name.

Consider a simple interface for making objects comparable:

interface IComparable {
     public function compareTo($object);
}

Normally, in Java and C# (before 4.0) the only way to implement this interface would be to make a carbon copy of the method signature (save for the name of the parameter) and then fill in the method body.

class NetString implements IComparable {
     public function compareTo($object) {
          ...
     }
}

This satisfies the interface requirements because we need to have a method that responds to a method named compareTo with a single argument. However, things get interesting when we introduce optional parameters. That’s because we can write a method signature that is different from that found in the interface but still satisfies the requirement that the method have the correct name and accept only 1 parameter.

How is that possible? Well, imagine we wanted our NetString class to optionally ignore case when comparing:

class NetString implements IComparable {
     public function compareTo($object, $ignoreCase = false) {
          ...
     }
}

Notice how we slipped in another (optional) argument $ignoreCase? Does this code still satisfy the IComparable interface? Absolutely. Why? Because we can still call compareTo($object) in a meaningful way, and that’s all the matters.