The page was designed by my fiancee Renee Lung and programmed by me. You’ll notice if you look at the source that there is no JavaScript in the traditional sense. The page consists of three JavaScript files: the jQuery library, the JSS plugin, and a JSS stylesheet.

I hope this gives people an idea of the power of JSS. Read on for an annotated version of the JSS stylesheet used on that site (as of June 29th 2009).

$.jss.declare({
 
// Fades the background in on each page.
// You'll notice the square bracket notation.  This is used to 
// attach multiple JSS commands to a single event property.  
// They run in the order they are declared.
".background":
{
  setup: 
  [ 
    "set-css (.background) display none", 
    "fade-in (.background) normal" 
  ]
},  
 
// This block only runs on the front page.
// It is used to show a different button mouse-over 
// image on the frontpage.
".front .button":
{
  setup: 
  [ 
    // This saves the name of mouseover image 
    // to the element so that the mouseover code
    // (down further) can use it.
    // The {id} is an attribute getter.
    // Thus, if the id for one of the buttons is
    // "portfolio", then the class-over variable
    // will be "front-portfolio-over".
    "set-data class-over front-{id}-over",       
    "preload-image gfx/buttons/front-{link-to}-over.png"
  ]
},
 
// This block runs on any page except the front page.
"#window:not(.front) .button":
{
  setup: 
  [ 
    "set-data class-over {id}-over",
    "preload-image gfx/buttons/{link-to}-over.png"
  ]  
},  
 
// This the code that is used to transition
// between pages.
".button":
{    
  // This is the rollover code.  Pretty simple eh?
  hover: "toggle-class [class-over] | toggle-class [class-over]",
  click: 
  [
    // This make the background fade out 
    // and then links the user to the link
    // provided in the HTML.
    "fade-out (.background) normal !then-link-to {@link-to}.html",
    "fade-out (#portfolio-window) normal"
  ]
},
 
// This a custom user function.  They can
// be tagged on to most JSS commands
// (in cases where you'd have things like
// a callback for an animation).
"then-link-to": function(link_target)
{  
  var event = $.Event("click");
  event.data = { arguments: [ link_target ] };
  this["link-to"](event);
},
 
// This is the code that handles making the 
// the images on the portfolio page "glow"
// when you mouseover them.
"div.artwork img":
{
  // This "setup" event property is used
  // to basically create a variable...
  setup: 
  [ 
    "set-data opacity-off 0.3", 
    "set-css opacity [opacity-off]"
  ],
 
  // ... that is then used by the "hover"
  // event property to set the opacity.
  hover: "fade-to 1 | fade-to [opacity-off]"
},
 
// The next block as well as the 
// two following #link-page-n classes are
// an admittedly hack way of making pages,
// but get the job done for a relatively simple
// page.  If you were dealing with anymore
// than a couple pages, this method would 
// quickly get unwieldly.
 
"#pager a":
{
  click: 
  [ 
    "set-css (.portfolio-window) display none",
    "set-css (#pager a) font-weight normal"
  ]
},
 
"#link-page-1":
{
  font_weight: "bold",
  click: 
  [
    "set-css (#portfolio-page-1) display block",
    "set-css font-weight bold"
  ]
},
 
"#link-page-2":
{
  click: 
  [
    "set-css (#portfolio-page-2) display block",
    "set-css font-weight bold"
  ]
},
 
// This is using JSS to make an image
// into a hyperlink.
"#pdf-button":
{
  click: "link-to {resume-link}"
}
 
});

• Fixed the way that {attributes} are handled when not using a selector. They should now properly grab the attribute from element that fired the event.
• Made it so each time a declaration block is applied, all the event handlers bound by JSS to the elements returned by that selector are unbound.
• Fixed the semantics of the {@attr} syntax. It now means that the eventTarget should always be used, regardless of whether or not a selector is defined. In order to access the attributes of a selector use {@attr} now.
• Added two new commands: set-data and remove-data. These commands use the jQuery functions data() and removeData(). They are similar to set-attr and remove-attr except instead of storing the information in an attribute, they are stored in a table. Data is accessed by using [data] syntax, similar to the {attr} syntax.
• Added new event property: setup. This event is fired when the JSS stylesheet is loaded (setup). This is useful in certain cases where the user wants to setup some variables using set-data.
• Made it so you can now set scroll-top and scroll-left via the set-attr command.
• Added trigger command. It can be used to trigger event properties on elements.
• Fixed bug where you could put a string | in a binary command due to the
  simplistic implementation. The new version requires any | to be escaped with \|.
• Added fade-to command, based on the jQuery.fadeTo() command.
• Added show and hide commands.
• Fixed issue with data and attribute replacements not working correctly (i.e. the first event would replace them for all events).
• Callbacks may now take string parameters. For example, “fade-out (#target) normal !callback str1 str2″.

I’ve also started writing documentation for the JSS commands. It is only partially completed but can still be helpful. Check out the JSS homepage for other documentation.

More extensive documentation will be forthcoming as I move towards a 1.0.0 release.

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.