If you’ve ever looked at the jQuery animate docs at api.jquery.com you might have noticed that one of the optional arguments you can define is step which is defined as:

A function to be called after each step of the animation.

…and that’s it. If you search for “step” on the page, you won’t see another mention of it.

Fortunately, a quick search on Google for “jquery animate step” will yield the jQuery 1.2 release notes that sheds a bit of light on the step function:

You can now extend jQuery animations with a function that is fired on every step of the animation that changes the style of the element being animated. It can be extended for specific css properties, or even to create a custom animation type.

For example, you can pass in an extra step function to .animate() to perform actions like animation synchronization.

The release notes also contain a code sample:

$("#go").click(function(){
    $(".block:first").animate({ left: 100 }, {
      duration: 1000,
      step: function(now, fx){
        $(".block:gt(0)").css("left", now);
      }
    });
});

So now we know the arguments step takes: now and fx. We can also tell from the code that now contains the value being animated. fx, however, is still a bit mystery. We can solve that mystery by running the above code in Firebug, setting a break point when the step function is called, and then inspecting the fx and now objects. Here are the results of that operation:

There were a couple more attributes (most of them functions) that I did not include because I either didn’t think they’d be useful or I didn’t really know what they did. If you need to know what those do, I suggest Firebugging up your code and taking a look yourself

Cascading Style Sheets (CSS) is a style sheet language used to describe the presentation (that is, the look and formatting) of a document written in a markup language.

If that blurb were written about JSS, it’d sound a little like this:

JavaScript Style Sheets (JSS) is a style sheet language used to describe the presentation (that is, the look and formatting) and functionality of a document written in HTML.

In this article, we will look at the syntactic structure of a JSS stylesheet. We will also talk briefly about including JSS stylesheets in your HTML documents.

At this point, some people may be wondering: aren’t we mucking up CSS by combining functionality and presentation in the same place? This is a valid concern. However, just because we can combine presentation and functionality in JSS, doesn’t necessarily mean we should. A good JSS site will have two or more JSS stylesheets: one for JSS styles (if they are needed) and one for JSS event properties. JSS event properties will be covered in a future article.

Syntactic Structure

Let’s get back to the CSS/JSS connection. What do people do with CSS? They write stylesheets. More specifically, they write rules. In JSS, we write rules too. In fact, we write them in a very similar format to CSS, although with some important differences owing to the fact that JSS stylesheets are actually JavaScript programs. Here’s the basic format of a CSS stylesheet:

rule-selector-a
{
  property-a: value-a;
  property-b: value-b;
  ...
}
 
rule-selector-b
{
  property-a: value-a;
  property-b: value-b;
  ...
}
 
...

In JSS, we use pretty much the same format, with the differences being the addition of boilerplate code (1), quoted selectors with colons (2), underscores instead of dashes in property names (3), quoted values with commas (4) and commas between rules (5). The JSS format is shown below:

$.jss.declare({ // (1)
 
"rule-selector-a": // (2)
{
  property_a: "value-a", // (3) and (4)
  property_b: "value-b",
  ...
}, // (5)
 
"rule-selector-b":
{
  property_a: "value-a",
  property_b: "value-b",
  ...
},
 
...
}); // (1)

Let’s talk a bit about each of these difference:

1. Boilerplate code. This is an unfortunate side effect of having to use JavaScript to extend CSS. Fortunately, it’s the same for each JSS stylesheet, so it’s not too much of a hassle to remember.
2. Quoted selectors with colons. Since the selector portion of a JSS rule is a string, it must be represented in JSS as a JavaScript string. All strings in JavaScript must be either single-quoted (as in ‘Hello!’) or double-quoted (as in “w00t w00t”). The colon following the selector is a necessity as internally, JSS selectors act as keys in a JavaScript object. A JSS selector may be any valid jQuery selector.
3. Underscores instead of dashes in property names. This is not strictly true, although using underscores instead of dashes is the recommended way of representing JSS properties. Consider, for example, the font-family property from CSS. This can be represented in 3 ways in JSS:
   1. font_family
   2. “font_family”
   3. “font-family”
4. Quoted values with commas. Unlike CSS, all values in JSS are quoted with either single or double quotes. Furthermore, between declarations, there must be a comma.
   
   

   // This is correct.
   "rule-selector-a":
   {
     property_a: "value-a",
     property_b: "value-b"
   },
    
   // This is incorrect.
   "rule-selector-b":
   {
     property_a: "value-a",
     property_b: "value-b", // This declaration should not 
                            // have a comma.
   }

