jQuery Roundup: SliderShock, printThis, readMore

13 Nov 2012 | By Alex Young | Comments | Tags jquery slideshow printing truncation sponsored-content
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

jQuery SliderShock

SliderShock example

jQuery SliderShock is a responsive slider plugin that can be dropped into WordPress sites. There’s full documentation for regular websites and WordPress sites. The WordPress version has some additional features, like built-in support for sliders from external data sources like RSS. The plugin supports various options, including up to 31 transition effects, control over delay time and positioning, and easy styling.

Clicking Build Your Own on the SliderShock homepage displays all of the available options:

SliderShock options

SliderShock can display text captions within slides, and comes bundled with lots of CSS3-based effects. The free version, licensed for use in personal projects, has 10 effects, and the premium version has 31 effects and 39 skins. A license for a single site costs $19, while multiple sites costs $29. There’s also a developer license for $99 that allows resale. “Combo” licenses are available if you wish to buy both the WordPress and jQuery versions at once, otherwise you’ll have to license them separately.

jquery.printThis

jquery.printThis (License: MIT/GPL) by Jason Day is a fork of permanenttourist / jquery.jqprint, and based on Ben Nadel’s Ask Ben: Print Part Of A Web Page With jQuery post – a combination of several things to solve the problem of printing a given element on a page. Jason’s changes can optionally include page styles, import additional stylesheets, and avoids using document.write.

It’s interesting to see how this works internally – the plugin is concise but it takes a bit of iframe manipulation to get the desired results.

jQuery.readMore

Dealing with dynamically truncating content is tricky, and there are many solutions out there. Stephan Ahlf sent in his solution, jQuery.readMore (GitHub: s-a / jQuery.readMore, License: MIT/GPL) which uses a method called $.isOverflowed to add text until there isn’t room for any more.

Previously covered related plugins include jQuery.smarttruncation, and jQuery.textFit.

How Does Watch.js Work?

12 Nov 2012 | By Alex Young | Comments | Tags observer code-review

Last week noticed a lot of interest in Watch.js (License: MIT) by Gil Lopes Bueno, so I thought it would be interesting to take a look at how it works. It allows changes to properties on objects to be observed – whenever a change is made, a callback receives the new and old values, as well as the property name:

var ex1 = {
  attr1: 'initial value of attr1'
, attr2: 'initial value of attr2'
};

ex1.watch('attr1', function() {
  alert('attr1 changed');
});

The watch method can also accept an array of property names, and omitting it will cause the callback to run whenever any property changes. The unwatch method will remove a watcher.

First, let’s get the elephant out of the room: this implementation modifies Object.prototype – that’s where the watch method comes from in the previous example. The author is planning to change the API to avoid modifying Object.prototype.

Second, this method is polymorphic in that it behaves differently based on the supplied arguments. This is quite common in client-side code. It’s implemented by looking at the number of arguments without requiring too much type checking, in watch:

WatchJS.defineProp(Object.prototype, "watch", function() {

    if (arguments.length == 1) 
        this.watchAll.apply(this, arguments);
    else if (WatchJS.isArray(arguments[0])) 
        this.watchMany.apply(this, arguments);
    else
        this.watchOne.apply(this, arguments);

});

You’re probably wondering what WatchJS.defineProp is. It’s actually a convenience method to use ES5’s Object.defineProperty in browsers that support it:

defineProp: function(obj, propName, value){
    try{
        Object.defineProperty(obj, propName, {
                enumerable: false
            , configurable: true
            , writable: false
            , value: value
            });
    }catch(error){
        obj[propName] = value;
    }
}

The watchMany method uses a utility method, WatchJS.isArray, to determine how to loop over the supplied arguments, calling watchOne on each in turn. The watchAll method calls watchMany, so there’s a lot of internal code reuse.

Most of the work gets carried out by watchOne. This calls WatchJS.defineGetAndSet(obj, prop, getter, setter) with a custom getter and setter to wrap around values so they can be watched. However, watching values change has a few complications.

For one thing, arrays have mutator methods like push and pop. Therefore, watchFunctions is called to wrap each of these methods with a suitable call to WatchJS.defineProp. Also, when a property is set to a new value, all of these wrapped methods will be lost. To get around this, the custom setter calls obj.watchFunctions(prop) again.

When a value has changed, callWatchers is called. An internal list of watcher callbacks indexed on property names is maintained and called by a for-in loop. It’s important to note that these callbacks only run if the values are actually different. This is tested by calling JSON.stringify(oldval) != JSON.stringify(newval) – presumably the author used this approach because it’s an easy way to compare the value of objects. I’d consider benchmarking this against other solutions.

Finally, we get to WatchJS.defineGetAndSet, which attempts to use Object.defineProperty if available, otherwise Object.prototype.__defineGetter__.call and Object.prototype.__defineSetter__.call are used.

Conclusion

Rather than using exceptions to track browser support, it might be better to use capability testing to check for Object.defineProperty and Object.prototype.__defineGetter__.call when the first call is made, then cache the result. As noted in the project’s issues, Object.observe should provide a more efficient approach in the future – this is an accepted Harmony proposal.

To really mature this project, changing the API to avoid modifying Object.prototype would be a good idea, and adding benchmarks and unit tests would be useful as well.

This article was based on watch.js commit dc9aac6a6e.

Ditto, sudo.js, dry-observer

09 Nov 2012 | By Alex Young | Comments | Tags mvc backbone.js dojo libraries

Ditto

Ditto (GitHub: bitpshr / ditto, License: WTFPL) by Paul Bouchon is a tool for resolving a project’s Dojo dependencies. A project’s zip file can be dropped onto the site, and it will analyse it and extract all of the required AMD modules. There’s an options tab that has an option for the legacy dojo.require syntax, and paths can be ignored as well.

sudo.js

sudo.js (License: MIT, npm: sudoclass) by Rob Robbins (sent in by Yee Lee) is a library that features inheritance helpers, view and view controllers, and data binding support. The API is documented in the sudo.js wiki.

