XLSX.js, Tres, ChromaNope

28 Sep 2012 | By Alex Young | Comments | Tags mobile spreadsheets usability

XLSX.js

XLSX.js (GitHub: stephen-hardy / xlsx.js, License: Microsoft Office Extensible File License) by Stephen Hardy can read and write Excel-compatible XLSX files. It converts base64 strings into object representations of XLSX spreadsheets, without using ActiveX.

It’s built using JSZip, and will generate data: URIs with a base64 encoded string that contains the spreadsheet’s XML.

Tres

Tres

Tres (GitHub: juliocesar / tres, License: MIT) by Julio Cesar Ody is a mobile framework based on Backbone.js. It provides some convenience classes for working with touch-based gestures and the wide variety of mobile device resolutions, and enough CSS and icons to jump-start development.

Like Backbone.js, Tres has its roots in Rails, so initial versions aim to provide interfaces that work well with Ruby-based projects. This includes console-based tools for generating stub files.

ChromaNope

ChromaNope

ChromaNope by Kris Hedges is a web service designed to illustrate the effects of various forms of colour blindness. It uses Node and PhantomJS to render any web page against the equivalent protanope, deuteranope, and tritanope version. Definitions of these terms can be found on the Wikipedia Color blindness page.

The Truth About Event Loops

27 Sep 2012 | By Alex Young | Comments | Tags node tutorials sponsored-content

The Truth About Event Loops

The Truth About Event Loops is an online masterclass by Marc-André Cournoyer, the creator of the Thin web server used by Apple, CloudFoundry, and Heroku. Each class is limited to 25 people, and includes eight hours of content, downloadable recordings, cheatsheets, exercises, reusable source code, and a copy of Create Your Programming Language. The class is priced at $529 CAD, but there are early bird tickets for $479 CAD which is around $488 USD.

Classes last for two days, and the next will be held on October 23rd and 24th at 9AM-1PM ET – keep in mind the time zone if you’re booking from outside Canada!

By taking part in this class, you’ll learn the following:

  • Guidelines for evented I/O
  • Why and when asynchronous I/O is faster
  • How an event loop works, by building one from scratch
  • The system calls at the core of every server
  • How to write the fastest network applications around
  • Ways to use your machine’s resources to the maximum

The aim is to allow you to finally master your web stack from top to bottom!

To give us a taste of the class, Marc has written a tutorial all about the Node event loop.

The Heart of the Node Event Loop

I am a big believer in mastering your tools to become a better developer. And the best way to master your tools is to understand how they are made.

Do you know what’s happening inside Node?

There’s an event loop. So there must be a loop somewhere, right? A loop handling events. Let’s take a look…

The Loop

Event loops like the one in Node are designed to react to I/O events. This could be an incoming connection, data arriving on a socket, etc. What’s more, it must react to these events extremely quickly. Like most things in software, the simplest design is usually the fastest. And event loops are usually very simple.

First, it consists of an endless loop:

while (true) {
  ...
}

Everything will happen in that loop. All of your Node programs will be running inside that loop. Which is similar to the loop you’ll find in virtual machines and emulators, where an actual processor is simulated instead.

A Turn in the Loop

Somewhere in the loop, your process will wait for I/O events to happen. Luckily, most operating systems come with a function that allows us to do just that. Several options exist, such as kqueue on Mac OS, epoll on Linux. The most portable (but slowest) one is select. For more on this, see select (2).

select watches a bunch of I/O objects (files, sockets) and lets you know when something happens. It looks something like this:

while (true) { // That's our loop
  events = select(<I/O objects to watch>)
}

React

At this point in the loop, we know an event has occurred. We must react to those events. In Node and many other event-based systems, this is done via callbacks.

In your Node program, you’ll define callbacks like so:

object.on('read', function() { ... })

This will register the callback inside the event loop, so that it knows what to do when this event happens. Introducing that in our loop, we’ll end up with the following:

while (true) {
  var events = select(<I/O objects to watch>)
  
  events.forEach(function(event) {
    var callback = findCallbackForEvent(event)
    callback() // This calls the callback function
  });
}

After we’re done executing all of the callbacks, we’re ready for another turn in the loop – it’ll patiently wait for other I/O events to happen.

But There’s More!

This is a simplification of how things work internally. However, even if the Node event loop is a little more complex than that, the structure is the same. It’s still a loop using select (or a variation), and triggering callbacks.

If you’d like to dive deeper into event loops and how it works in Node, and how other features such as setTimeout are implemented, then join the next edition of my online class.

Everything is online. You can ask questions. You’ll get exercises. And you’ll also get recordings of the class to watch again at your leisure.

The class already helped a number of developers master Node. Here’s what one of them had to say:

The class was paced excellently. Overall, this subject matter is complicated — but Marc walks through the material step-by-step and it’s straightforward to follow along. I’ve learned a great deal about how Evented I/O systems work, how they’re built and when they might be most appropriate (as well as when they’re not!)

- Tom Buchok

The previous edition was such a great success, it sold out in just a few days. So if you’re interested, book now!

truthabouteventloops.com

Node Roundup: 0.8.10-11, Cabinet, Node Si

26 Sep 2012 | By Alex Young | Comments | Tags node modules
You can send in your Node projects for review through our contact form or @dailyjs.

0.8.10

Node 0.8 releases are still coming thick and fast, with the release of 0.8.10 this week. On average the 0.8 branch has seen approximately 9 days between releases, with an extended summer holiday period of 20 days in August and September.

This version has a few fs fixes by Ben Noordhuis, although he’s already cited an issue in fs.stat() so he’s recommending holding off for 0.8.11 which should be released later this week.

Cabinet

Cabinet (License: MIT, npm: cabinet) by Manuel Astudillo is an alternative to Connect’s static middleware. The changes from TJ’s original module are as follows:

  • Memory-based cache, based on fs.watch
  • Automatic asset compilation and minification
  • gzip
  • Support for “virtual” files, including cache manifests

The API is compatible with Connect and Express middleware, but there are additional options:

app.use(cabinet(__dirname + '/static', {
  coffee: true,
  gzip: true,

  less: {
    // Specify search paths for @import directives
    paths: ['.',__dirname + '/static/stylesheets']
  },

  cache: { maxSize: 1024, maxObjects:256 }
}));

The project comes with Mocha tests, and additional options are documented in the readme file.

Node Si

Node Si (License: MIT, npm: si) by Michał Czapracki is a binary prefix number parser and formatter module. It can be used to format numbers like 10000000 as 10M, or 10gb as 1e10.

It’s currently a simple module, but the author plans on adding IEC compliant binary multipliers like ‘MiB’, case sensitive formats, and fractional SI multipliers.

jQuery Roundup: 1.8.2, jQuery UK, JavaScript Conference 2012

25 Sep 2012 | By Alex Young | Comments | Tags jquery plugins events
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

jQuery 1.8.2

jQuery 1.8.2 is out, and new users of the 1.8 line are advised to read the jQuery Blog posts for 1.8 and 1.8.1 before upgrading. This version adds a lot of fixes to the selector engine’s pseudo class handling, including :first, :last, :nth-child, :not, and :contains.

jQuery UK

jQuery UK 2013 has been announced for the 19th of April in Oxford. Early bird ticket will be £160, but there are also ‘blind bird’ tickets available for £130.

To apply to speak at the conference, complete the proposal form. Speakers can also be suggested by the community: jQuery 2013 - Suggested Speakers.

JavaScript Conference 2012

While we’re on the topic of conferences, JavaScript Conference 2012 takes place on the 15th and 16th of October 2012 in Düsseldorf. There are several tiers of tickets available, and the main conference ticket costs €590.

There’s a talk on jQuery Mobile and a few on Sencha’s various technologies. I also noticed a Backbone.js talk, and one on Node as well. The speakers page has details on all of the talks and workshops.

Linking the Hash Map

24 Sep 2012 | By Justin Naifeh | Comments | Tags tutorials data structures linked hash map

The Hashmap

The hash map is a classic and indispensable data structure in application programming. It is so ubiquitous that almost every modern language supports it either with a library, or by baking the functionality into the syntax itself. Hash maps are often implemented as an associative array.

A hash map provides constant-time access to a value via a unique key. The most common methodology in JavaScript is to use an object literal as a hash map.

var map = {};

// dot notation
map.foo = "bar";
console.log(map.foo); // "bar"

// bracket notation
map["foo"] = "bar";
console.log(map["foo"]); // "bar"

// mix and match
map.foo = "bar";
console.log(map["foo"]); // "bar"