5. Commas between rules. Like declarations, each rule must have a comma between it:

   "rule-selector-a":
   { ... },
    
   "rule-selector-b":
   { ... } // Make sure the last rule has no comma after it.

Loading JSS and JSS stylesheets

Now that we understand the syntactic structure of a JSS stylesheet, it’s time to take look at how we include them in an HTML file. Every page that makes use of JSS will have the following structure:

<html>
  <head>
    <title>Title</title>
    <script type="text/javascript" src="jquery.js"></script>
    <script type="text/javascript" src="jquery.jss.js"></script>
    <script type="text/javascript" src="sheet-1.jss.js"></script>
    <script type="text/javascript" src="sheet-2.jss.js"></script>
    ...
    <script type="text/javascript" src="sheet-n.jss.js"></script>
  </head>
  <body>
    <!-- Your website here. -->
  </body>
</html>

Let’s quickly go through the components here. The first script tag includes the jQuery library, which is required by JSS. The second script tag includes the JSS jQuery plugin, which is the brains of JSS, and is required for any JSS stylesheet to work. All the script tags after that are the JSS stylesheets that you wish to load.

As you can see, you can add an unlimited number of JSS stylesheets, and when the page loads, they’ll be applied in the same order they are included in the page. Keep in mind, however, that if you’re including many script tags on a single webpage, it is advisable to use some sort of JavaScript loader.

Consider these two images:

Imagine we wanted to make them “rollover”, i.e. the zebra should be shown when nothing is happening, and the shark should be showed when the mouse is “rolled over” (i.e. on top of) the zebra. Like this:

Before we start writing some JSS, let’s write some HTML for a page just showing the rollover at rest (i.e. just show a plain old static image):

<html>
  <head>
    <title>JSS Rollover</title>
  </head>
  <body>
    <img src="image_off.png" />
  </body>
</html>

If we copied this code into an HTML file and ran it on our browser, we would see a static image of a zebra. Not that exciting, right? Now let’s see how we can use JSS to make this zebra “rollover” to the shark when the mouse is on it. Here’s the JSS stylesheet:

$.jss.declare({
 
  "img[src-over]":
  {
    hover: "set-attr src {src-over} | set-attr src {src-out}"
  }
 
});

Let’s step through this syntax, because there’s a lot going on here, even though it’s a single line. First, let’s annotate the JSS source so we can refer to it easier:

$.jss.declare({ // 1. Boilerplate that starts any JSS stylesheet.
 
  // 2. Rule
  "img[src-over]": // 3. CSS Selector
  {
    // 4. JSS Declaration
    hover: "set-attr src {src-over} | set-attr src {src-out}"
  }
 
});

As you might have noticed, a JSS stylesheet looks very similar to a CSS stylesheet. Let’s walk through the anatomy of a JSS stylesheet.

At the top of any JSS stylesheet there is some boilerplate code (1). This is necessary because a JSS stylesheet is actually a JavaScript program. However, beyond the fact that this boilerplate needs to be in every JSS stylesheet, you don’t really need to know what it does.

A JSS stylesheet is made up of an unlimited number of rules (2). This is the same as in a CSS stylesheet. Inside a JSS rule, there are two components, a selector (3) and an unlimited number of declarations (inside a declaration block) (4). This is where we start to see some of the advantages of JSS over using plain CSS.

JSS selectors are powered by jQuery. As such, JSS supports any CSS3-compliant selector. In addition, JSS also allows you to use any of the jQuery CSS selector extensions as well.

For example, in CSS, this stylesheet should stripe all the tables on the page as alternating gray and white:

table tr:nth-child(odd)
{ background-color: #eee; }
 
table tr:nth-child(even)
{ background-color: #fff; }

However, if you tried to use that CSS stylesheet in the two most popular browsers available (IE7 and Firefox 3) you would discover that it didn’t work. On the other hand, if you use the following JSS stylesheet…

$.jss.declare({
 
  "table tr:nth-child(odd)":
  { background_color: "#eee" }
 
  "table tr:nth-child(even)":
  { background_color: "#fff" }
 
});

…you would discover that it worked in all major browsers. By using a JavaScript selector engine, JSS offers better cross-browser styling than regular CSS.

(Aside: Before all you web developers out there go crazy, I would like to note that I realize there are several drawbacks to using JavaScript to style your page. Stay tuned to the end of this article for a discussion of them).

Now let’s return to our task of making a rollover. How does the JSS stylesheet make it possible? Let’s take a look at that JSS stylesheet again:

$.jss.declare({ // 1. Boilerplate that starts any JSS stylesheet.
 
  // 2. Rule
  "img[src-over]": // 3. CSS Selector
  {
    // 4. JSS Declaration
    hover: "set-attr src {src-over} | set-attr src {src-out}"
  }
 
});

Let’s look closer at the rule. More specifically, take a look at the CSS selector. For anyone familiar CSS, it reads “select all img tags that have the attribute src-over”. Why would we want to do that? Well, as it happens, we need some way to describe which image to use when the user mouses over our image. In order to do that, we’re going to use something called a custom attribute.

Custom attributes are user-defined attributes on HTML tags. For example, the img tag has an attribute called src. That’s a proper attribute that is defined in a W3C recommendation. What we’re going to do is add two new attributes, src-over and src-out, that are not part of any W3C standard. We just made them up because they’re convenient for our purposes.

Now that we’ve decided that we’re adding these two attributes, we need to add them to our HTML file:

<html>
  <head>
    <title>JSS Rollover</title>
  </head>
  <body>
    <img src="image_off.png"
        src-out="image_off.png" src-over="image_on.png" />
  </body>
</html>

With that done, let’s take a look at the last part of the JSS stylesheet: the declaration. A JSS declaration has a property (hover) and a value (“set-attr src {src-over} | set-attr src {src-out}”). This is just like a CSS declaration, like “font-family: Arial, sans-serif”. In that case, “font-family” is the property and “Arial, sans-serif” is the value.

In the case of the rollover JSS stylesheet, the hover property must have a value with the following structure:

hover: "jss-expression | jss-expression"

The first JSS expression on the left is run when the mouse is over the image area, and the right JSS expression is run when the mouse leaves the image area.

Let’s look at what happens in the JSS rollover stylesheet when the mouse is brought over the image area:

set-attr src {src-over}

This JSS expression reads: “set the src attribute (of the selected element) to the contents of the src-over attribute (of the selected element)”. This is because “set-attr” is a JSS command. The “set-attr” command takes two arguments: the attribute to change, and the value to change it to. That leaves one more question. What’s the deal with the curly braces?

In JSS, curly braces are basically a “get-attr” command. They fetch the value of an attribute. In the context they are being used here, they fetch the value of the “src-over” attribute (which happens to be the name of the shark image “image_on.gif”).

With that information in hand, it can be deduced that the right hand side…

set-attr src {src-out}

…switches the src attribute back to src-out image URL when the mouse leaves the image area.

Thus, if we put it all together, and include the appropriate JavaScript files, we have the following. In the “index.html” file we have:

<html>
  <head>
    <title>JSS Rollover</title>
    <script type='text/javascript' src='jquery.js'></script>
    <script type='text/javascript' src='jquery.jss.js'></script>
    <script type='text/javascript' src='styles.jss.js'></script>
  </head>
  <body>
    <img src="image_off.png"
        src-off="image_off.png" src-over="image_on.png" />
  </body>
</html>

And in the “styles.jss.js” file we have this:

$.jss.declare({
 
  "img[src-over]":
  {
    hover: "set-attr src {src-over} | set-attr src {src-out}"
  }
 
});

These files together create a page that has a rollover that changes from zebra to shark when the mouse is hovered over it. Better yet, this JSS stylesheet can be used with any web page to enable rollover images. All the user has to do is set the “src-over” and “src-out” custom attributes.

Notes on JSS Availability & Performance

JSS applies its stylesheets using JavaScript. This has several implications to web designers using it. First of all, in order for a site to take advantage of JSS, JavaScript must be enabled. Fortunately, something like 95% of all web surfers have JavaScript enabled, so that’s not too big of deal. Secondly, JSS is a lot slower than CSS. For most websites, this difference will probably be imperceptible deal, but it’s still something to be aware of.

My recommendations would be this: if you can do it in CSS, and it works properly across all browsers, then use CSS. There’s no reason not to. However, if you need to use JSS features like event properties (like hover) or cross-browser selectors, then use JSS.

In short, the merge() command allows you to merge your current zing with the previous zing in your stack. What’s the stack, you ask?

Recall that, by default, Arrayzing a functional API, meaning that (unless you’re using a mutator command) your zing is never modified. Instead a new one is returned. So, if we do this…

_(1, 4, 9, 144).gteq(4).map(Math.sqrt);

…we have in fact created 3 zings, not one. Although it seems wasteful to keep making new zings, it turns out to be pretty useful. For one, it allows us to step backwards using the undo() command:

_(1, 4, 9, 144)  // [1, 4, 9, 144]
  .gteq(4)        // [4, 9, 144]
  .map(Math.sqrt) // [2, 3, 12]
  .undo()         // [4, 9, 144]
  .undo()         // [1, 4, 9, 144]
  .undo();        // []

(Aside: For those familiar with jQuery, the undo() command is the same as the end() command from that library).

Keeping a history (or stack) also allows us to combine the past with the present using the andSelf() command:

var double = function (x) { return x * 2; };
_(1, 2, 3)    // [1, 2, 3]
  .map(double) // [2, 4, 6]
  .andSelf();  // [2, 4, 6, 1, 2, 3]

But what else? Well, consider this situation: What if we wanted to modify only a subset of a zing? For example, imagine we a list of monetary values and we wanted to make sure they all had the “$” character in front of them. Let’s try and do that without using merge():

var fn = function(e)
{
  if (!e.startsWith("$"))
    return "$" + e;
};
 
_("$1.00", "$1.99", "100.00", "$5").map(fn);

That solution is OK. It’s pretty simple but it still requires a lot of typing and it’s not really using Arrayzing for much (just the map() command). Let’s see if we can reduce the number of keystrokes and make better use of Arrayzing’s capabilities by using the new merge() command:

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/).prepend$("$").merge();

So what just happened there? What does it all mean? Let’s look at that again, and track the contents of the zing:

1
2
3
4
5

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/)    // [ "100.00" ]
  .prepend$("$") // [ "$100.00" ]
  .merge(); 
  // [ "$1.00", "$1.99", "$100.00", "$5" ]