The author has included a test suite, compatibility polyfills for things like the console object and String.prototype.trim, and an optional build with a small templating library.

dry-observer

dry-observer (License: MIT) by Austin Bales is a small library for working with centralising binding and unbinding to events, while encouraging consistent handler naming. It requires a Backbone.js or at least a Backbone.Events-compatible object.

Here’s a quick example by the author:

# Observe a Model by passing a hash…
@observe model,
  'song:change'   : @onSongChange
  'volume:change' : @onVolumeChange
  'focus'         : @onFocus

# …or a String or Array.
# Observation will camelCase and prefix your events.
@observe model, 'song:change volume:change focus'

# Stop observing and dereference your model…
@stopObserving model

# …or stop observing /everything/
@stopObserving()

AngularJS: Common Pitfalls

08 Nov 2012 | By Alex Young | Comments | Tags mvc angularjs backbone.js

I noticed this commit to AngularJS by Braden Shepherdson that updates the AngularJS FAQ with a list of common pitfalls to avoid. Some of these pieces of sage advice can be applied to other MVC frameworks like Backbone.js, or at least act as some inspiration:

Stop trying to use jQuery to modify the DOM in controllers. Really. That includes adding elements, removing elements, retrieving their contents, showing and hiding them.

Similarly, the Backbone.js documentation advises the use of scoped DOM queries. Also, Backbone patterns suggests ensuring event handlers are correctly abstracted rather than using jQuery event handlers outside of Backbone.js code.

If you’re struggling to break the habit, consider removing jQuery from your app.

This might seem drastic, but AngularJS packs in enough functionality to get by without jQuery for the most part. The FAQ suggests using jQLite for binding to events.

There’s a good chance that your app isn’t the first to require certain functionality. There are a few pieces of Angular that are particularly likely to be reimplemented out of old habits.

After this the author describes how to take advantage of ng-repeat, ng-show, and ng-class. It’s the kind of practical knowledge that comes from hard-won experience, but it’s all explained quite clearly here. For example, ng-class can accept objects, including conditional expressions:

<div ng-class="{ errorClass: isError, warningClass: isWarning, okClass: !isError && !isWarning }">...</div>

Although AngularJS, Backbone.js, and Knockout all have great documentation, I feel like the learning curve once the basics have been mastered is pretty tough. It’s good to see these low-level tips cropping up to clarify how the authors intend the project to be used.

Node Roundup: Fastworks.js, Probability.js, Colony

You can send in your Node projects for review through our contact form or @dailyjs.

Fastworks.js

Fastworks.js (License: GPL3, npm: fastworks) by Robee Shepherd is an alternative to Connect. It includes “stacks” for organising middleware, and middleware for routing, static files, compression, cookies, query strings, bodies in various formats (including JSON), and a lot more. It can also work with Connect modules.

StaticFile serves things like images, style sheets and javascript files, using the pretty nifty Lactate node module. According to the author’s benchmarks, it can handle more than twice the requests per second that Connect’s Send module can.

That Lactate module sounds promising. On the subject of performance, one motivation for developing Fastworks.js was speed, but as of yet it doesn’t include benchmarks or tests. Hopefully the author will include these at a later date so we can see how it shapes up against Connect.

Probability.js

Probability.js

Probability.js (License: MIT) by Florian Schäfer is a fascinating little project that helps call functions based on probabilities. Functions are paired alongside a probability so they’ll only be called some of the time.

That doesn’t sound useful on the surface, but the author suggests it could be useful in game development. Although if you’ve played the recent XCOM game you may be disillusioned by randomness in games, which is actually quite a well-trodden topic in the games development community. Analysis: Games, Randomness And The Problem With Being Human by Mitu Khandaker is an interesting analysis of games and chance.

Colony

Colony

Colony (GitHub: hughsk / colony, License: MIT, npm: colony) by Hugh Kennedy displays network graphs of links between Node code and its dependencies, using D3.js.

The network can be navigated around by clicking on files – the relevant source will be displayed in a panel. Files are coloured in groups based on dependencies, so it’s an intuitive way to navigate complex projects.

jQuery Roundup: Airbnb Style Guide, jPanelMenu, Crumble, imgLiquid

06 Nov 2012 | By Alex Young | Comments | Tags jquery style-guides images on-page guidance mobile
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

Airbnb JavaScript Style Guide

Airbnb JavaScript Style Guide is a pretty detailed JavaScript style guide that includes suggestions for jQuery. As a bonus, the Resources section includes links to other style guides (and DailyJS, thanks Airbnb!)

I’ve been using Google’s Style Guide for a few projects, although I don’t necessarily have a preference for any style guide. The code style used in examples on DailyJS came from trying to use horizontal space effectively (the blog has a fixed-width narrow design), but also by trying to make things explicit for beginners. Even these humble goals are subjective enough to cause endless arguments. The best advice I could give on the matter is to pick a style and be consistent.

jPanelMenu

jPanelMenu screenshot

jPanelMenu (GitHub: acolangelo / jPanelMenu) by Anthony Colangelo creates a navigation panel similar to those found in recent mobile applications. It can be configured to use selectors for the menu and an element that opens the menu:

var jPM = $.jPanelMenu({
  menu: '#custom-menu-selector'
, trigger: '.custom-menu-trigger-selector'
});

jPM.on();

This creates two div elements that contain the menu and the corresponding panel for the content.

jPanelMenu is well documented, and the documentation itself is built using the plugin so it doubles as a detailed example.

Crumble

Crumble (GitHub: tommoor / crumble, License: MIT) by Tom Moor is an interactive tour built using grumble.js. Similar to the plugins mentioned by Oded Ben-David in Introduction to On-Page Guidance, Crumble shows help bubbles that draw attention to elements on a page.

imgLiquid

imgLiquid (GitHub: karacas / imgLiquid, License: MIT/GPL) by Alejandro Emparan is a plugin for resizing images to fit a given container. It can try to fill a container or shrink the image instead, by using CSS:

$(selector).imgLiquid({ fill: true });

There’s also a fadeInTime option that’ll trigger a fadeTo animation.

State of the Art: Web MIDI API

05 Nov 2012 | By Alex Young | Comments | Tags standards sota audio browser

In a previous life I wrote a lot of music, so I have a certain amount of familiarity with MIDI. Mentioning MIDI to non-musicians usually results in either a disbelief that MIDI still exists, or nostalgia for 90s PC games (I’m a big LucasArts fan). So if you’re not familiar with MIDI, it’s not all about bad sounding music files on GeoCities, it’s actually a specification for networking musical instruments, computers, and a wide variety of wonderful hardware.

Yamaha's Tenori-On can act as a slightly more unusual way to control MIDI devices.

The Web MIDI API was published as a working draft on the 25th of October, with input from Google’s Chris Wilson. It outlines an API that supports the MIDI protocol, so future web applications will be able to enumerate and select MIDI input and output devices, and also send and receive MIDI messages. This is distinct from playing back MIDI files – the HTML5 <audio> element should take care of that.

JavaScript-powered MIDI strikes me as of particular interest to both musicians and makers – hackers building art installations or novel control schemes for music projects.

Code

The navigator object, typically used to query user agent information, provides interfaces to a few new APIs like geolocation. The MIDI API uses it to expose MIDI access, and then available devices can be iterated over and inspected further:

navigator.getMIDIAccess(function(MIDIAccess) {
  var inputs = MIDIAccess.enumerateInputs()
    , outputs = MIDIAccess.enumerateOutputs()
    ;
});

MIDI messages can then be sent and received. There’s a test suite by Jussi Kalliokoski with more JavaScript examples here: web-midi-test-suite.

Implementation Progress

There’s currently a low-level MIDI plugin called Jazz-Plugin. For tracking browser support and other audio-related topics, the most accessible source is probably the HTML5 Audio Blog written by Jory K. Prum.

References

Introduction to On-Page Guidance

02 Nov 2012 | By Oded Ben-David | Comments | Tags on-screen guidance on-page guidance iridize tutorials

My name is Oded Ben-David, and I’m a co-founder at Iridize – a service for enhancing website user-experience through on-screen guidance. Documentation is important to new users of a software product, yet it’s typically added as an afterthought. Worse, users don’t always want to spend time reading documentation. On-screen guidance turns this on its head by showing help where and when it’s needed.

On-screen guidance is becoming more commonplace on the web. It is used by prominent companies including Facebook, Yahoo, and Google. Additionally, several JavaScript libraries for website on-screen guidance were published recently, most of which are mentioned below.

On-screen guidance seeks to solve two issues: presenting help when and where it is needed. It should propel users to their goals and keep them focused on the task at hand, not stop them in their tracks and point their attention elsewhere, to external help texts and videos. Also, guidance should only be there when the user actually wants it. Permanently cluttering a web page with too much help will end up confusing users.

To actually implement this, on-screen guidance systems use an interactive layer over a web page that is activated either on-demand, or automatically based on business logic.

By guiding users step-by-step throughout fulfilling a task they are always focused on the task at hand. This provides first time users with an interactive site tour which helps illustrate key features.

These tools are not just for help content. Pointing out newly added or key but underused features can also benefit from being presented in a dedicated layer. This dedicated layer can also serve for increasing conversion, by inviting users to sign-up or subscribe, as well as increase user engagement by enticing them to try up a service or a feature. It can easily be coupled with A/B testing services to further optimize conversions.

Tutorial: Open Source On-Screen Guidance

There are several JavaScript libraries available for adding on-screen guidance to your project:

  1. king_tour is probably one of the earliest available libraries. Tours are defined as markup using a simple structure based around containers and title attributes. Global options and tour activation are handled by JavaScript.
  2. Joyride is a more modern jQuery plugin that takes a similar approach.
  3. A different approach is taken by the very nice bootstrap-tour (reviewed in DailyJS), where steps are defined using a factory method, rather than in markup. Bootstrap-tours also manages a simple state and allows for some multi-page capabilities.
  4. Guiders.js by the good people of Optimizley, is another library where guides can be automatically started using a special hash parameter, and an optional overlay can be used to highlight the element the guider refers to on the page.

Let’s take a look at how to create a guide using the Guiders.js library. For the purpose of this short demonstration I have created a jsFiddle, where you can see the final result. The first thing we need for our demo is some page markup. I chose the markup for a bug-tracking form from the free gallery at wufoo. Next, we need to embed jQuery, and the Guiders.js JavaScript and CSS files. jQuery is readily available via jsFiddle’s default libraries. For this demo I am serving the Guiders.js sources from via our own CDN (so please do not hotlink there).

<script type="text/javascript" src="https://static-iridize.netdna-ssl.com/static/guiders/guiders-1.2.8.js"></script>
<link rel="stylesheet" type="text/css" href="https://static-iridize.netdna-ssl.com/static/guiders/guiders-1.2.8.css">

Now that we are all set we can start adding guiders. For starters, let’s add an introductory ‘splash’ tip with an overlay. Note that this bit of code should be executed on DOM ready event. This is the JavaScript for creating the first tip:

guiders.createGuider({
  buttons: [{ name: 'Next' }]
, description: 'Introducing Guiders.js for the DailyJS readers. I am the first tip. Click my Next button to get started.'
, id: 'first'
, next: 'second'
, overlay: true
, title: 'Demoing Guiders.js!'
}).show();

There’s quite a bit going on here, so I’ll break it down. First, as mentioned before, guiders are created using the createGuider method, which accepts a configuration object containing the guider options. Guider ids are used for chaining them together using the next property. This guider is set as first, and the next guider will be the one with id second. Setting the overlay property to true tells sets an overlay mask blocking the rest of the page.

The buttons property sets which buttons should be displayed at the bottom of the tip. This property accepts an array of button definition objects. You can define custom buttons and custom button behaviors, but the three default buttons available are Next, Close, and Prev. For this first tip we set only a single Next button, used for going forward.