In this example, the string "bar" is the value assigned to the object property foo. Notice that treating an object literal like a hash map is the same syntax as normal property access and manipulation; we can leverage the language itself as a data structure. Because there isn’t native hash code support in JavaScript, the Object.prototype.toString() method is invoked on the key to create the property name.

var map = {};
  
map[1] = "one";
console.log(map[1] === "one"); // true
console.log(map["1"] === "one"); // true
console.log(map[(1).toString()] === "one"); // true

While object literals suffice for basic hash map uses like caching, there are many operations that require boilerplate code such as listing all values in a hash map:

 
var map = {};

map["key1"] = "one";
map["key2"] = "two";
map["key3"] = "three";

// get all values
var values = [];
for (var key in map) {
  if (map.hasOwnProperty(key)) {
    values.push(map[key]);
  }
}

// the key order is not guaranteed with a basic hash map
// and each browser might have different implementations
console.log(values.join(',')); // "two,three,one"

To rescue ourselves from reinventing the wheel, it is advisable to use a hash map class that encapsulates the behavior. The details of implementation is beyond the scope of this article, but there are many open-source libraries and articles that are worth perusing for details. For this article, we will use the following rudimentary hash map class:

Hash Map

/**
 * Simple hash map class.
 */
var HashMap = function() {
  this._size = 0;
  this._map = {};
};

HashMap.prototype = {

  /**
   * Puts the key/value pair into the map, overwriting
   * any existing entry.
   */
  put: function(key, value) {
    if (!this.containsKey(key)) {
      this._size++;
    }
    this._map[key] = value;
  },
  
  /**
   * Removes the entry associated with the key
   * and returns the removed value.
   */
  remove: function(key) {
    if (this.containsKey(key)) {
      this._size--;
      var value = this._map[key];
      delete this._map[key];
      return value;
    } else {
      return null;
    }
  },
  
  /**
   * Checks if this map contains the given key.
   */
  containsKey: function(key) {
    return this._map.hasOwnProperty(key);
  },
  
  /**
   * Checks if this map contains the given value.
   * Note that values are not required to be unique.
   */
  containsValue: function(value) {
    for (var key in this._map) {
      if (this._map.hasOwnProperty(key)) {
        if (this._map[key] === value) {
          return true;
        }
      }
    }

    return false;
  },
  
  /**
   * Returns the value associated with the given key.
   */
  get: function(key) {
    return this.containsKey(key) ? this._map[key] : null;
  },
  
  /**
   * Clears all entries from the map.
   */
  clear: function() {
    this._size = 0;
    this._map = {};
  },
  
  /**
   * Returns an array of all keys in the map.
   */
  keys: function() {
    var keys = [];
    for (var key in this._map) {
      if (this._map.hasOwnProperty(key)) {
        keys.push(key);
      }
    }
    return keys;
  },
  
  /**
   * Returns an array of all values in the map.
   */
  values: function() {
    var values = [];
    for (var key in this._map) {
      if (this._map.hasOwnProperty(key)) {
        values.push(this._map[key]);
      }
    }
    return values;
  },
  
  /**
   * Returns the size of the map, which is
   * the number of keys.
   */
  size: function() {
    return this._size;
  }
};

This HashMap class lacks advanced features, but it is simple, effective, and library-agnostic.

Insertion Order

Even a robust and well tested hash map has one shortcoming if it relies on an object literal backbone: the return order of HashMap.keys() or HashMap.values() is unpredictable, meaning insertion order is not preserved. The overhead of tracking insertion order is why most hash map implementations ignore such a requirement and do not guarantee return order.

Although insertion order seems trivial, there are many cases in which it is critical to use hash maps for constant time access while also tracking when key/value pairs were inserted into the map. For example, a user interface library might allow a developer to add widgets to a dashboard.

Composition

Widget objects are added to a Dashboard, and when a Dashboard is rendered, so too are all of its Widget children in a predictable order. This is to avoid having a dashboard’s widgets randomly allocated to different layout slots per render.

var dashboard = new Dashboard();
dashboard.add(new Calendar("myCalendar"));
dashboard.add(new StockTicker("myStockTicker"));
dashboard.add(new Twitter("myTwitter"));

// modify the Calendar before rendering
var calendar = dashboard.getWidget("myCalendar");
calendar.setTimeZone("MST");

// render the dashboard and its widgets in order: Calendar, StockTicker, Twitter
dashboard.render();

We access the Calendar object–and other Widget objects–by its unique id, with Dashboard.getWidget() internally delegating to a private hash map. This introduces an implementation problem: we want to preserve the widget insertion order but give the developer constant time access to its Widget children. A common solution is to maintain two data structures within the Dashboard by synchronizing a hash map for access and an Array for order.

Dashboard

The code to ensure consistency and integrity between the two structures is non-trivial and not reusable, hence it is not ideal. Another solution is to abandon the hash map and rely solely on an Array, but this will slow Widget access time to a crawling O(n), which is also unacceptable.

Enter the linked hash map.

A linked hash map is a specialized hash map that is synchronized with a doubly linked list. We can merge these two data structures into a new class called LinkedHashMap, which allows constant time access backed by a doubly linked list to preserve insertion order. There is minimal overhead to synchronize the two structures when performing write operations on the core hash map. By extending the HashMap class we can add an optimized doubly linked list to track the keys. (If the hash map cannot be subclassed then consider decorating it or rolling your own if there are application-specific or critical optimization requirements.)

LinkedHashMap

/**
 * Constructor that initializes the parent HashMap
 * and the doubly linked list head and tail.
 */
var LinkedHashMap = function() {
  // invoke super constructor
  HashMap.apply(this, arguments);

  // "inner" Entry class
  this._Entry = function(value) {
    this.prev = null;
    this.next = null;
    this.value = value;
  };

  // doubly linkedlist instance variables
  this._head = this._tail = null;
};

// extend HashMap and overwrite the necessary functions
var temp = function() {};
temp.prototype = HashMap.prototype;
LinkedHashMap.prototype = new temp();

/**
 * Puts the key/value pair in the HashMap and records
 * the insertion record if it does not exist.
 * 
 * @override HashMap.put()
 */
LinkedHashMap.prototype.put = function(key, value) {
  var entry = new this._Entry(key);

  if (!this.containsKey(key)) {
    if (this.size() === 0) {
      this._head = entry;
      this._tail = entry;
    } else {
      this._tail.next = entry;
      entry.prev = this._tail;
      this._tail = entry;
    }
  }

  /*
   * EDIT: Added optimization suggested
   * by Chad Walker (see article comments).
   */
  // overwrite the value with an optimized Object wrapper
  value = {value:value, entry:entry};

  HashMap.prototype.put.call(this, key, value);
};

/**
 * Returns the value associated with the key.
 * 
 * @override HashMap.get()
 */
LinkedHashMap.prototype.get = function(key){
  var value = HashMap.prototype.get.call(this, key);
  
  /*
   * EDIT: Added optimization suggested 
   * by Chad Walker (see article comments).
   */  
  // we must unwrap the value
  return value != null ? value.value : null;
};

/**
 * Removes the key/value pair from the map and 
 * the key from the insertion order.
 * 
 * @override Hashmap.remove()
 */
LinkedHashMap.prototype.remove = function(key) {

  /*
   * EDIT: Added optimization suggested 
   * by Chad Walker (see article comments).
   */
  var value = HashMap.prototype.remove.apply(this, arguments);

  if (value != null) {
  
    var entry = value.entry;
  
    if (entry === this._head) {
      this._head = entry.next;
      this._head.prev = null;
    } else if (entry === this._tail) {
      this._tail = entry.prev;
      this._tail.next = null;
    } else {
      entry.prev.next = entry.next;
      entry.next.prev = entry.prev;
    }
  }

  return value;
};

/**
 * Clears the HashMap and insertion order.
 *
 * @override HashMap.clear()
 */
LinkedHashMap.prototype.clear = function() {
  HashMap.prototype.clear.apply(this, arguments);
  this._head = this._tail = null;
};

/**
 * Returns the HashMap keys in insertion order.
 *
 * @override HashMap.keys()
 */
LinkedHashMap.prototype.keys = function() {
  var keys = [];
  for (var cur = this._head; cur != null; cur = cur.next) {
    keys.push(cur.value);
  }
  return keys;
};

/**
 * Returns the HashMap values in insertion order.
 * 
 * @override HashMap.values()
 */
LinkedHashMap.prototype.values = function() {
  var values = [];
  for (var cur = this._head; cur != null; cur = cur.next) {
    values.push(this.get(cur.value));
  }
  return values;
};

This new data structure, a marriage between a hash map and doubly linked list, is perfect as the sole backbone of Dashboard to manage widgets.

Dashboard

Moving On

