Docco Fork – All JS, all the time

EDIT: My fork is no longer needed. The folks at docco saw the same thing, and recently ported over the library to use highlight.js.

I love documentation generators for code. You know what I’ve talking about to – something which gives you a split screen of the code and the comments, side by side, for easy reading and scrolling. Like jasmine uses for their documentation:

Since I’ve mostly been working in JavaScript lately, I’ve been looking for something to help document the packages I create easily.

In comes docco. A CoffeeScript + Python library to help generate good-looking documentation from comments in your code.

However, one thing bothered my about this project – the python part. Docco uses a python library to highlight the syntax. There are plenty of decent syntax highlighters out there – why not use one written in a JavaScript flavor?

So I decided to fork docco and plugin a decent highlighter.

Pretty happy with the results. You can check out the fork here.


Esvalidate Library – Standalone Validation Library Using Esprima

I spent a good bit of time working on the Esvalidate code that comes with Esprima, trying to get it to work smoothly with my sublime plugin. After submitting a massive pull request to the author of Esprima, and our reviewing my code, we came to a conclusion – the new code was better served in its own library.

It’s still in its early stages, but please check out the progress I’m making here:

Esvalidate Library

Esprima Plugin for Sublime Text

In relation to my previous posts confessing my love for sublime, and my enjoyment of Esprima, here is some code that showcases both:

An Esprima plugin for Sublime Test!

This has been included in the official list of Sublime Plugins. So you can install this from Sublime using Packages Control.

Sublime Text – Esprima Plugin Screenshot

Added JavaScript syntax checking via Esprima and a Git pre-commit hook

I came across a brilliant project the other day – Esprima from Ariya Hidayat, the author of PhantomJS.

What is Esprima? Esprima is a JavaScript Parser written in JavaScript Syntax Validator. It forms the basis of several different tools – a minifier, a code coverage tool, a syntax validator – just to name a few.

I was immediately interested in the syntax validation tool. It’s not a linter – it just checks that the JavaScript written is syntactically correct. Why would you want this if you already have JsHint and JsLint?

  1. It is extremely fast. Validating three.js (800 KB source) takes less than a second on a modern machine.
  2. It looks only for syntax errors, it does not care about coding style at all.
  3. It handles generated files as the result of minification or compilation (CoffeeScript, Dart, TypeScript, etc).
  4. It tries to be tolerant and not give up immediately on the first error, especially for strict mode violations.

Esprima is available as an npm package, so installing it only takes a second:

sudo npm install -g esprima

Using Esprima from the command line is simple:

esvalidate file.js

The only thing to note about running from the command line: if the validation succeeds, you won’t get much in the way of confirmation. Which can be painful if you are processing a whole directory. You only get useful feedback in the default mode on error.

However, if you don’t mind reading a little XML:

esvalidate lib/*.js --format=junit

Prints junit XML which at least you can visually parse to see which files were validated.

Where would I use this where I might not use JsHint? As a pre-commit hook to screen my checkins. Instead of going through a check-in, building everything, then running JSHint just to hear that something is not up to spec, I can add a little script that will do a quick sanity check of my JS before I go to commit anything to git.

If you’ve never created a pre-commit hook before, it’s pretty easy. Two lines in bash will give you a pre-commit file:

touch .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

This is windows version of the code for the pre-commit hook:

files=$(git diff-index --name-only HEAD | grep -l '\.js$')
for file in $files; do
esvalidate $file
if [ $? -eq 1 ]; then
echo "Syntax error: $file"
exit 1

To make this work on Linux, just remove the remove the #!/bin/sh line.

For more information about Esprima, check out this article by the author.

Derby.js – The Ready() Function, and Adding Client-Side Scripts to your App

I’ve found a neat feature of derby dealing with the ready() function.

I’ve been creating a derby app, and in my application I need to load up a client-side calendar. With a standard HTML web page this is straightforward thing to do. On the page you wanted the calendar, you would include the client js for the calendar, some code to load it, and that would be that.

Derby introduced some complexity to this relatively simple task.

On my first attempt, I put my scripts in the section of the page that I needed the calendar on. I added a script to load the calendar as well. When I went to the url of the page, it loaded immediately. Success! (I thought).

Then I clicked a link away from my calendar, and then clicked back. No calendar.

What happened? When I loaded the link originally, the page was rendered from the server. The second time, the page was rendered client side. Something wasn’t working with loading the calendar on the client-side render.

You need a place to put your code that guarantees that it will load on the client-side. The app.ready() function is designed to handle this scenario.

What is the purpose of the app.ready() function? From the derby documentation:

Code that responds to user events and model events should be placed within the app.ready() callback. This provides the model object for the client and makes sure that the code is only executed on the client.

This function is called as soon as the Derby app is loaded on the client. Note that any code within this callback is only executed on the client and not on the server.

I’ve bolded the part I think is particularly important. This code is run as soon as the client is loaded. Which means if you have more than a single-page app, using app.ready() to load a feature might not work out.

So what to do? An undocumented feature of Derby – app.on().

What does it do? It allows you to load code AFTER a specific page has loaded. Which is exactly what I’m looking for.

So here’s what I ended up writing in my app.ready():

  app.on('render:calendar', function(ctx) {
    logger.log("rendering calendar client-side...");
    new Timeline("timeline", new Date());

In this example this code will run after rendering the calendar view. On the Calendar page, there is a script block which loads the Timeline function.

After writing this code, I tried my page again. Still no luck. I wasn’t getting the calendar to load on both the client and server load.

On a lark, I moved the block containing my Timeline javascript to my index view, and tried again. Success.

Which makes sense. If you are rendering pages via the client side load, additional resources aren’t going to be loaded. So by putting my script into the index view, it’s unfortunately loaded for all my pages, but at least it’s available for both the client and server side rendering of my cool control.

Setting up MongoDB to work with Derby.js

This post is going to cover installing and configuring MongoDB to use with Derby.

If you’re reading this post looking to add model persistence to your Derby application but don’t know much about MongoDB, understanding MongoDB will help you understand Derby and the model system it uses.

What’s MongoDB?

From their website:

MongoDB (from “humongous”) is a scalable, high-performance, open source NoSQL database.

If you’ve never used MongoDB before, you should immediately go here. This is the easiest, fastest way to learn the basics of what mongo is and how it works. And it only takes about fifteen minutes. It’s even interactive to keep you from getting bored. Go give it a play.

Derby and MongoDB

Now that you have an idea about how MongoDB works, many of the conventions Derby uses for models should make sense. If you scan through the Derby Query Readme now, hopefully is makes a bit more sense (like where the term “gte” came from).

Installing MongoDB

If you still need to install MongoDB go here for downloads and installation directions.

Configuring Derby to use MongoDB

Now that you know about MongoDB, let’s get MongoDB set up to work with Derby. This is straightforward and takes about two minutes.

To add MongoDB to your Derby application, you’ll need to include the racer-db-mongo package in your project.

Update your package.json file to look something like this:

  "name": "potluck",
  "description": "",
  "version": "0.0.1",
  "main": "./server.js",
  "dependencies": {
    "derby": "*",
    "derby-ui-boot": "*",
    "express": "3.0.0beta4",
    "gzippo": ">=0.1.7",
    "racer-db-mongo": "*" //this is the line. Glory in its beauty.
  "private": true

Then, at the command prompt, update your project (and download the recently added racer-db-mongo dependency) using the following command:

 npm update 

You’ll have to update your server configuration (by default in /lib/server/index.js) to use the new dependency. This requires TWO new lines of code

derby.use(require('racer-db-mongo')); // This line is new

  listen:  server
, db:      {type: 'Mongo', uri: 'mongodb://localhost/database'} /* This line is new */

That’s all the changes you need to make to add MongoDB to your project. So why I’d bother with a blog post?

What About Troubleshooting?

Now, if you go and start your Derby application, you might see the following error:

Error: failed to connect to [localhost:27017]

Which means:

  1. You’ve installed the racer-db-mongo dependency correctly!
  2. You now need to:
    • Install MongoDB
    • Turn on MongoDB
    • OR Fix MongoDB

If you’ve forgotten to install Mongo, if you look around, you’ll probably find a link somewhere which will help you out.

Starting/Stopping/Statusing MongoDB

If you’ve installed Mongo, you have to start the service before Derby can use it. On Ubuntu, you start Mongo using the following command:

 sudo start mongodb 

Remember to stop Mongo later with:

 sudo stop mongodb 

If you’ve started Mongo, then loaded your Derby application, and you’re still getting an error, it’s possible that Mongo did not start correctly. Typing:

 sudo status mongodb 

will let you know if Mongo is running or not. If you’ve run the Mongo Start command, yet the status command is telling you that Mongo is stopped, the most likely cause is Mongo did not shut down gracefully last time it was run. You’ll have to go and repair your installation (luckily, this is pretty easy).

Repairing MongoDB

To repair your installation, run the following commands:

$ sudo rm /var/lib/mongodb/mongod.lock
$ sudo -u mongodb mongod -f /etc/mongodb.conf --repair 

The code above was taken from this great article

At this point, you should have a working copy on MongoDB along with a working integration with Derby. Congrats!

MongoDB is working great – now Derby hates me

If your application loads, but you’re getting a strange error whenever you add to a collection that looks something like this:

Error: No persistence handler for 
push(FIRST_WORD.SECOND_WORD, [object Object], 18) 

It means that you are pushing to the wrong portion on an model path. You can only use push to arrays, and arrays are not objects, and you can only use objects for the first and second words of your model path. In the case shown above, a push is attempting to be made to


which equates to


which means SECOND_WORD is an array (which isn’t allowed).

If this last bit of explanation might have well been in Latin, check out this post. It’ll explain a little bit about how to declare models and what Derby is expecting you to do.