You may have noticed that there’s another method call chained to the createGuider call, namely .show(). Guiders are created hidden by default, so the show() method is called to show the first tip automatically. Of course, we could have saved a reference to the created guider in a variable instead, and issued the show call at a later time.

Now that the first guider is ready, a second can be added:

guiders.createGuider({
  attachTo: '\#foli0'
, buttons: [{name: 'Close'}, {name: 'Next'}]
, description: 'Please write down the full URL of the page where you experienced a bug. You can copy paste it from the address bar.'
, id: 'second'
, next: 'third'
, position: 3
, title: 'Oh Where?'
});

This guider has two new properties: attachTo and position. The attachTo property accepts a selector for the element next to which the tip should be positioned. The position property specifies the position of the tip relative to the element specified by attachTo. The number stands for ‘clock position’, so specifying 3 makes the tip appear to the right of the element. This tip also has an option to close the guide, by adding the Close button to the buttons array. Also, note that show() was not called for this guider, as it should only be shown when clicking the Next button on the previous tip.

The rest of the tips in this short demo are more of the same. You can find the full reference of guider options on the Guiders.js repository page.

Iridize

Video showing one of the demos available at iridize.com

Our vision for Iridize was that the developer should not be required to create or maintain guidance material. Creating and embedding on-screen guidance should be at least as easy as creating a presentation. This should leave developers with more time to code instead of writing help guides.

Iridize is the realization of that vision - on-page guidance and site-tours as a service.

We created a fully visual editor which runs in the browser. This means that there is absolutely no installation required to get started. Other than embedding a generic JavaScript snippet there is no setup necessary even for deployment (similar to embedding Google Analytics). All JavaScript and guidance content is loaded from our servers, and delivered through a CDN – with SSL if necessary. Our service includes a full management system, complete with an editing and publishing cycle that supports collaboration for guide creation.

True to the spirit of providing guidance where and when it is needed, our guides can be launched by the end user from a side-panel or launched automatically based on the page path, parameters, or a hash URL fragment. We provide an API for even tighter control on how guides are started.

We are now in a close beta phase, and we would like to invite you to take a look and register for a beta account. Moreover, as we are keen on giving back to the wonderful JavaScript community that built so many of the great tools we are using, we would like to offer free service to select open-source projects for the long term. Please contact us if you are member of the core team of such a project that could benefit from our services (even if just for your public website).

Conclusion

On-screen guidance can be a powerful tool for enhancing user-experience and improving website usability. Providing guidance where and when it is needed can alleviate the pains of first time and occasional website users, as well as expose new feature to the experienced crowd. Guiding users step-by-step keeps them focused and can ensure they don’t miss or forget steps along the way.

Whether you choose to use Iridize to implement on-screen guidance in your projects or decided to take the DIY route with one of the libraries I listed, we are certain that your users will thank you for helping them out!

Node Cookbook Winners

01 Nov 2012 | By Alex Young | Comments | Tags node giveaways books

In one week, 415 people entered the Node Cookbook giveaway. I feel guilty that we only have five books to give out! From this I can only assume that there’s a huge amount of interest in Node, or people thought it was a new kind of molecular gastronomy. Either way, here are the winners:

  • Francesco Lentini
  • De Bollivier Sébastien
  • Jason Serovi
  • Janghwan Kim
  • Joakim Bengtson

Winners will be contacted through email by Packt (@packtpub.com) and will receive a digital copy of the book.

Coincidentally, I also won a book this week. It was Practical Vim: Edit Text at the Speed of Thought, and I reviewed it over at usevim.com: Book Review: Practical Vim. Vim is my editor of choice, and I’ve been running usevim.com alongside DailyJS for a few months now. Check it out, and if you prefer Emacs I’m cool with that too!

Node Roundup: 0.8.14 and 0.9.3, Orange Mocha Frappuccino, Crawlme, WebSocketIPC

31 Oct 2012 | By Alex Young | Comments | Tags node modules websockets testing mocha crawling
You can send in your Node projects for review through our contact form or @dailyjs.

0.8.14 and 0.9.3

Last week, 0.8.14 and 0.9.3 were released. The 0.8.14 release is basically the 0.8.13 release with a fix for EventEmitter:

Note: v0.8.13 contains a regression in the EventEmitter class. This is a bugfix release, but contains no new features. Most of the release notes are copied from v0.8.13, since it didn’t live long.

The 0.9 release updates V8 and has various bug fixes. It also adds an options argument to util.inspect – the older API had three arguments, so reducing the arity makes sense as new options can be supported more easily.

Orange Mocha Frappuccino

Orange Mocha Frappuccino (License: MIT, npm: omf) by Brian Carlson is a library to help build HTTP verification tests with Mocha. It can accept a Node HTTP server or URLs:

var omf = require('omf');
var assert = require('assert');

omf('https://github.com', function(client) {
  client.get('/brianc/node-omf', function(response){
    response.has.statusCode(200);
    response.has.body('ORANGE MOCHA FRAPPUCCINO');

    //the full response is available to any custom tests:
    it('has ETag header', function() {
      assert(this.response.headers['etag']).ok();
    });
  });
});

This is a little bit more like how Expresso worked, which was TJ’s pre-Mocha test framework.

Crawlme

Crawlme (License: MIT, npm: crawlme) from Optimal Bits is Connect middleware for automatically mapping hashbang URLs to parameter-based URLs for Googlebot Ajax Crawling.

WebSocketIPC

WebSocketIPC (License: GPL) by Nicolas Froidure is a proof-of-concept of his VarStream “variable exchange format”. This format is designed to be human readable, streamable, and self-referencial.

WebSocketIPC uses WebSockets to synchronise a variable tree between multiple clients and a server. It can also synchronise data between multiple Node instances by piping VarStreams.

It’s interesting that as interest in using streams grows more diverse projects are appearing to better exploit their properties.