With just a little overhead for write operations to the LinkedHashMap, even basic problems that require hash map behavior can query the insertion order with ease.

var map = new LinkedHashMap();

map.put("key1", "one");
map.put("key2", "two");
map.put("key3", "three");

// return order is now predictable
console.log(map.keys().join(',')); // "key1,key2,key3"
console.log(map.values().join(',')); // "one,two,three"

Because LinkedHashMap implements the same API as HashMap via inheritance, calling code can switch to a LinkedHashMap at runtime without breaking. The beauty of object-oriented design is that the declared type (HashMap) of a variable is irrelevant to the runtime type (LinkedHashMap). The only difficulty is enforcing the API in a type-unsafe language like JavaScript…but that’s another article.

Tutorial: LispyScript Introduction

21 Sep 2012 | By Santosh Rajan | Comments | Tags LispyScript tutorials lisp
This tutorial is by Santosh Rajan (@santoshrajan), the creator of LispyScript (GitHub: santoshrajan / lispyscript).

Introduction

LispyScript is a tree structured programming language that compiles to JavaScript. A LispyScript program is made up of one or more LispyScript expressions.

(<function> arg1 arg2 arg3 ...)

A LispyScript expression is made up of an opening parenthesis, a set of elements separated by space characters, and a closing parenthesis. A LispyScript expression is a function call (this is not exactly accurate, but we will see the exceptions to this later).

The first element evaluates to a function. It may be a function reference or an anonymous function. The rest of the elements are the arguments to the function. The expression evaluates to the return value of the function.

(console.log "Hello World!")

You will notice that we called console.log, which happens to be a JavaScript function, directly from LispyScript. You can call all JavaScript functions from LispyScript, even loaded library functions and object methods. console.log also works like printf().

(console.log "2 + 2 = %d" (+ 2 2))

You can have expressions within expressions in LispyScript. Here the expression (+ 2 2) is evaluated first, and replaced with its return value 4. Then the function console.log is called with arguments string 2 + 2 = %d and value 4.

And this is all there is to the basic structure of a LispyScript program. LispyScript has a tree structure: expressions within expressions. Let’s look at a tree structure almost everyone is familiar with: HTML.

<html lang="en">
  <head>
    <title>My Home Page</title>
  </head>
  <body>
    <h1>Welcome to LispyScript</h1>
  </body>
</html>

This is a LispyScript HTML template that generates the exact same HTML as above:

(html {lang: "en"}
  (head
    (title "My Home Page"))
  (body
    (h1 "Welcome to LispyScript")))

We will learn how LispyScript HTML templates work later. For now, you can see that LispyScript has a tree structure. This same code structure can also be a data structure in LispyScript. This is known as homoiconicity – a fancy term for code having a data structure supported in that language.

When a compiler compiles a language like JavaScript, or Java or C, it first parses the source code into a tree structure known as the syntax tree, and then generates the machine/byte code from the syntax tree. If you could manipulate the syntax tree (which you can’t in these languages) while compiling, you could actually modify the language itself in ways not possible in the above mentioned languages and most other languages.

In LispyScript your code – for all practical purposes – is the syntax tree itself. And since the language is homoiconic, you can treat your code as data, and even modify the syntax tree! This is what macros do.

Macros

LispyScript does not have a print expression like printf() or console.log in JavaScript. We know that we can call the JavaScript console.log from LispyScript. Now if we could somehow transform a print expression into a console.log expression, we are done!

(macro print (str rest...)
  (console.log ~str ~rest...))

(print "Hello print macro!")
(print "2 + 2 = %d" (+ 2 2))

This example extends LispyScript by adding a print expression to it. The macro expression takes the macro name print as its first argument, and a list of argument names representing the arguments that will be passed to print as the second argument. The last argument to macro is a code template that will be expanded at macro expansion time.

Here the print expression takes two arguments, the same as console.log, and we name the first argument str. The second argument rest... is a special argument which represents the rest of the arguments to print. rest... can represent zero or more arguments.

Inside the template expression we dereference the two arguments by adding a ~ to them. So what happens when we use the print expression below?

(print "Hello print macro!")

The LispyScript compiler works in two steps. First it expands any macro expressions in the code. The previous expression will be expanded to:

(console.log "Hello print macro!")

And then the compiler compiles the above expression to JavaScript

console.log("Hello print macro!");

The expression:

(print "2 + 2 = %d" (+ 2 2))

Is expanded to:

(console.log "2 + 2 = %d" (+ 2 2))

…and compiled to:

console.log("2 + 2 = %d", (2 + 2));

This is a very simple example and you don’t gain much, but it’s good enough to illustrate a simple macro. You might wonder why a print function can’t be used instead of a print macro. Let’s see what happens when we write a print function instead.

(var print
  (function (data value)
    (console.log data value)))

(print "2 + 2 = %d" (+ 2 2))

This will work too, but have a look at the compiled output:

var print = function(data,value) {
    return console.log(data,value);
};
print("2 + 2 = %d",(2 + 2));

The print function must be included alongside the call to it in the compiled output! When we used a macro the compiled code was only one line.

console.log("2 + 2 = %d", (2 + 2));

This is only an incidental benefit of using macros. We still need to look at the real benefits. Rather than learn when to use macros, it is better to learn when not to use macros. Macros can be dangerous. Consider this function:

(var square
  (function (x)
    (* x x)))

(console.log (square 2))

The above code will print the answer 4.

This can be rewritten as a macro:

(macro square (x)
  (* ~x ~x))

(console.log (square 2))

And the expanded code is:

(console.log (* 2 2))

That’s it! The answer is correct. But now try the following:

(var i 2)
(console.log (square i++))

Ouch! You get 6! An embarrassing square of an integer. If you had used the function you would have got the correct answer. This is what happened:

var i = 2;
console.log((i++ * i++));

When you use functions the arguments to the function get evaluated and then passed into the function. So in this case when you pass i++, the value 2 is passed as x into the function and i gets incremented. So (x * x) yields 4. In the case of the macro the argument is not evaluated when the macro expansion happens. Whatever you pass as arguments to the macro just get substituted as is in the template. So if you pass i++, it gets substituted as is in your macro template yielding (i++ * i++) which is (2 * 3)!

Conclusion

By taking advantage of tree structures and homoiconicity, LispyScript offers an alternative way of developing JavaScript programs. Although macros are powerful, they must be handled with care.

Enyo Tutorial: Part 1

20 Sep 2012 | By Robert Kowalski | Comments | Tags tutorials enyo enyo-kowalski frameworks mobile

Enyo is a mobile and desktop framework that uses JavaScript and HTML5. Developed by HP and the open source community, it’s licensed under the Apache License. If you’re looking to build mobile applications with JavaScript, then Enyo is a great choice. In this tutorial series, I’ll introduce the major concepts through some worked examples that you can build or download and try out. The Enyo styleguide is suggesting double quotes instead of single quotes. Enyo also uses tabs for indentation. Although I prefer 2 Spaces as indentation and single quotes, I will follow these rules during this tutorial.

Kinds

Enyo applications are built around object prototypes called kinds. These can be either components or controls. Kinds in Enyo are very modularized, reusable and encapsulated.

Controls, on the other hand, are for controlling DOM nodes and manipulating them. Controls can nest other controls or components – they’re the “building blocks” for applications. A good example would be an app consuming an XML feed: a component would process the feed to JSON and rearrange the data. The views of that application representing the feed would be controls.

The Tip Calculator

There are hundreds of tip calculator apps on all the major vendor-specific app stores. We can go one better though – let’s build a tip calculator that can run on pretty much anything. Also, our Enyo-based app will be publishable using Cordova (formerly PhoneGap).

Setup

The Enyo project provides Bootplate – Enyo’s template project. All we have to do is clone the repository and init the submodules:

git clone https://github.com/enyojs/bootplate.git
cd bootplate
git submodule update --init

First Steps

Next open debug.html. You should now see the example app. In our developer console, type the following:

new enyo.Control({ content: 'Hello World' }).write();

This creates an Enyo control. It’s rendered as a simple div:

<html>
  <head>
  </head>
  <body>
    <div id="control">Hello World</div>
  </body>
</html>

Going Deeper: Controls, Getter and Setter, Events

To start developing the tip calculator, delete the contents of source/App.js – we’ll replace it with a new file.

Let’s add a kind called App to our emptied App.js:

enyo.kind({
  name: "App",
  kind: enyo.Control,
  style: "",
  classes: "onyx",
  components: [
    {kind: "onyx.InputDecorator", components: [
      {kind: "onyx.Input", name: "sumControl", placeholder: "Enter sum"}
    ]},
    {kind: "onyx.InputDecorator", components: [
      {kind: "onyx.Input", name: "percentControl", placeholder: "Enter percent"}
    ]},
    {kind: "onyx.Button", content: "Calculate tip", ontap: "calculate"},
    {tag: "div", name: "tipAmount"}
  ],
  create: function() {
    this.inherited(arguments);
  },
  calculate: function(inSource, inEvent) {
    var sum = this.$.sumControl.hasNode().value;
    var percent = this.$.percentControl.hasNode().value;

    var result = (sum * percent) / 100;
    this.$.tipAmount.setContent(result);

    return true; // stop bubbling
  }
});

An instance is created and rendered into the DOM in our debug.html file with renderInto:

new App().renderInto(document.body);

Now I’ll explain the previous example in detail. The kind property is set to enyo.Control, and there are currently no inline styles – the style property is empty. The onyx CSS class should be added, which is an included submodule in the Bootplate that themes our Enyo application and the applications elements.

The components property is used to nest more kinds – I’ve used several to define the required input controls, a button, and a div to display the results. All of these components have a name property, which is important and will be explained later.

The button has an event attached, the tap-event. Enyo supports many other events, e.g. dragging over the screen, flick, or self-created events.

When a kind is created the method create is automatically called by the Enyo framework. The method inherits from its parent kind with this.inherited(arguments); and can be overwritten. There are several other constructor and constructor-like functions in the lifecycle of a kind: destroy, create or constructor.

Every time we tap our button the calculate method is called. this.$ is used to address and access controls within the kind.

var sum = this.$.sumControl.hasNode().value

This line is where the value of the control with the name sumControl is accessed. After that we calculate the tip and render the result into the element.

this.$.tipAmount.setContent(result);

Every control has some handy getters and setters:

.setContent();
.getContent();
.getClasses();
.setClasses();
.getStyle();
.setStyle();
.getAttribute();
.setAttribute();

At the end of the method return true is used to prevent the tap event from bubbling up.

Get the Source

The source is available at my GitHub account: robertkowalski/enyo-dailyjs.

Conclusion

We’ve now hacked together a very basic tip calculator. This example could be built on to add a canvas element for diagrams, localStorage for statistics, or simply to add validation to user input.

In the next part of this series we’ll have a closer look at components and exposing the published properties of kinds. We’ll also create more reusable components from our app.

Node Roundup: mongo-lite, smog, sshfs-node

19 Sep 2012 | By Alex Young | Comments | Tags node modules libraries filesystem mongo
You can send in your Node projects for review through our contact form or @dailyjs.

mongo-lite

mongo-lite (GitHub: alexeypetrushin / mongo-lite, License: MIT, npm: mongo-lite) by Alexey Petrushin aims to simplify MongoDB by removing the need for most callbacks, adding reasonable defaults like safe updates, and offering optional compact IDs.

The chainable API looks more like MongoDB’s command-line interface:

var db = require('mongo-lite').connect('mongodb://localhost/test', ['posts', 'comments']);
db.posts.insert({ title: 'first' }, function(err, post) {
  // Use post
});

There’s also a Fiber-based API, so it can be used in a synchronous fashion.

smog

smog (License: MIT, npm: smog) from Fractal is a web-based MongoDB interface. It displays collections, and allows them to be sorted and edited. It also supports administration features, like shutting down servers, CPU/bandwidth usage graphs, and replica set management.

It’s built with Connect, and there’s an experimental GTK+ desktop interface made with the pane module by the same authors.

sshfs-node

sshfs-node (License: MIT, npm: sshfs-node) by Charles Bourasseau allows remote filesystems to be mounted using SSH. It uses sshfs and requires keys for authentication, rather than passwords.

It comes with Vows tests, and the same author has also released fs2http.

jQuery Roundup: equalize.js, jQuery Builder, Gridster.js

18 Sep 2012 | By Alex Young | Comments | Tags jquery plugins design ui layout grid
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

equalize.js

This plugin comes from the “should I just use a table?” department of design technicalities that we still have to deal with in 2012: equalize.js (GitHub: tsvensen / equalize.js, License: MIT/GPL). Created by Tim Svensen, this plugin resizes elements to match their height or any other dimension supported by jQuery Dimensions.

It works by calling a single method on the parent selector:

// Height is the default
$('#height-example').equalize();

$('.parent').equalize('outerHeight');
$('.parent').equalize('innerHeight');
$('.parent').equalize('width');
$('.parent').equalize('outerWidth');
$('.parent').equalize('innerWidth');

The documentation has full examples.

jQuery Builder

jQuery Builder (GitHub: jgallen23 / jquery-builder, License: MIT, npm: jquery-builder) by Greg Allen is a web-based tool for building a custom version of jQuery 1.8.1. As jQuery has evolved it’s got a lot easier to include only the components necessary for a given project. This particular solution has been made using Node, and is installable with npm.

Gridster.js

Gridster.js (GitHub: ducksboard / gridster.js, License: MIT) from Ducksboard is a grid plugin that allows layouts to be designed by drag and drop. Elements can span multiple columns, and by dynamically added and removed. Any element can be used because Gridster is based around data attributes.

Gridster is distributed with suitable CSS, and supports IE 9+, Firefox, Chrome, Safari, and Opera.

Encapsulation Breaking

17 Sep 2012 | By Justin Naifeh | Comments | Tags encapsulation tutorial

Encapsulation is the process by which an object’s internal components and behavioral details are hidden from calling code. Only that which should be exposed is exposed, making objects self-contained black boxes to the outside world. Many languages support encapsulation by supplying visibility modifiers (e.g., private) and constructs such as inner classes.

Unfortunately, JavaScript offers very little in the encapsulation department. While there are certain tricks that can wrap protected code in closures (see Module Pattern), many have disadvantages that compromise code flexibility and extensibility.

Standard Convention

Instead of using closure-based encapsulation, which often makes object-oriented inheritance difficult, many libraries and code-bases opt to mark private properties and functions with an underscore prepend. This convention makes inspecting the properties and functions easy within browser debuggers.

 
var Person = function(first, last){
  // private properties _first, _last, and _id
  this._first = first;
  this._last = last;
  this._id = this._generateId();
};

Person.prototype = {
  getId : function(){
    return this._id;
  },
  getFirstName: function(){
    return this._first;
  },
  getLastName : function(){
    return this._last;
  },
  // private function to generate an id for this object
  _generateId : function(){
    return new Date().getTime().toString();
  }
};

This convention is commonplace, similar to naming constants in uppercase. The downside is that private properties and functions can still be accessed, thus breaking encapsulation because of careless coding.

Encapsulation Breaking

The dynamic nature of JavaScript allows for a free-for-all environment where a developer can do whatever he or she wants. Consider the following:

 
var person = new Person("Bob", "Someguy");
console.log(person._first); // logs "Bob"

This appears all fine and well, but now we’ve coupled our code to the Person implementation. Any change to the internals – the category of change encapsulation should protect us against – could break calling code.

 
var Person = function(first, last){
  this._firstName = first; // property change
  this._lastName = last; // property change
  this._id = this._generateId();
};

// ... 
var person = new Person("Bob", "Someguy");
console.log(person._first); // logs "undefined"

These bugs can be difficult to track, especially since the application code may not have changed…an updated external library or resource, in which Person may be defined, is all that it takes. The best defense against such couplings is to avoid breaking encapsulation. If a property or method is marked as private, do not access, modify, or invoke it. The overhead in rethinking the architecture and design is almost always less than the cost of dealing with the consequences of breaking encapsulation.

In other words: “Developers don’t let developers break encapsulation.”

Method Stealing

As troublesome as accessing private properties can be in JavaScript, there is another much more insidious practice that seems commonly accepted: method stealing.

The methods Function.prototype.call and Function.protoype.apply are integral to modern libraries and code-bases by allowing a method to inject a custom context (this reference) into the execution scope. Without these capabilities the reliance on closures to achieve the same effect would be too cumbersome.

Just as some properties should be hidden, so too should some methods. Given our prior example, Person.prototype._generateId() might function as an inadequate UUID generator. A clever developer notices that another available method Book.prototype._setUUID() sets a this._id property on all Book objects whose value is much more unique across space and time than Person.prototype._generateId();

 
var Book = function(title, author){
  this._title = title;
  this._author = author;
  this._id = null;
  this._setUUID();
}
Book.prototype = {
  getId : function(){
    return this._id;
  },
  getTitle : function(){
    return this._title;
  },
  getAuthor : function(){
    return this._author;
  },
  _setUUID : function(){
    var result = '';
    for(var i=0; i<32; i++)
    {
      result += Math.floor(Math.random()*16).toString(16);
    } 
    this._id = result;
  }
};