Unfortunately, you CAN use the second word of a model path as an array without persistence support. So this kind of bug will only surface once you’ve got MongoDB integrated with Derby.

Derby.js – Starting out with Components; Creating a Twitter Bootstrap Input Component

In working with Twitter Bootstrap Forms, one of my favorite ways to lay out a form is using the Horizontal form layout. The layout requires a bit of css/html to get each of the form elements (the text boxes and what not) to play nicely.

To add form elements to the horizontal form layout, you need the following html structure for each field:

<div class="control-group"><!-- additional classes here to change state -->
  <label class="control-label">INPUT_LABEL_TEXT_HERE</label>
  <div class="controls">
    <input type="text" /> <!-- This is the control you want to display -->
    <span class="help-inline">ERROR_OR_INFORMATIONAL_MESSAGE_HERE</span>

That’s a hefty amount of markup to copy and paste all over your pristine views. Which makes this a great place to use a Component.

So what’s a Component?

A component is basically a derby template you can supply parameters to. Those parameters are supplied in the form of HTML attributes and HTML content.

There are two types of components: application and library. Application components can only be used in a single project. Library components can be re-used across multiple projects.

For my project I’m going to create an application component. Eventually if I need the component on another project I’ll add it to a component library. But that process is more complicated and less documented so I’ll save that for another day.

There are two ways to create an application component:

  • Inline
  • If your component is only being used on a single view, you can add it to the same file as your view.

  • External
  • If your component is going to be used on multiple views, you should create a separate file for your component.

Apparently there are two ways to create a library component as well:

The ui directory contains a component library, which can be used to create custom components for the containing project. These are re-usable templates, scripts, and styles that can be used to create custom HTML tags for use in applications. General purpose component libraries can be created as separate npm modules.

All components run under the scope of the context in which they are called. Which means you can bind model data to your component without having to pass your component any values.

For example:

<h2>All toys:</h2>
  {each toys as :toy} <!-- Alias :toy available to the component -->
    <app:toyStatus> <!-- All application components live in the app namespace -->

<toyStatus:>  <!-- this tag says I am a component -->
  <!-- I'm using alias :toy here, defined above -->
  <span>The toy is located at {:toy.location}</span> 

If all of this “Model-Bindy” stuff is foreign to you, check out my post Working with Views, Models, and Bindings.

I don’t like the way you used a scoped alias from your view in your component. What if my component is in another file? What if I want to use a field with a different name? Is there a better way to pass values to a component?

From the derby documentation:

Literal values or variable values can be passed to components. These component attributes are available through “macro” template tags, which have triple curly braces.

What does that look like? Again, from the docs:

  <h1><app:greeting message="Hello"></h1>

  I was passed this message as an attribute: {{{message}}}

You can also pass html to your component as well. That is a two-part trick: First, write your component with an opening and closing tag. Put the value you want to pass to your component between the tags.

Then, in your component, you use the special triple-curly bracket {{{content}}} macro-tag to reference what you passed in.

For example:

    <b>Click me now!</b>

<fancyButton: nonvoid>
  <button class="fancy">

But I already knew all that. How do I make a component?

The easiest way is to just add the component to your page, as show in the simple example above. This example is taken from the derby website, and it shows you how to reference a component in a separate file:


(This is your component, which is located in your views folder.)

  <div class="profile">...</div>


(This is the view that will use your component.)

 <!-- This line imports your component into the view -->
<import: src="shared">

  Welcome to the home page
  <!-- include component from an imported namespace -->

The <import> tag at the top, used to include your component into your view, can be called with variety of parameters. For more information on the  <import>  tag go to

Didn’t you say something about Twitter Bootstrap?

Oh yeah. Got sidetracked there.

As you can see, creating a component is relatively easy. Since I already have all the Twitter Bootstrap markup ready, I might as well create a Twitter Bootstrap Component for Derby.

To do this, all you have to do is figure out what you want to be able to customize.


{{{#with data}}} 
  <div class="control-group {{cssClass}}">
    <label class="control-label">{{label}}</label>
    <div class="controls">
      <input type="{{type}}" value="{{value}}" />
      <span class="help-inline">{{message}}</span>

As you can see, I added bindings for {{cssClass}}, {{label}}, {{type}}, {{value}}, and {{message}}.

Why did I use a #with block to set the scope of my object being passed in? There is a bug in the derby code right now (documented here) where you can’t reference an object’s child properties with the triple curly brackets syntax. So {{{data}}} will work, but {{{data.value}}} won’t.

The object being bound to the component:

var data = function(value, label, type) {
	this.label = label;
	this.value = value;
	this.message = "";
	this.cssClass = "";
	this.type = type || "text";

And I call it in my view like this:

<app:boot:input data="{:person.firstName}">

Where firstName is an object like data described above.

So, in a just a little bit of markup and code, I have a great reusable component that I can use to style the look and feel of my application without having to copy and paste code everywhere.

I hope this it helps some of the fledging Derby developers out there.

BTW, code samples from this post can be found here.