jQuery Roundup: jQuery UI 1.9.1, IndexedDB on Cordova, Backbone.ViewKit

30 Oct 2012 | By Alex Young | Comments | Tags jquery jquery-ui indexeddb backbone.js
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

jQuery UI 1.9.1

jQuery UI 1.9.1 was released a few days ago. This is a maintenance release that includes bug fixes for many widgets and the core library. The jQuery UI 1.9.1 Changelog has full details of the fixes.

Bootstrap 2.2.0

Bootstrap 2.2.0 templates

Bootstrap 2.2.0 is out. This version includes much needed additional templates, a media component, a new variable-driven typographic scale, and other more minor tweaks.

IndexedDB on Cordova

Parashuram Narasimhan has got his IndexedDB polyfill working on on Cordova. This means it can be used with iOS and Android applications:

Parashuram’s posts include details on the techniques he uses to get IndexedDB working on each platform. For example, with Android he currently has to use JavaScript to inject the polyfill during the deviceready event.

Backbone.ViewKit

Backbone.ViewKit (License: MIT) by Scott Nelson is a Backbone.js plugin for managing views with transitions in an iOS-inspired fashion. It adds Backbone.ViewKit.ViewPort which renders sets of views, displaying one at a time. Stacks of views are managed using Backbone.ViewKit.ViewStack, which allows views to be pushed or popped as required.

Transition animations can be triggered using Backbone.ViewKit.Transition:

new Backbone.ViewKit.Transitions.Slide({
   reverse: false
 , duration: 0.4
 , easing: 'ease-out'
 , delay: 0
});

There’s a demo here: Backbone.ViewKit demo.

Connecting Fuel UX Datagrid to the Flickr API

29 Oct 2012 | By Adam Alexander | Comments | Tags bootstrap fuelux tutorials

Fuel UX (GitHub: ExactTarget / fuelux, License: MIT) extends the revolutionary Twitter Bootstrap with some additional JavaScript controls. One of these controls is the Datagrid, and today I’m going to show you how to add the Datagrid to a page and connect it to a third party API.

Demo

Step One: Basic Fuel UX Page

There are a couple of resources I recommend for getting started with a basic Fuel UX page:

Once you have Fuel UX on your page, you’re ready to add the Datagrid!

Step Two: Adding the Datagrid

Just like in Bootstrap, you can add most Fuel UX controls to a page by simply adding some markup and they will be instantiated automatically.

View the markup for this example

Since the Datagrid needs to be connected to some data to be useful, we will need a little JavaScript to instantiate the control.

$('#MyGrid').datagrid({
  dataSource: new FlickrDataSource({

    // Column definitions for Datagrid
    columns: [{
      property: 'image',
      label: 'Image',
      sortable: false
    },{
      property: 'title',
      label: 'Title',
      sortable: false
    }],

    // Create IMG tag for each returned image
    formatter: function (items) {
      $.each(items, function (index, item) {
        item.image = '<img src="' + flickrUrl(item) + '"></a>';
      });
    }
  })
});

Step Three: Provide the Data Source

To connect the Datagrid to some data, we just need a data source to act as an adapter. The data source’s responsibilities are:

  1. Provide column info
  2. Provide data when requested by the Datagrid

For this example, I created a simple datasource to communicate with the Flickr API.

View the data source for this example

Conclusion

I hope this tutorial is helpful in getting your own use of the Datagrid off the ground, and in using Fuel UX in general. The Fuel UX contributors and I are excited to have you on board! Next steps:

Dynamic Invocation Part 1: Methods

26 Oct 2012 | By Justin Naifeh | Comments | Tags reflection dynamic invocation method

Today we will explore dynamic invocation, which is a clever way of saying “invoke a method using the string method name.” Many people, including myself, refer to this as reflection, which is terminology borrowed from Java’s Reflection library. Because we don’t want to be sued, especially on a Friday, this will be known as dynamic invocation in the article, although it probably goes by other names.

JavaScript benefits from dynamic invocation because the capability is intrinsic to the language; no library is required. This means we can leverage dynamic invocation in all JavaScript environments! The question is…how?

The Interview Question

This is one of many interview questions I created at my company to test a developer’s knowledge of the JavaScript language.

We start with a basic domain class called Employee.

Employee_UML

In case you want to float code in your head or test it yourself, here’s the (optional) reference implementation.

/**
 * Constructor for the Employee class.
 * @param String name The full name of the employee.
 * @param String position The employee's position.
 */
var Employee = function(name, position) {
  this._name = name;
  this._position = position;
};

Employee.prototype = {
  /**
   * @return String The Employee's name.
   */
  getName: function() {
    return this._name;
  },
  
  /**
   * @return String The Employee's position.
   */
  getPosition: function() {
    return this._position;
  },
  
  /**
   * Promotes an Employee to a new position.
   * @param String The Employee's new position.
   */
  promote: function(newPosition) {
    this._position = newPosition;
  }
};

We assume the following instance of Employee for the question:

var emp = new Employee("Tom Anders", "junior developer");

After years of hard work, Tom Anders has been promoted to “senior developer,” which must be evaluated by the code. The application in which this is hosted, due to its architecture, does not have direct knowledge of the promote() method. Instead, only the method name is known as a string. Given the following code setup, how does one promote Tom to senior developer?

var emp = new Employee("Tom Anders", "junior developer");

// ...

var method = "promote";
var newPosition = "senior developer";

// promote emp [Tom] to the position of newPosition
// ...???

How would you execute promote() in the context of emp?

There are two answers, both of which are correct, although one is more dynamic and powerful than the other.

The first answer casts the mantra eval is evil aside in the name of convenience. By concatenating the variable name with the method name and input a developer can promote the employee.

eval("emp."+method+"(\""+newPosition+"\")");
console.log(emp.getPosition()); // "senior developer"

This works…for now. But keep in mind that not only is the arbitrary execution of code insecure, new variables cannot be created by eval() in ES5’s strict mode. The solution will not scale over time.