In return, the developer has chosen to “steal” this behavior from Book for Person and modify Person.prototype._generateId() to invoke Book.prototype._setUUID().

 
var Person = function(first, last){
  // private properties _first, _last, and _id
  this._first = first;
  this._last = last;
  this._id = null;
  this._generateId();
};

Person.prototype = {
  getId : function(){
    return this._id;
  },
  getFirstName: function(){
    return this._first;
  },
  getLastName : function(){
    return this._last;
  },
  // private function to generate an id for this object
  _generateId : function(){
    // sets this._id withing _setUUID()
    Book.prototype._setUUID.call(this);
  }
};

Again this works…ostensibly so, by having this._id set by Book.prototype._setUUID(). The design is brittle, however, because Book’s internals can be refactored unbeknownst to Person, thus breaking Person objects. If Book.prototype._setUUID() is refactored to set this._uuid rather than this._id then all Person.prototype.getId() invocations will return undefined. With one myopic decision we broke our application because it was easier to break encapsulation rather than rethink the design.

Conclusion

There is not much of a conclusion except do not break encapsulation. In fact, apply the Golden Rule while coding: treat other code as you wish yours would be treated. Any API deficiencies should be brought to the original author, not hacked apart to make it usable for one use case or instance. The maintenance headache down the road is just not worth it.

Functional Programming in JavaScript

14 Sep 2012 | By Nathaniel Smith | Comments | Tags functional tutorial

JavaScript has two parents: Scheme and Self. We can thank Self for all of the object-orientedness of JavaScript and indeed we do in our code and our tutorials. However, Scheme played just as important a role in the language’s design, and we would do ourselves ill to overlook JavaScript’s functional heritage.

What exactly does it mean for JavaScript to be functional? “Functional” merely describes a collection of traits a given language may or may not have. A language like Haskell has all of them: immutable variables, pattern matching, first class functions, and others. Some languages hardly have any, like C. While JavaScript certainly doesn’t have immutable variables or pattern matching it does have a strong emphasis on first class functions; mutating, combining, and using these function objects for cleaner and more succinct code is the purpose of this tutorial.

Partial Application

Partial application is a technique for taking a function f and binding it against one or more arguments to produce a new function g with those arguments applied. We’ll demonstrate this operation by adding a helper function p to Function’s prototype.

Function.prototype.p = function() {
  // capture the bound arguments
  var args = Array.prototype.slice.call(arguments);
  var f = this;
  // construct a new function
  return function() {
    // prepend argument list with the closed arguments from above
    var inner_args = Array.prototype.slice.call(arguments);
    return f.apply(this, args.concat(inner_args))
  };
};

var plus_two = function(x,y) { return x+y; };
var add_three = plus_two.p(3);
add_three(4); // 7

Composition

Composition is an operation that produces a new function z by nesting functions f and g. You can think of it in this way: z(x) == f(g(x)). Let’s add a helper like we did for partial application.

Function.prototype.c = function(g) {
  // preserve f
  var f = this;
  // construct function z
  return function() {
    var args = Array.prototype.slice.call(arguments);
    // when called, nest g's return in a call to f
    return f.call(this, g.apply(this, args));
  };
};

var greet = function(s) { return 'hi, ' + s; };
var exclaim = function(s) { return s + '!'; };
var excited_greeting = greet.c(exclaim);
excited_greeting('Pickman') // hi, Pickman!

Flipping

Flipping at first seems like a scary and arbitrary thing to do to a poor Function. However, it is useful when one desires to use partial application to bind arguments other than the first. To perform a flip we take function f which takes parameters (a,b) and construct a function g which takes parameters (b,a).

Function.prototype.f = function() {
  // preserve f
  var f = this;
  // construct g
  return function() {
    var args = Array.prototype.slice.call(arguments);
    // flip arguments when called
    return f.apply(this, args.reverse());
  };
};

var div = function(x,y) { return x / y; };
div(1, 2) // 0.5
div.f()(1,2) // 2

Point-Free Style

Point-free programming is a style of coding that one doesn’t see much outside of languages like Haskell or OCaml. However, it can help drastically reduce the use of the rather verbose function declaration syntax omnipresent in JavaScript code. Programming in a point-free style is made possible by our helpers above, and we’ll combine them to illustrate this concept.

// We'll start by solving the following problem in a non point-free way.
// Produce a function which, given a list, returns the same list with
// every number made negative.

// First, declare some helpers:
var negate = function(x) { return -1 * x; };
var abs = function(x) { return Math.abs(x); };
var map = function(a, f) { return a.map(f); };
var numbers = [-1, 2, 0, -2, 3, 4, -6]