In line 1, we create the Arrayzing (nothing special here). In the following line, we filter out all strings that don’t begin with “$” using a regular expression. Things get a little more interesting on line 3, where we use the mutator version of prepend() to modify the filtered array in-place. Finally, on line 4, we use the merge() command which, basically puts the originally filtered monetary value back into the preceding zing.

So why did we use the prepend$() instead of prepend()? The reason for that is because using prepend() would have created another level of history. For example, here is what would happen if we had used prepend() instead of prepend$():

1
2
3
4

_("$1.00", "$1.99", "100.00", "$5")
  .not(/^\$/)   // [ "100.00" ]
  .prepend("$") // [ "$100.00" ]
  .merge();     // [ "$100.00" ]

Why did that happen? The answer to that question lies in how merge() merges. Let’s start by looking at line 2 of the last code snippet. In that line, we filtered out all strings that did not start with a “$” character. When Arrayzing returns a new zing that contains only the elements that start with a “$”, it also remembers where the new elements came from. So in the case of the not() function on line 2, Arrayzing remembers that “100.00″ came from index 2 of the zing in line 1 (that is, the zing _(“$1.00″, “$1.99″, “100.00″, “$5″)). The merge() command only operates on the current zing and the one immediately previous to it on the stack.

With that in mind, let’s look at line 3. On line 3, we run the prepend() command, which creates and returns a new zing that contains the value “$100.00″. What’s more, it also remembers that the value “$100.00″ was derived from “100.00″ (index 0) in the zing immediately previous to it in the stack (that is, the zing _(“100.00″)). Thus, when merged, it simply overwrites the value it derived from, which is the 0th index of the zing [ "100.00" ]… which results in the zing [ "$100.00" ]. You follow all that?

This concept is easier to understand by annotating the previous code snippet:

var zing1 = _("$1.00", "$1.99", "100.00", "$5");
// [ "$1.00", "$1.99", "100.00", "$5" ] index 0-3 come from nothing
 
var zing2 = zing1.not(/^\$/);
// [ "100.00" ] index 0 comes from index 2 in zing1
 
var zing3 = zing2.prepend("$");
// [ "$100.00" ] index 0 comes from index 0 in zing2
 
var zing4 = zing3.merge();
// [ "$100.00" ] copy index 0 from zing3 over index 0 in zing2

Now, with that more or less explained, let’s go on to one final item: What happens when we try to merge a zing that we’ve added to or removed from. For example, if we added elements like this:

_("str", 2, 3, 4, "a", "b").numbers().add$(7).merge();

What would be in the zing returned by this sequence of functions? In this case, when merge() is called, Arrayzing would not know where to merge the 7 element (since it only remembers the original indices of elements that directly derived from the previous zing). Arrayzing deals with this scenario by simply adding all elements that it does not have an index for to the end of the previous zing in the stack. Here’s what that same snippet would look like if we documented each step:

_("str", 2, 3, 4, "a", "b")
  .numbers() // [ 2, 3, 4 ]
  .add$(7)   // [ 2, 3, 4, 7 ]
  .merge();  // [ "str", 2, 3, 4, "a", "b", 7 ]

How about if we removed elements? If we were to remove elements, they would simply not be merged back into the previous zing on the stack. For example:

_("str", 2, 3, 4, "a", "b")
  .numbers()    // [ 2, 3, 4 ]
  .set$(0, 4)   // [ 4, 3, 4 ]
  .set$(2, 7)   // [ 4, 3, 7 ]
  .removeAt$(0) // [ 3, 7 ]
  .merge();     // [ "str", 2, 3, 7, "a", "b" ]

As you can see, the merge() command is a powerful addition to Arrayzing. It allows us to select a subset of the elements, transform them, and then re-add them to our original zing.

For example, to get all the numbers out of an Arrayzing array (which I have started calling a zing, much to Kevin’s dismay) we would simply have to do this:

_(1, 2, "foo", function() { return 42 }, false, 3, 42).numbers();

Although this is useful in itself, Arrayzing can still do more. Imagine that not only did we want to extract all the numbers in an array, we wanted to sum them too. Arrayzing can handle that without breaking a sweat:

_(1, 2, "foo", function() {}, false, 3, 42).numbers().sum();

And that’s just scratching the surface! But enough about that (we’ll deal with the power of Arrayzing is many posts in the future). Let’s talk about API design.

Arrayzing has been a lot of fun to design. Along the way there have been many design decisions to make and I thought it’d be useful to write about them for the benefit of myself and other would-be API designers.

The first decision I’ll talk about is probably the most radical of the recent changes. It has to do with the functional nature of Arrayzing (which was inherited from jQuery).

Basically, every time an Arrayzing command causes a zing to change (i.e. the numbers() function is invoked), Arrayzing will return a new zing as opposed to just returning a modified version of the current zing. (Remember, a zing is an Arrayzing object). This idea is illustrated below:

// str() is just a convenient way of calling toString()
var a = _(1, "two", 3);
a.str(); // "1,two,3"
var b = a.numbers();
a.str(); // "1,two,3"
b.str(); // "1,3"

This behaviour can be useful in a number of cases. For instance,

var a = _(1, 2, "three", 4, false, function() {}, "foo");
var sum = a.numbers().sum(); // 7
var strings = a.strings().join(","); // "three,foo"

As you can see, we don’t need to keep a copy of the initial values (1, 2, “three”, etc.), we can simply re-use the initial zing. We also won’t accidentally modify a zing when we don’t want to.

However, sometimes we want to modify an array in-place. For example, imagine we had an object called Reader that would read from some data source, and periodically have strings available. In order to check if the Reader has more strings, we would call Reader.hasNext(). In order to read the next string, we would call Reader.next(). So, to read all the strings that Reader has available at a given moment, we would iterate like this:

var array = new Array();
while (Reader.hasNext())
{
  array.push(Reader.next());
}

That same code in Arrayzing, as I’ve described it so far, would be this:

var zing = _();
while (Reader.hasNext())
{
  zing = zing.push(Reader.next());
}

Which has several problems. First of all, it’s not altogether obvious that this is how we’d it. Secondly, it’s pretty inefficent. Every iteration is creating a new Arrayzing that needn’t exist for our purposes. So what’s the solution? Borrow from our friend Ruby and throw in some mutator methods!

In Ruby, when a method modifies an object in-place, it is suffixed with an exclamation mark !. Unfortunately, JavaScript doesn’t allow for us to use exclamation marks in our variables. In place of that, Arrayzing uses the $ character. So now, in Arrayzing, every function that returns a modified zing also has a sister function with a suffixed $ that will modify the zing in-place.

Thus, returning to the example with the Reader, we can now use a mutator function:

var zing = _();
while (Reader.hasNext())
{
  zing.push$(Reader.next());
}