Without eval() how could we possibly invoke the method? Remember that methods are like any other properties, and once attached to the object or its prototype it becomes accessible via bracket notation.

console.log(emp["promote"] === emp[method]); // true
console.log(emp[method] === emp.promote); // true
console.log(emp[method] instanceof Function); // true

Knowing this we can dynamically invoke the method with the arguments we want.

emp[method](newPosition);
console.log(emp.getPosition()); // "senior developer"

This style of invocation is effective but vanilla. It assumes the number of arguments are known and the this context is the object referencing the method. This is only the tip of the iceberg, for invocation can be much more dynamic when the arguments and this context are unknown beforehand.

Before advancing, note that each object has an implicit property that references its defining class’s prototype, thus solidifying the relationship between a class and its instances.

console.log(emp.promote === Employee.prototype.promote); // true
console.log(emp.__proto__ === Employee.prototype); // true
console.log(emp.__proto__.promote === Employee.prototype.promote); // true

With this in mind, we can combine class, prototype, and object references with the string method to achieve truly dynamic invocations. This will help us demystify calls ubiquitous in framework and library code (e.g., Array.prototype.slice.call(arguments, 0, arguments.length)).

call() and apply()

Just as the class Employee defines promote(), the class Function defines methods call() and apply(), which are methods on methods. In other words, methods–instance/member functions–are first-class objects in JavaScript, hence its functional nature!

The methods call() and apply() take the same first argument, the this context of execution. The second argument of call() is n-arguments in explicit order, while apply() takes a single array where each element is an argument that is flattened in order as if call() were applied. Using the class’s prototype we can statically access methods yet execute them with a specific context.

// call
Employee.prototype[method].call(emp, newPosition);

// apply
Employee.prototype[method].apply(emp, [newPosition]);

console.log(emp.getPosition()); // "senior developer"

This syntax can also be used with the object itself because emp[method] === Employee.prototype[method].

// call
emp[method].call(emp, newPosition);

// apply
emp[method].apply(emp, [newPosition]);

console.log(emp.getPosition()); // "senior developer"

It might seem redundant to specify the context as emp when invoking promote() on that object, but this is the required syntax, and it allows for variable arguments.

Regardless of the syntax used, dynamic invocation is extremely flexible and introspective. Once the class, prototype, object, and property relationships are understood, a developer can manipulate the language and its constructs in clever ways. Unsolvable problems become solvable.

Conclusion

Dynamic invocation is useful when generating JavaScript code from the server or when matching aspect-oriented rules. And sometimes it’s just helpful to avoid the rightfully deprecated eval().

In part 2 I will go into detail about dynamic invocation and constructors.

Giveaway: Node Cookbook

25 Oct 2012 | By Alex Young | Comments | Tags node giveaways books

This competition has now closed.

Packt Publishing has five copies of Node Cookbook by David Mark Clements to give away. Node Cookbook is a recipe-style book that aims to teach you everything you need to able to publish modules with npm, work with databases, handle streams, and also includes plenty of coverage on web development with Express.

If you’re a client-side developer looking to learn more about Node, then it’s a great jumping off point.

The Rules

  • Post a message using our general contact form. Winners will be chosen at random.
  • Winners will be contacted by email.
  • The competition has ended.

Node Roundup: Express 3.0, Declare, Sourcery

24 Oct 2012 | By Alex Young | Comments | Tags node modules http frameworks express object-oriented
You can send in your Node projects for review through our contact form or @dailyjs.

Express 3.0

Express 3.0 (GitHub: visionmedia / express, License: MIT, npm: express) has been released, announced by TJ in a blog post with more details on Express 3.0 and Connect 2.

There’s a 2.x to 3.x migration guide and a list of Express 3.x features. In particular, express() now returns a Function that can be used with Node’s http.createServer, you’ll need to update the way helpers work, and there are a few changes to the request and response objects.

The Express website now also includes a list of applications powered by Express, which is useful for those of us evaluating frameworks for use in a new project.

Declare

Declare (GitHub: doug-martin / declare.js, License: MIT, npm: declare.js) by Doug Martin is an attempt to help write object oriented code that runs on both the client and server. The resulting classes can be used with RequireJS, and support features like mixins, super methods, static methods, and getters and setters.

The author has included some simple tests, and detailed usage examples.

Sourcery

Sourcery (License: MIT, npm: sourcery) by Veselin Todorov is designed for creating RESTful API clients. It’s influenced by ActiveResource, so it should work well with many CRUD-oriented REST APIs. It supports basic authentication as well:

var BasicAuth = require('sourcery').BasicAuth;

var Base = Resource.extend({
  host: 'http://example.com/api/v1'
, auth: {
    type:  BasicAuth
  , user: 'replace-with-real-user'
  , pass: 'replace-with-real-pass'
  }
});

It includes Mocha tests, and is built using the popular request HTTP client library by Mikeal Rogers.

jQuery Roundup: Fuel UX, uiji.js, QuoJS

23 Oct 2012 | By Alex Young | Comments | Tags jquery jquery-ui bootstrap mobile
Note: You can send your plugins and articles in for review through our contact form or @dailyjs.

Fuel UX

Fuel UX

Fuel UX (GitHub: ExactTarget / fuelux, License: MIT) from ExactTarget is a lightweight library that extends Twitter Bootstrap with some additional JavaScript controls, a Grunt build, and AMD compatibility. At launch, the following controls are included:

  • Combobox - combines input and dropdown for easy and flexible data selection
  • Datagrid - renders data in a table with paging, sorting, and searching
  • Pillbox - manages selected items with color-coded text labels
  • Search - combines input and button for integrated search interaction
  • Spinner - provides convenient numeric input with increment and decrement buttons

The project is well-documented, covered in unit tests, and outside contributions are welcome and encouraged.

Contributed by Adam Alexander

uiji.js

uiji.js

uiji.js (GitHub: aakilfernandes / uiji) by Aakil Fernandes is a clever hack that inverts jQuery by allowing CSS selectors to create elements. This will create a paragraph with the class greeting, that contains the text Hello World!:

$('#helloWorld .output').uiji('p.greeting"Hello World!"')

Callbacks can be used to create hierarchy, and the API is chainable because the plugin returns $(this) once it has processed the input.

QuoJS

QuoJS (GitHub: soyjavi / QuoJS, License: MIT) by Javier Jiménez is a small library for mobile development. It supports HTML traversal and abstractions for touch-based gestures. It doesn’t require jQuery, but has a similar API:

// Subscribe to a tap event with a callback
$$('p').tap(function() {
  // Affects "span" children/grandchildren
  $$('span', this).style('color', 'red');
});

The same author has written a few other ambitious projects, including Monocle (GitHub: soyjavi / monocle, License: MIT), which is an MVC framework for CoffeeScript application development.

Worth Starring: Components

22 Oct 2012 | By Alex Young | Comments | Tags libraries client-side starred

Back in July, TJ Holowaychuk wrote a post entitled Components in which he outlined an approach to JavaScript project distribution. In the post he discusses CSS and the relationship with modernisation, asset bundling and packaging, require fragmentation and package distribution, and the potential move away from libraries like jQuery in the future.

An example of a calendar component.

Almost four months later I found myself wondering what TJ and his collaborators had done since then. I was surprised to find 123 public repositories in the component GitHub account. There are repositories with updates as recent as a day ago.

It’s impressive how many of the repositories are truly generic, given the number of them. For example, enumerable helps iterate over sets of objects – a very focused slice of Underscore’s functionality. Other repositories are reminiscent of popular jQuery plugins, and come bundled with cut-down CSS and structural markup, as promised by TJ’s post. The menu component is a good example of this.

There’s also a search-api repository for the component registry.

TJ attempted to formalise the structure of components in the Component Spec. The specification includes details on a JSON manifest file, project directory structure, and submission to the registry.

It would be entirely possible to use these repositories alongside jQuery-powered client-side apps. Quite a few will work well in Node. I haven’t seen many projects using these components yet, but lots of them are worth adding to your GitHub starred repositories.

Command-Query Separation in Practice

19 Oct 2012 | By Justin Naifeh | Comments | Tags software design command query separation

Let’s end the week by learning about a software design principle that is easy to follow, yet a violation of it can cause bugs and coincidental correctness.

Command-query Separation (CQS) is the principle by which a method is defined to perform a query, execute a command, but never both. A query returns information about the state of the system, which can include anything from primitive data to objects, or even complex aggregation results. A command, on the other hand, changes the state of the system, usually by writing (persisting) modified objects or data. If we are working with a domain to manage Person objects a query method to find a person by name could be PersonQuery.find(name), and a command to persist an instance could be Person.apply().

Normal Violations

While CQS is a sensible principle, it is violated in everyday practice. This is not as troublesome as it sounds, depending on the type of violation. Strict adherence to CQS makes some methods impossible such as query methods that count the number of invocations, thus allowing a developer to query the number of queries.

/**
 * Finds a user by name and increments the
 * query counter.
 * @return the found Person or null if one was not found
 */
PersonQuery.prototype.find = function(name) {
  this._queriesPerformed++;

  // get the Person from the datasource or null if not found
  var person = this.dataSource.find("Person", name);
  return person;
};

/**
 * @return the number of queries performed.
 */
PersonQuery.prototype.getQueriesPerformed = function() {
  return this._queriesPerformed;
};

We could create an incrementQueriesPerformed() method instead of incrementing the counter within find(), but that would be excessive and burden the calling code.

// now the developer must synchronize the state of PersonQuery. Yikes!
var person = personQuery.find("someuser");
personQuery.incrementQueryiesPerformed();

In practice, CQS is rarely taken in its pedantic form because doing so would make certain types of batched/transactional calls cumbersome. Also, multi-threaded and asynchronous tasks would be difficult to coordinate.

Two classic violations are the Stack.pop() and HashMap.remove() methods as was the case in the LinkedHashMap article (inspired by Java’s Map interface).

var map = new LinkedHashMap();
map.put('myNum', 5);

// ...

var val = map.remove('myNum');
alert(val); // prints "5"

The remove() method is both a command and query because it removes the value associated with the key (command) and returns the value, if any, that was associated with the key (query). While the violation is subtle, the same behavior could have been implemented with a remove():void method.

var map = new LinkedHashMap();
map.put('myNum', 5);

// ...

var val = map.get('myNum');
map.remove('myNum');
alert(val); // prints "5"

As with many instances, the code to avoid CQS violation is clunky and overkill.

Although there are often violations of CQS at the method scale, many libraries violate CQS as an integral approach to their API design by combining both getter and setter behavior within the same method.

var person = new Person("someuser");

// one possibility
person.enabled(true); // set enabled to true
var enabled = person.enabled(); // return true

// another possibility
person.value('enabled', true); // set enabled to true
var enabled = person.value('enabled'); // return true

I personally do not prefer this flavor of behavior overloading–instead recommending getEnabled() and setEnabled(Boolean)–but as long as the API is intuitive and documented then it’s generally not a problem.

Dangerous Violations

There are, however, instances where CQS violations cause side effects that can be difficult to debug. This usually happens when code tries to be too clever or helpful by merging command and query behavior.

Consider the following code to query and create a Person:

var person = personQuery.find("someuser");
if (person === null) {
  person = new Person("someuser");
  person.apply(); // persisted
  console.log("Created the Person ["+person+"]");
} else {
  console.log("Person ["+person+"] already exists.");
}

The code attempts to find a Person and create one if it does not exist; further calls to find() will correctly return the Person. The logic is trivial and easy to understand, but imagine that a developer decides to reduce the effort by changing find() to create a Person if a result is not found.

PersonQuery.prototype.find = function(name) {
  var person = this.dataSource.find("Person", name);

  if (person === null) {
    person = new Person(name);
    person.apply();
  }
  
  return person;
};