var negate_all = function(array) { return map(array, function(x) { return negate(abs(x)) };
negate_all(numbers); // [-1, -2, 0, -2, -3, -4, -6]

// That solves it; but we can do better:

var negate_all = map.f().p(negate.c(abs));
negate_all(numbers); // [-1, -2, 0, -2, -3, -4, -6]

What did we do here? First, we flipped map’s signature to be (f,a); this allows us to then partially apply a function to map and turn it into a function that takes only a single parameter: the array we wish to negate. But what function do we want to bind to our map? The result of negate.c(abs), which represents a function that does negate(abs(x)). We’ve produced the same function in the end and solved our problem. In the former attempt, we declare a new function to imperatively do what we wish; in the latter we construct a new function based on functions we already have.

What makes this point-free? Note the redundancy of the array argument in the former declaration. We already have a function that knows how to produce a new array from an existing one; why not convert that function into a new one to do what we want? We cut characters by 37% and, for many, achieve better readability.

Conclusions

In the end, functional programming is a matter of taste. For some it is a thing of subtle beauty and for others a wild nest of parentheses. This tutorial is a suggestion of styles that might be and is in no way a ‘Functional is better’ argument. If this has piqued the reader’s interest, she or he may be interested in the following resources:

Express 3 Tutorial: Contact Forms with CSRF

13 Sep 2012 | By Alex Young | Comments | Tags express tutorials bootstrap

The contact form

This tutorial is a hands on, practical introduction to writing Express 3 applications complete with CSRF protection. As a bonus, it should be fairly easy to install on Heroku.

Prerequisites

A working Node installation is assumed, and basic knowledge of Node and the command-line.

Getting Started

Create a new directory, then create a new file called package.json that looks like this:

{
  "author": "Alex R. Young"
, "name": "dailyjs-contact-example"
, "version": "0.0.1"
, "private": true
, "dependencies": {
    "express": "3.0"
  , "jade": "0.27.2"
  , "validator": "0.4.11"
  , "sendgrid": "latest"
  }
, "devDependencies": {
    "mocha": "latest"
  },
  "engines": {
    "node": "0.8.9"
  }
}

Express has a built-in app generator, but I want to explain all the gory details. If you want to try it out, try typing express myapp in the terminal.

Back to the package.json file. The author and name can be changed as required. The private flag is set so we don’t accidentally publish this module to npmjs.org. The dependencies are as follows:

  • express: The web framework we’re using, version 3 has been specified
  • jade: The template language, you could convert this project to ejs or something else if desired
  • validator: The validator library will be used to validate user input
  • sendgrid: SendGrid is a commercial email provider that’s easy to use with Heroku

The engines section has been included because it’s a good idea to be specific about Node versions when deploying to Heroku.

Configuration

Although I typically encourage breaking up Express projects into multiple files, this project will use a single JavaScript file for brevity.

First, the modules are loaded, and an Express app is instantiated. Users of Express 2.x will notice that there is no longer a createServer() method call:

var express = require('express')
  , app = express()
  , SendGrid = require('sendgrid').SendGrid
  , Validator = require('validator').Validator
  ;

The Validator object is just one way to work with the node-validator module. The author has also provided Express middleware for directly validating data in requests. I didn’t use it here because I was concerned it might not work with Express 3, and I’m writing to a deadline, but it’s worth taking a look at it. In general, I like to avoid tying too much code into Express in case I want to migrate to another framework, so that’s worth considering as well.

The next few lines are application configuration:

app.configure(function() {
  app.set('views', __dirname + '/views');
  app.set('view engine', 'jade');
  app.use(express.cookieParser());
  app.use(express.session({ secret: 'secret goes here' }));
  app.use(express.bodyParser());
  app.use(app.router);
  app.use(express.csrf());
  app.use(express.static(__dirname + '/public'));
});

When you’re writing Express configuration, avoid copying and pasting lines from examples without fully understanding what each line does – it will get you into trouble later! You should understand what every single line does here, because changing the order of app.use lines can impact the way requests are processed and result in frustrating errors.

With that in mind, here’s what each line does:

  • app.set('views', __dirname + '/views'): Use ./views as the default path for the client-side templates
  • app.set('view engine', 'jade'): Automatically load index.jade files just by passing index
  • app.use(express.cookieParser()): Parse the HTTP Cookie header and create an object in req.cookies with properties for each cookie
  • app.use(express.session...: Use a session store – this is needed for the CSRF middleware
  • app.use(express.bodyParser()): Parse the request body when forms are submitted with application/x-www-form-urlencoded (it also supports application/json and multipart/form-data)
  • app.use(app.router): Use the actual router provided by Express
  • app.use(express.csrf()): The CSRF protection middleware
  • app.use(express.static(__dirname + '/public')): Serve static files in the ./public directory

Next follows configuration for development and production environments:

app.configure('development', function() {
  app.use(express.errorHandler({ dumpExceptions: true, showStack: true }));
  app.locals.pretty = true;
  sendgrid = {
    send: function(opts, cb) {
      console.log('Email:', opts);
      cb(true, opts);
    }
  };
});

app.configure('production', function() {
  app.use(express.errorHandler());
  sendgrid = new SendGrid(process.env.SENDGRID_USERNAME, process.env.SENDGRID_PASSWORD);
});

The app.locals.pretty = true line causes Jade to render templates with indentation and newlines; otherwise it spits out a single line of HTML. Notice that app.use is being called outside of app.configure – this is perfectly fine, and app.use can actually be called anywhere. There was some discussion about removing app.configure from Express 3.x, and it isn’t technically required.

I’ve made a mock sendgrid object for development mode that just prints out the email and then runs a callback. The production configuration block uses environmental variables (process.env.SENDGRID_USERNAME) to set the SendGrid username and password. It’s a good idea to use environmental variables for passwords, because it means you can keep them out of your source code repository. Since only specific developers should have access to the deployment environment, then it’s potentially safer to store variables there. Heroku allows such variables to be set with heroku config:add SENDGRID_USERNAME=example.

Helpers

The next few lines are new to Express 3:

app.locals.errors = {};
app.locals.message = {};

The app.locals object is passed to all templates, and it’s how helpers are defined in Express 3 applications. I’ve used these properties so I can write templates without first checking if these objects exist, else a ReferenceError would be raised.

Middleware Callbacks: CSRF Protection

I’ve mentioned CSRF but haven’t fully explained it yet. It stands for “Cross-Site Request Forgery”, and is a class of exploits in web applications where an attacker forces another user to execute unwanted actions on a web site. In this case it’s not particularly useful, but it’s good practice to guard against CSRF attacks in production web apps. The Open Web Application Security Project has a good article on CSRF), which includes example attacks.

function csrf(req, res, next) {
  res.locals.token = req.session._csrf;
  next();
}

The Connect CSRF middleware automatically generates the req.session._csrf token, and this function maps it to res.locals.token so it will be available to templates. Any route that needs CSRF protection now just needs to include the middleware callback:

app.get('/', csrf, function(req, res) {
  res.render('index');
});

The form in views/index.jade has a hidden input:

form(action='/contact', method='post')
  input(type='hidden', name='_csrf', value=token)

The token variable is the one set by the middleware callback in res.locals.token.

Validating Data

The contact form must be validated before an email is sent. Seeing as database storage isn’t necessary for this project, we can use the node-validator module to verify user input. I’ve put this in a function to abstract it from the corresponding route:

function validate(message) {
  var v = new Validator()
    , errors = []
    ;

  v.error = function(msg) {
    errors.push(msg);
  };

  v.check(message.name, 'Please enter your name').len(1, 100);
  v.check(message.email, 'Please enter a valid email address').isEmail();
  v.check(message.message, 'Please enter a valid message').len(1, 1000);

  return errors;
}

An instance of a Validator is created, and I’ve set a custom error handling function. This error handling function collects the errors into an array, but there are many other solutions supported by node-validator’s API.

Each message property is checked against a single validation, but several could be chained together.

The validate function itself expects a message object which will come from the posted form later.

Sending Email

Emails are sent with SendGrid. Again, I’ve made a function for this to keep it out of the corresponding Express routes:

function sendEmail(message, fn) {
  sendgrid.send({
    to: process.env.EMAIL_RECIPIENT
  , from: message.email
  , subject: 'Contact Message'
  , text: message.message
  }, fn);
}

I’ve made it accept a callback so the Express route can handle cases where sending the mail fails.

Posting the Form

Here is the Express route that handles the form post:

app.post('/contact', csrf, function(req, res) {
  var message = req.body.message
    , errors = validate(message)
    , locals = {}
    ;

  function render() {
    res.render('index', locals);
  }

  if (errors.length === 0) {
    sendEmail(message, function(success) {
      if (!success) {
        locals.error = 'Error sending message';
        locals.message = message;
      } else {
        locals.notice = 'Your message has been sent.';
      }
      render();
    });
  } else {
    locals.error = 'Your message has errors:';
    locals.errors = errors;
    locals.message = message;
    render();
  }
});

It uses the csrf middleware callback to generate another token. This is required because the contact form will always be rerendered. The form data can be found in req.body.message – I’ve used form variables like message[email], so these will get translated into a JavaScript object with corresponding properties.

When there are invalid fields, or sending the email fails, the contact form will be rendered again with the original message. To make the form retain the values, the value property of each field must be set:

form(action='/contact', method='post')
  input(type='hidden', name='_csrf', value=token)
  .control-group
    label.control-label(for='message_name') Your Name
    .controls
      input#message_name.input-xxlarge(type='text', placeholder='Name', name='message[name]', value=message.name)
  .control-group
    label.control-label(for='message_email') Email
    .controls
      input#message_email.input-xxlarge(type='text', placeholder='Email', name='message[email]', value=message.email)
  .control-group
    label.control-label(for='message_message') Message
    .controls
      textarea#message_message.input-xxlarge(placeholder='Enter message', rows='6', name='message[message]')=message.message
  button.btn(type='submit') Send Message

This is quite a chunk of Jade, but the extra markup is there because I’ve used Bootstrap to style the project.

The locals object I’ve used gets passed to the res.render message and contains the form data when required.

Download

The full source is available here: alexyoung / dailyjs-contact-form-tutorial.

Node Roundup: 0.8.9, xmlson, Mubsub, Book on libuv

12 Sep 2012 | By Alex Young | Comments | Tags node modules libraries books xml json pubsub
You can send in your Node projects for review through our contact form or @dailyjs.

Node 0.8.9

Node 0.8.9 is out, and this looks like a significant release judging by the long changelog. v8, npm, and GYP have all been updated, and there are quite a few platform-specific bug fixes relating to memory.

xmlson

xmlson (License: MIT, npm: xmlson) by the developers at Fractal is a libexpat-based XML/JSON conversion module:

var xmlson = require('xmlson');

xmlson.toJSON('<p><h1 title="Details">Title</h1></p>', function(err, obj) {
  // Do something with obj
  console.log(obj.p.h1)
});

In the previous example, [ { '@title': 'Details', text: 'Title' } ] will be printed, so attributes are included when converting to JSON. There’s also a synchronous API. Installing xmlson with npm will compile the necessary dependencies with gyp.

This module is a fairly lightweight wrapper around ltx, which is worth checking out.

Mubsub

Mubsub (License: MIT, npm: mubsub) by Scott Nelson is a publish–subscribe implementation that uses MongoDB:

It utilizes Mongo’s capped collections and tailable cursors to notify subscribers of inserted documents that match a given query.

To use it, a channel must be created and then subscribed to. It can work with MongoDB connection URLs, so it’s fairly easy to drop into an existing MongoDB-based Node project. It comes with Mocha/Sinon.JS tests.

Book: An Introduction to libuv

An Introduction to libuv by Nikhil Marathe is a guide to libuv. It covers streams, threads, processes, event loops, and utilities. If you’re trying to understand what makes Node different, and how its asynchronous and event-based design works, then this is actually a great guide. Try looking at Basics of libuv: Event loops as an example.

jQuery Roundup: jQuery License Change, FileUploader, Raphaël Tutorial

11 Sep 2012 | By Alex Young | Comments | Tags jquery plugins raphael file
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

jQuery Now MIT Licensed

jQuery was previously dual licensed under the MIT and GPL. This shouldn’t technically change anything, because the work could be relicensed under the GPL if required:

Having just one license option makes things easier for the Foundation to manage and eliminates confusion that existed about the Foundation’s previous dual-licensing policy. However, this doesn’t affect your ability to use any of the Foundation’s projects. You are still free to take a jQuery Foundation project, make changes, and re-license it under the GPL if your situation makes that desirable.

Contributors are being asked to sign a license agreement to ensure everything published under the jQuery Foundation has the necessary legal background. The license agreement has been modeled on the Contributor Agreements for copyright assignment, published by the Civic Commons Community.

FileUploader

FileUploader (License: MIT/GPL2/LGPL2) by Andrew Valums and Ray Nicholus is a File API wrapper. It can handle multiple uploads by using XMLHttpRequest, and will fall back to an iframe-based solution in older browsers. The API looks like this:

var uploader = new qq.FileUploader({
  // pass the dom node (ex. $(selector)[0] for jQuery users)
  element: document.getElementById('file-uploader'),

  // path to server-side upload script
  action: '/server/upload'
});

It doesn’t have any external dependencies, and has many advanced features, including drag-and-drop file selection, multiple uploads, and keyboard support.

Raphaël Tutorial

Making a Simple Drawing Application using RaphaëlJS is a tutorial by Callum Macrae that uses Raphaël and jQuery to create a simple paint program. It includes a basic introduction to Raphaël, and uses jQuery-based event handling to create the mouse-driven drawing interface.

Mastering Node Streams: Part 1

10 Sep 2012 | By Roly Fentanes | Comments | Tags tutorials node streams

Streams are one of the most underused data types in Node. If you’re deep into Node, you’ve probably heard this before. But seeing several new modules pop up that are not taking advantage of streams or using them to their full potential, I feel the need to reiterate it.

The common pattern I see in modules which require input is this:

var foo = require('foo');

foo('/path/to/myfile', function onResult(err, results) {
  // do something with results
});

By only having your module’s entry point be a path to a file, you are limiting the stream they could use on it to a readable file stream that they have no control over.

You might think that it’s very common for your module to read from a file, but this does not consider the fact that a stream is not only a file stream. A stream could be several things. It could be a parser, HTTP request, or a child process. There are several other possibilities.

Only supporting file paths limits developers – any other kind of stream will have to be written to the file system and then read later, which is less efficient. One reason for this is the extra memory it takes to store the stream. Secondly, it takes longer to stream the file to disk and then read the data the user needs.

To avoid this, the above foo module’s API should be written this way

var stream = fs.createReadStream('/path/to/myfile');
foo(stream, function onResult(err, result) {
  // do something with results
});

Now foo can take in any type of stream, including a file stream. This is perhaps too long-winded when a file stream is passed; the fs module has to be required, and then a suitable stream must be created.

The solution is to allow both a stream and a file path as arguments.

foo(streamOrPath, function onResult(err, results) {
  // ...
});

Inside foo, it checks the type of streamOrPath, and will create a stream if needed.

module.exports = function foo(streamOrPath, callback) {
  if (typeof streamOrPath === 'string') {
    stream = fs.createReadStream(streamOrPath);
  } else if (streamOrPath.pipe && streamOrPath.readable) {
    stream = streamOrPath;
  } else {
    throw new TypeError('foo can only be called with a stream or a file path');
  }

  // do whatever with `stream`
};

There you have it, really simple right? So simple I’ve created a module just for this common use case, called streamin.

var streamin = require('streamin');

module.exports = function foo(streamOrPath, callback) {
  var stream = streamin(streamOrPath);
  
  // do whatever with `stream`
};

Don’t be fooled by its name, streamin works with writable streams too.

In the next part, I’ll show you how modules like request return streams synchronously even when they’re not immediately available.

HexGL, one.color, fs.js

07 Sep 2012 | By Alex Young | Comments | Tags webgl libraries html5 filesystem

HexGL

HexGL

HexGL is a WebGL-powered racing game similar in style to WipEout, developed by Thibaut Despoulain. It’s built using three.js, and is a pretty solid and fun game. One aspect that impressed me is there’s a selector for changing the quality, based on settings tailored for “Mobile”, “Mainstream”, and “Ultra” – the author suggests that the game should always run at 60fps.

Thibaut is planning on open sourcing the game, and his blog has a feed so you can stay up to date that way or by following @BKcore on Twitter.

one.color

one.color (License: BSD, npm: onecolor) is a browser and Node colour manipulation library. Morgan Roderick suggested this library on Twitter after seeing our jQuery Color coverage, and also pointed out that one of the creators has posted a video about it: Peter Müller: One-color.js.

This library has a chainable API, supports alpha channels and colour names, and has Vows tests to back it all up.

fs.js

fs.js (License: MIT, npm: fs.js) by Manuel Astudillo is a wrapper for the HTML5 File API, based on Node’s fs module. It’s got some Mocha unit tests, and supports the use of prefixed file systems:

var sizeInBytes = 1024 * 1024
  , prefix = 'filetest';

FSFactory.create(sizeInBytes, 'testfs', function(err, fs) {
  fs.read('foo', function(err, data){
    // data contains file contents.
  });
});

AngularJS: About Those Custom Attributes...

06 Sep 2012 | By Alex Young | Comments | Tags mvc tutorials angularjs

The first thing I noticed on the AngularJS homepage was the use of a non-standard attribute, ng-app:

<div ng-app>
  <div>
    <label>Name:</label>
    <input type="text" ng-model="yourName" placeholder="Enter a name here">
    <hr>
    <h1>Hello !</h1>
  </div>
</div>

Suspicious as I am, I wanted to look into this further. Running a more complete HTML5 example through the w3.org validator shows errors for each ng- attribute:

  • Attribute ng-app not allowed on element div at this point.
  • Attribute ng-model not allowed on element div at this point.

Earlier HTML specifications state that unrecognised attributes should be ignored, so this should be safe enough – clients will generally ignore the unrecognised attribute and JavaScript can handle it as required by AngularJS.

The AngularJS developers have gone a step further to quell fears of rogue attributes causing unexpected issues: it now transparently supports data- prefixed attributes. That means the previous example could be written with data-ng-app and it would still work. I tried it out and found that it even copes with mixed attribute styles.

Knockout

Unlike AngularJS, Knockout embraced data- attributes from the beginning. The documentation even clarifies the use of data attributes:

The data-bind attribute isn’t native to HTML, though it is perfectly OK (it’s strictly compliant in HTML 5, and causes no problems with HTML 4 even though a validator will point out that it’s an unrecognized attribute). But since the browser doesn’t know what it means, you need to activate Knockout to make it take effect.

Although AngularJS now fully supports this approach, using custom attributes may have hurt early adoption.

Directives

The underlying mechanism that AngularJS uses to support multiple attribute prefixes is Directives, which according to the documentation turns HTML into a “declarative domain specific language”. You may have noticed that AngularJS templates are HTML – this contrasts with many other frameworks that use a string-based template system. Since templates are HTML, the entire page can be loaded and parsed by the browser. The resulting DOM is traversed by AngularJS’s compiler to find directives. The resulting set of directives is associated with DOM elements and prioritised. Each directive has a compile method, which can modify the DOM, and generates a link function.

Links are live bindings, and splitting compilation into stages like this means AngularJS can do a certain amount of work before repeatedly rendering sets of elements. The example in the documentation is rendering lots of list elements:

The result of of the li element compilation is a linking function which contains all of the directives contained in the li element, ready to be attached to a specific clone of the li element.

Conclusion

Although AngularJS may have been treated with some trepidation due to the adoption of non-standard HTML attributes, the authors have identified this and it’s possible to write applications that will validate. The “declarative domain specific language” concept is definitely interesting, and the two-stage compilation process has some advantages over other schemes that I’ve seen.

Node Roundup: redis-stream, DataGen, Cushion

05 Sep 2012 | By Alex Young | Comments | Tags node modules libraries streams redis couchdb
You can send in your Node projects for review through our contact form or @dailyjs.

redis-stream

redis-stream (License: MIT, npm: redis-stream) by Thomas Blobaum is a stream-based wrapper around the Redis protocol. It’s actually an extremely lightweight module, but the author has included tests and some interesting examples. The standard Node stream methods work, so data can be piped:

var Redis = require('redis-stream')
  , client = new Redis(6379, localhost, 0)
  , rpop = client.stream('rpop');

rpop.pipe(process.stdout);
rpop.write('my-list-key');

This doesn’t just apply to rpop, other Redis commands will also work in a similar way.

DataGen

DataGen (GitHub: cliffano / datagen, License: MIT, npm: datagen) by Cliffano Subagio is a multi-process test data file generator. It can be used to generate files in various formats, including CSV and JSON, based on template files that describe the output. Random numbers, dates, and strings can be generated.

The underlying random data generation is based on the Faker library, and Mocha tests are included.

Cushion

Cushion (GitHub: Zoddy / cushion, License: MIT, npm: cushion) by André Kussmann is a CouchDB API. It has Node-friendly asynchronous wrappers around the usual CouchDB API methods, and it also supports low-level requests by calling cushion.request. Fetching documents returns a document object that can be modified and saved like this:

var doc = db.document('id');
doc.load(function(err, document) {
  document.body({ name: 'Quincy' });
  document.save();
});

Designs and users can also be fetched and manipulated.

RoyalSlider: Tutorial and Code Review

04 Sep 2012 | By Alex Young | Comments | Tags libraries browser plugins jquery sponsored-content

RoyalSlider

There are a lot of carousel-style plugins out there, and they all have various strengths and weaknesses. However, RoyalSlider (License: Commercial, CodeCanyon: RoyalSlider, Price: $12) by Dmitry Semenov is a responsive, touch-enabled, jQuery image gallery and content slider plugin, and is one of the slickest I’ve seen. The author has worked hard to ensure it’s fast and efficient – it features smart lazy loading, hardware accelerated CSS3 transitions, and a memory management algorithm that ensures only visible slides are in the DOM at any one time.

The plugin is actively maintained, and has seen over a dozen updates since its release in August 2011. It’s distributed exclusively through CodeCanyon, but Dmitry’s site also has documentation and details on WordPress integration. Purchasing RoyalSlider gives access to a set of RoyalSlider templates that includes several types of galleries that should slot right in to your projects.

Since the plugin was originally released it has received extremely positive feedback (which is partly why it was chosen for a Featured Content post) – Dmitry has sold over 4,500 licenses, and it’s earned a 5 star rating based on 378 reviews.

Browser Support

RoyalSlider has been tested on IE7+, iOS, Opera Mobile, Android 2.0+, Windows Phone 7+, and BlackBerry OS.

Download and Setup

RoyalSliders build tool

RoyalSlider can be downloaded as either a development archive (that contains the original, unminified source), or a customised build can be created using Dmitry’s web-based build tool (access is granted once a license has been purchased).

To add RoyalSlider to a page, ensure you’ve included jQuery 1.7 or above, and then include the stylesheet and JavaScript:

<link rel="stylesheet" href="royalslider/royalslider.css">
<script src="royalslider/jquery.royalslider.min.js"></script>

The plugin expects a container element with the royalSlider class. Each child element will be considered a slider:

<div class="royalSlider rsDefault">
  <!-- simple image slide -->
  <img class="rsImg" src="image.jpg" alt="image desc" />

  <!-- lazy loaded image slide -->
  <a class="rsImg" href="image.jpg">image desc</a>

  <!-- image and content -->
  <div>
    <img class="rsImg" src="image.jpg" data-rsVideo="https://vimeo.com/44878206" />
    <p>Some content after...</p>
  </div>
</div>

Then all you need to do is run $.fn.royalSlider:

$(function() {
  $('.royalSlider').royalSlider();
});

At this point options can be provided, and believe me there are a lot of options!

Examples

RoyalSlider example

The templates distributed alongside RoyalSlider include full examples with JavaScript, CSS, and HTML. The example above is suitable for a gallery, and it includes quite a few interesting features:

  • Scrolling thumbnail navigation
  • Fullscreen mode
  • Automatically loads higher quality images in fullscreen mode
  • Responsive images using media queries
  • Keyboard arrow navigation

To set up a gallery like this, all that’s required is suitable images and $.fn.royalSlider with the options along these lines:

$('#gallery-1').royalSlider({
  fullscreen: {
    enabled: true
  , nativeFS: true
  }
, controlNavigation: 'thumbnails'
, autoScaleSlider: true
, autoScaleSliderWidth: 960
, autoScaleSliderHeight: 850
, loop: false
, numImagesToPreload: 4
, arrowsNavAutoHide: true
, arrowsNavHideOnTouch: true
, keyboardNavEnabled: true
});

The option names are fairly verbose so it’s easy to tell what they do, but I’ll go over the main ones below.

  • autoScaleSlider: This automatically updates the slider height based on the width, most of the examples use this option
  • numImagesToPreload: Sets the number of images to load relative to the current image
  • arrowsNavAutoHide: Hide the navigation arrows when the user isn’t interacting with the plugin

Mobile Support

RoyalSlider running on Android and iOS

RoyalSlider includes several ways to support touchscreen devices. Swipe gestures work as expected, and there are a couple of relevant options:

  • arrowsNavHideOnTouch: Always hide arrows on touchscreen devices
  • sliderTouch: Allows the slider to work using touch-based gestures

There are also events for dealing with gestures, which you can hook into like this:

sliderInstance.ev.on('rsDragStart', function() {
  // mouse/touch drag start
});

sliderInstance.ev.on('rsDragRelease', function() {
  // mouse/touch drag end
});

I tested the plugin using several examples on iOS and Android 4.1 and was generally impressed by the performance.

Code Review

When I look at jQuery plugins I usually run through the advice found in the jQuery Plugin Authoring Guide. I’d like to only write about plugins that are well-written, and you’d be surprised how many are not, given that the jQuery team has worked hard to document exactly how to write a plugin. With that in mind, I took a look at RoyalSlider’s source to see how it stacks up.

RoyalSlider is split up into separate files using a modular approach. That enables the build tool to only include what’s necessary, so it’s actually pretty trivial to make a build directly suited to a given project. The code is also consistently formatted, so I strongly recommend downloading the development version just in case you’ve got questions that aren’t answered by the documentation – the code is easy enough to understand for an intermediate jQuery developer.

All of these modules and the main source file are wrapped in closures, so RoyalSlider doesn’t introduce any messy globals.

Most of the plugin’s code is based around a standard JavaScript constructor, which also adds to its readability. This made me wonder if the author intends to port it to other JavaScript frameworks, because it seems like large portions of functionality are neatly encapsulated from jQuery’s API.

In terms of low-level DOM coding and animation performance, it has Paul Irish and Tino Zijdel’s requestAnimationFrame fixes, and uses CSS vendor prefixing where required.

Namespacing

RoyalSlider adds these methods and objects to $:

  • $.rsProto
  • $.rsCSS3Easing
  • $.rsModules
  • $.fn.royalSlider

In general plugins should limit how many things they add to $, but I felt like the author has been careful here and only exposed what’s necessary.

  • Namespaces events and CSS classes, example: keydown.rskb
  • Correctly tracks state using royalSlider .data attribute

Other Notes

Most jQuery plugin authors seem to miss the section on using $.extend to handle options, but I was pleased to see Dmitry has done this. The main jQuery method also returns this, so calls after .royalSlider can be chained as expected.

Support and Community

RoyalSlider has its own Tender-powered support site, and the author also talks to users through his Twitter account: @dimsemenov.

WebSpecter, cerebral.js, Mobify.js

03 Sep 2012 | By Alex Young | Comments | Tags testing frameworks libraries backbone.js mobile

WebSpecter

WebSpecter (License: MIT) by Juliusz Gonera is an acceptance test framework built using PhantomJS. The author’s examples are written with CoffeeScript, but it can be used with JavaScript as well.

The tests use a BDD-style syntax, based around “features” and CSS selectors:

feature "GitHub search", (context, browser, $) ->
  before (done) -> browser.visit 'https://github.com/search', done

  it "finds WebSpecter", (done) ->
    $('input[name=q]').fill 'webspecter'
    $(button: 'Search').click ->
      $(link: "jgonera / webspecter").present.should.be.true
      done()

  it "looks only for users when asked to", (done) ->
    $('input[name=q]').fill 'webspecter'
    $(field: 'Search for').select 'Users'
    $(button: 'Search').click ->
      $(link: "jgonera / webspecter").present.should.be.false
      done()

The browser object is a wrapper around Phantom’s WebPage. A $ function is also present which is jQuery-like but not implemented using jQuery.

cerebral.js

cerebral.js (GitHub: gorillatron / cerebral) by Andre Tangen extends Backbone.js to provide a module system and a publish/subscribe application core. It uses RequireJS for modules and module loading, and modules are restricted to a “sandbox” designed to limit the elements the module has access to.

The main motivation behind cerebral.js is to encourage loosely coupled applications. When I’m working on my own Backbone.js applications I usually adopt a similar approach, so it’s reassuring to see the same ideas in a framework.

Mobify.js

Mobify.js (GitHub: mobify / mobifyjs, License: MIT, npm: mobify-client) is a new client-side web framework that aims to make it easier to adapt sites to any device. This includes responsive design techniques, but it can also be backed by a cloud service called Mobify Cloud that includes automatic image resizing, JavaScript concatenation, and a CDN. Mobify.js projects are built with Zepto and Dust.js.

The Mobify.js authors have also been building MIT-licensed Mobify.js modules, at the moment there’s a carousel and an accordion.