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

Furthermore, after some thought, I’ve decided to split up Fep arrays. In PHP arrays aren’t really arrays in the traditional sense, but more like array/associate array hybrids (JavaScript uses a similar concept). This can be confusing, error-prone and I don’t think that the benefits of having an hybrid array system outweighs the complexity.

Thus, in Fep, there will be two main collection types: lists and dictionaries. Here’s how a Fep list will look like:

// Fep
fep = [ "foo", 1, 2, "bar" ];
fep.count(); // == 4
fep.add( "baz" );
fep.find( x => x > 1 ); // == 2
 
// Will compile into this PHP
$fep = new FepList("foo", 1, 2, "bar");
$fep->count();
$fep->add( "baz" );
$fep->find( function( $x ) { return x > 1 } );

And here’s how a Fep dictionary will look:

// Fep
fep = { blah: "blah", foo: "bar", 0: "zero" };
fep.keys(); // == [ "blah", "foo", 0 ]
fep.containsKey( "foo" ); // == true
fep.remove( "foo" ); // == true
 
// PHP
$fep = new FepDict(array("blah" => "blah", "foo" => "bar", 
         0 => "zero"));
$fep->keys();
$fep->containsKey( "foo" );
$fep->remove( "foo" );

Unfortunately, I don’t think the folks at Mozilla put their best effort into this one.

First of all, the Firefox implementation only supports a subset of the IE options. Here’s a table showing what each browsers implementation supports according to their documentation:

Doesn’t seem too bad, right? We still have center, resizable and scroll right? Right? Wrong.

Documentation != Implementation

It seems the guys who wrote the Firefox documentation weren’t the same guys who wrote the code. Including center, resizable or scroll in your arguments string has no effect whatsoever. In fact, center is supposed to be on by default, but I can tell you right now that the modal dialog sure as hell isn’t centered.

Here’s an updated support matrix:

Fortunately, they did get one part right: the dialog is modal. Woooo!

Can we fix it?

Well, we can, kinda. We can’t fix resizable, because that’s a property of the window, and we can’t fix scroll for the same reason. We can, however, emulate the center option by using dialogLeft and dialogTop. Here’s some quick-and-dirty code I wrote to do that.

var oldShowModalDialog = window.showModalDialog;
window.showModalDialog = function(url, args, options)
{           
  // Convert the options string into an object.
  var pairs = options.replace(/\s+/g, "").split(";");
  var option = {};
  $.each(pairs, function()
  {
    var pair = this.split(":");
    if (pair.length != 2) return true;
 
    option[pair[0]] = pair[1];
  });
 
  // Get the width and height of the document.
  var width = $(document).width();
  var height = $(document).height();
 
  // Get the width and height of the dialog.
  var dialogWidth = option.dialogWidth.replace("px", ""); 
  var dialogHeight = option.dialogHeight.replace("px", "");
 
  // Calculate where the dialog needs to be to be
  // centered.
  var dialogLeft = (width - dialogWidth) / 2;
  var dialogTop = (height - dialogHeight) / 2;
 
  // Add those settings to the options string.
  options += "dialogLeft: " + dialogLeft + "; ";
  options += "dialogTop: " + dialogTop + "; ";
 
  // Call the original function.
  return oldShowModalDialog(url, args, options);
};

Although this code uses jQuery, you could easily rewrite it to use vanilla JavaScript.

Will it be fixed soon?

Firefox has had showModalDialog since 3.0. So naturally, you’d have assumed they’d have fixed this bug in 3.5, right? Nope! The bug still exists in 3.5. Thus, I wouldn’t hold my breath on this one being fixed anytime soon.

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.

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.

When using plain old JavaScript Array objects, a common operation is to access or modify elements. For example:

var a = [1, 2, 3];
var sum = a[0] + a[1] + a[2]; // = 6
a[0] = 6;
a.join(); // "6,2,3"

Arrayzing also supports the built-in [] accessor. However, it should be noted there are limitations to accessing an Array in this manner, most notable amongst them being that we must always index from the left. For example, imagine we wanted to access the last element. Using a normal Array, we would have to do this:

var a = [1, 2, 3];
a[a.length - 1] = 4; // a = [1, 2, 4];
alert(a[a.length - 1]); // shows 4

Although this works, it’s not the most convenient or elegant way to do it. To address this problem, Arrayzing provides two new functions get() and set(). These functions act essentially the same as the built-in [] accessors with an added benefit: we can index from the left and the right. For example, to implement the above example using Arrayzing, we could instead do this:

var a = _(1, 2, 3);
a.set$(-1, 4); // a = [1, 2, 4];
alert(a.get(-1)); // shows 4

(Aside: If you’re not familiar with the $ after set$(), check out this article. It means that the function is a mutator).

What’s more, all Arrayzing commands that take an index as an argument allow right-indexing. What convenience!

There is one further advantage of using set(): we can change an element in your zing (a zing is an Arrayzing array) without modifying the original array. For example, if we wanted to replace an element in our zing but didn’t want to modify the original array, we would do this:

var a = _(1, 2, 3);
var b = a.set(0, 10); // not set$()
a.str(); // returns "1,2,3"
b.str(); // returns "10,2,3"

As you can see, Arrayzing provides a strict superset of the capabilities of a normal Array’s accessors, allowing you to write cleaner, easier code.