It can be argued that by combining both query and command behavior into find(), calling code can remove the if/else checks for null, thus making it simplier.

var person = personQuery.find("someuser");
console.log("Person ["+person+"] exists.");

The amount of code has been reduced, but we must consider other circumstances in which find() will be called.

As an example, when a user is creating a new Person via a standard HTML form, the system calls find() to ensure the name is not already taken. When find() was just a query method it could be called any number of times without affecting the system. But now it creates the Person it is attempting to find so a uniqueness constraint violation will occur.

// request one
var person = personQuery.find("newuser"); // returns newuser
if (person !== null) {
  alert("The name is already taken.");
}

// ... however, in a second request

// request two
var person = personQuery.find("newuser"); // Error (duplicate name)
if (person !== null) {
  // we can never reach this
  alert("The name is already taken.");
}

By adding command behavior to find(), the developer has accidentally broken the code. The original post-condition, the condition known to the code at the time, changed from returns null if no match was found to creates a Person and returns it if no match was found. Now the developer must spend time to refactor the original code, but maybe it’s legacy or outside of his or her control. Care must be taken when changing method conditions.

One solution is to name the method more aptly to describe its behavior: PersonQuery.findOrCreate(). Then the method find() could be added as a pure query alternative, and calling code can choose which one to invoke under the circumstances.

Another solution is to not change find() at all. It worked before, and it will work in the future.

Conclusion

Strict adherence to CQS is nearly impossible to achieve in normal application programming, although some special applications might require such an architecture.

What should be kept in mind is that a looser definition of CQS is valid and useful in practice. A method should stick to being a command or query, but if both behaviors are needed the method name should reflect its dual nature and a non-query/command alternative should be offered.

Totally Testacular

18 Oct 2012 | By Alex Young | Comments | Tags libraries testing node browser

Vojta Jina created Testacular (GitHub: vojtajina / testacular, License: MIT, npm: testacular) to write better tests for AngularJS, Google’s client-side library that’s rapidly gaining support from the wider web development community.

While established projects like Selenium are currently more complete than Testacular, the goal of bringing 100% of Angular’s tests to Testacular is an important milestone that should bring more attention to the project.

Testacular diagram

The design of Testacular itself is actually fairly lightweight. It uses a built-in Node-powered web server to send a test harness to a browser, and then Socket.IO is used for communication between the browser and client. A special page, /context.html, is used to contain tests, and a Node file watcher automatically runs tests when the associated test files change.

A configuration file is used to pull all of this together. It’s basically JavaScript, but uses special variables to set configuration options. For example, files is an array that holds a list of files to load in the browser, and reporters controls how test results are displayed.

Testacular automatically runs a browser instance when testacular start is invoked on the command-line. The entire workflow is optimised around development, so you shouldn’t have to leave your editor to see results. Also, a new instance of a browser is loaded – if you set up Chrome to run tests then your existing Chrome session won’t be interfered with.

Browsers are scripted through “launcher” files. The Chrome launcher includes command-line invocations suitable for Linux, Windows, and Mac OS. It’s also possible to use Internet Explorer and PhantomJS.

Testing cross-platform is also supported through custom launcher files. I found a custom browser example by digging through the project’s documentation. This is intended for invoking browsers through a virtual machine on a Continuous Integration (CI) server, but this could be adapted for local development. In fact, supporting Travis CI was one of Vojta’s initial goals for the project.

Trying Testacular

The Testacular readme has some details on how to get started writing Testacular tests. It’ll work with both Jasmine and Mocha. Let’s say you’re using Jasmine to test an existing project, and have added testacular to your package.json or installed it. All you need to do is run testacular init to create a configuration file, edit it with suitable values for your project, and then start up the Testacular server with testacular start.

Assuming you’ve created a Jasmine Testacular config file, change the files argument as follows:

files = [
  JASMINE,
  JASMINE_ADAPTER,
  'test/*.js'
];

And then add a test file to test/, anything will do:

describe('Array', function(){
  describe('#indexOf()', function(){
    it('should return -1 when the value is not present', function(){
      expect([1, 2, 3].indexOf(5)).toEqual(-1);
    });
  });
});

Now running testacular start will start up the tests. You should see something like the following screenshot – if not, check your basePath.

Testacular running on a Mac with Chrome

Conclusion

It’s good to see interesting spin-offs coming from MVC projects. Vojta has been working on Testacular for a while now, and it seems like his original plans are coming to fruition. If you’re frustrated with Selenium and work with Node, it might be a natural fit.

P.S. Writing this article without accidentally typing "testicular" was a formidable challenge.

Node Roundup: 0.8.12, Node CSV, Memoize

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

Node 0.8.12

Node 0.8.12 is out, which has some fixes for Windows, the Buffer and HTTP modules, and the REPL. I upgraded as soon as this release came out, and it’s running all of my stuff fine as far as I can tell.

Node CSV

Node CSV (GitHub: wdavidw / node-csv-parser, License: New BSD, npm: csv) by David Worms is a streaming CSV parser. By implementing stream readers and writers, this module can parse CSV with less memory overheads when compared to reading the entire file into memory.

It can be used with fs.createReadStream like this:

fs.createReadStream('./in')
  .pipe(csv())
  .pipe(fs.createWriteStream('./out'));

Alternatively, David has added a more convenient property-based API:

csv()
  .from.path('./in')
  .to.string(function(data) { console.log(data); });

To set options, from.options({ option: 'value' }) can be used. This supports the usual CSV parser settings, like field delimiters and quoting. The project has Mocha tests, and there’s a growing list of contributors.

Memoize

Memoize (License: MIT, npm: memoize) by Mariusz Nowak is a memoize module that implements pretty much everything related to memoization that I can think of. It works in both Node and browsers, works with function arguments without serialising arguments, supports asynchronous functions, and has cache management features.

The “primitive mode” is interesting because it’s optimised for large amounts of data. In fact, it made me think back to Map and WeakMap from Monday’s article on ES6 for Node. It seems like caching would get a boost from these ES6 features.