Using hogan.js with express on node.js

Thought i'd try getting twitter's hogan.js up and running with express... not as straight forward as i expected. Drawing upon this article on using mustache.js with express.js i created a simple adapter to help bridge functionality.

I would only use this while connect 3.x is in dev. After that i'd use TJ's consolidate.js cause i'm no TJ.

If you're looking for a full, working example, be sure to checkout a Nodestrap-- a repo i use as a project "prototype." It comes out of the box with better than average architecture, hogan-express templating, bootstrap 1.x. Its a good jumping off point.

Here's the adapter:

	var HoganExpressAdapter=(function(){
	var init=function(hogan) {
	var compile=function(source){
	return function(options) {
	return hogan.compile(source).render(options);
	};
	}
	return {compile:compile};
	};
	return {init:init};
	}());
	if(typeof module!== 'undefined' && module.exports){
	module.exports=HoganExpressAdapter;
	} else if (typeof exports!=='undefined') {
	exports.HoganExpressAdapter=HoganExpressAdapter;
	}

view raw hogan-express.js hosted with ❤ by GitHub

Here's an example of it in use:

	var express=require('express'),
	hogan=require('hogan.js'),
	adapter=require('./hogan-express.js'),
	app = express.createServer();
	app.configure(function(){
	app.use(express.static(__dirname + '/public'));
	app.use(express.logger());
	app.use(express.bodyParser());
	app.use(express.cookieParser());
	app.use(app.router);
	app.use(express.errorHandler({dumpExceptions:true,showStack:true}));
	app.set('view engine','hogan.js');
	app.set('view options',{layout:false});
	app.set('views',__dirname+ '/views');
	app.register('hogan.js',adapter.init(hogan));
	});
	app.get("/",function(req,res,next) {
	res.render("index",{name:"micah"});
	});
	app.listen(8080);

view raw hogan-express-app.js hosted with ❤ by GitHub

In the views directory i have a index.hogan.js file-- that's the template.

It's worked for simple uses so far. I'll update if needs be.

HTML5 Videos via ffmpeg

Script for making html5 videos in ubuntu linux. I used these directions to get ffmpeg set up correctly.

Run like . html5-vid.sh myfile.avi

	#!/bin/bash
	# html5 videos maker
	ffmpeg -i $1 -b 1500k -vcodec libx264 -g 30 -s 640x360 $1.mp4
	ffmpeg -i $1 -b 1500k -vcodec libvpx -acodec libvorbis -ab 55000 -f webm -g 30 -s 640x360 $1.webm
	ffmpeg -i $1 -b 1500k -vcodec libtheora -acodec libvorbis -ab 55000 -g 30 -s 640x360 $1.ogv

view raw html5-vid.sh hosted with ❤ by GitHub

A Very Quick Look at d3.js

I finally got a chance to dig into d3.js today. From what i can tell, d3.js is an amazing dom/svg animation framework. To be honest, i have no idea how to describe it. There very well is much, much more under the hood than i'm aware of.

The jQuery-like Parts

d3.js is a lot like jQuery insofar as many of the operations are based upon items selected with CSS-selector style syntax. For example, d3.selectAll('div') probably looks fairly intuitive to anyone who has written jQuery before-- it grabs all divs on the page.

Another jQuery-esque thing about d3.js is that its API is chainable, so the following code:

	//grab all divs on the page
	//and set their width to 300
	d3.selectAll('div')
	.attr("width",300)
	.attr("height",400);

view raw gistfile1.txt hosted with ❤ by GitHub

obviously sets the width of all divs to 300, height to 400

d3.selectAll('div').on('click',function(){alert('hi!');});-- i bet you can already tell how events in d3.js work--exactly like (post 1.7) jQuery.

d3.js data()

One of the things that makes d3.js initially difficult to understand is the .data() function. Here's a code snippet that does a little explaining.

	//select all divs
	d3.selectAll('div')
	//map some data to those divs, in order that they were found in the DOM
	.data(["hello","world","hi"])
	//and now do something to the divs with that data
	//perhaps, put the data in the divs
	//so this function param "d" is actually the data for that div
	.html(function(d) {
	return d;
	});

view raw gistfile1.txt hosted with ❤ by GitHub

So the above script maps (hmmmm...) the data to the items it gets passed in order. So "hello" would be the innerHtml of the first div, "world" would be the content of the second... makes sense. The data that you pass in can be strings, numbers, object literals, anything. (Hmmm I wonder what you could do with functions...?)

What if you had 2 divs on the page, and the data() array had 3 items in it? How would it map that? Well, it would map the first 2 to the first 2 divs, neglecting the other piece of data. There is a way to work with that extra piece of data though--.enter().

d3.js enter()

.enter() allows you to do something with left over data. Here's an example:

	//so there's two divs on the page for this to select
	d3.select('body')
	.selectAll('div')
	.data(["hello","there","world"])
	//this will map "hello" and "there" to the only two divs
	.html(function(d){return d;})
	//but theres 3 pieces of data...?
	//this is why d3 has the enter() function
	//think of it as "withTheLeftOverDataAfterMapping()" instead of "enter()"
	.enter()
	//so now we can do something with the leftover data,
	//how about create another div?
	.append('div')
	.html(function(d){return d;});

view raw d3-js-enter.js hosted with ❤ by GitHub

So we were able to add extra divs on with .enter() in order to represent all the data that we passed into it.

Full Bleed d3.js example

Example: Animating SVG Circles on Mouseover

The really interesting stuff i see with d3.js involves the transition() function and SVG, which is supported in Chrome, Firefox, IE9, iOs, and Android(Honeycomb). Here's a script i wrote that draws circles in the DOM which move as soon as you hover over them.

Intention-Revealing Interfaces

Amazingly well put:

If a developer must consider the implementation of a component in order to use it, the value of encapsulation is lost. If someone other than the original developer must infer the purpose of an object or operation based onits implementation, that new developer may infer a purpose that the operation or class fulfills only by chance. If that was not the intent, the code may work for the moment, but the conceptual basis of the design will have been corrupted, and the two developers will be working at cross-purposes.

Domain Driven Design by Eric Evans, page 246

Working with Selections and Ranges in CKEditor

Working with ranges and selections in CKEditor is almost unbearable. In order to make it a bit easier, i recommend using rangy, a free library that makes the html selection/range api cross-browser-proof. Well, at least it made what i was trying to accomplish cross-browser...

	/**
	* allows you to wrap or insert an html tag over a selection/range using rangy
	* @param iframe the CKEditor iframe html element
	* @param tagName string representation of the tag, such as 'a' for anchor
	* @param withNodeFunc function to allow outside modification of the element before injecting/wrapping
	*/
	function wrapOrInsert(iframe, tagName, withNodeFunc) {
	var iframedoc = iframe.contentDocument || iframe.contentWindow.document,
	tag = iframedoc.createElement(tagName),
	selection = rangy.getIframeSelection(iframe),
	selectionRange = selection.getRangeAt(0);
	//let the caller do something with the element
	withNodeFunc(tag);
	//since you can't wrap something with an image tag
	if (tagName === 'img') {
	selectionRange.collapse(false);
	selectionRange.insertNode(tag);
	} else if (tagName === "a" && selection.isCollapsed) {
	//provide some default text for an anchor
	selectionRange.collapse(false);
	tag.appendChild(iframedoc.createTextNode('link'));
	selectionRange.insertNode(tag);
	} else {
	selectionRange.surroundContents(tag);
	}
	//detach rangy
	selection.detach();
	}
	/**
	* Example on how to call the function, let's say on a jquery document.ready
	* It'll wrap the selection in a span
	*/
	$(function(){
	//first, lets get the iframe that the ckeditor is in
	var iframe=$(".ckeditor iframe");
	//we put the [0] on the end of the jquery item, since that will cast it to a DOM element (see http://stackoverflow.com/questions/6974582/jquery-object-and-dom-element)
	// and, we'll pass an empty callback, since we don't want to do anything with the span after its created
	wrapOrInsert(iframe[0],"span",function(){});
	});

view raw ckeditor-selection-wrap-with-rangy.js hosted with ❤ by GitHub

Inlining in .NET

I spent some time today debugging a huge, huge function. I remember one of the quotes a professor of mine told me about function length. It might of been about class length, actually.

"Never write a function longer than your screen."

I think its a good rule. There's something to be said for being able to sum up a piece of code just by looking at it. Did you know that .NET does the same thing behind the scenes? And that it has trouble with huge functions?

Enter Inlining

From what i understand, back in the C++ days, programmers used to be able to specify what functions would be embedded into the calling function. The advantage was one less function that the execution would have to call--because on execution of a function "some stuff happens" that i'm not going to go into here. The point i'm trying to make is that if you didn't call that function, you wouldn't have to do "that stuff." So, instead of putting that piece of reusable code in every place they wanted it to go, they kept DRY and marked it to be inlined--for the compiler to manually place it in every place it was called.

.NET Inlines for You

It's true. .NET will inline your code for you during JIT if it deems it a good place to do so. But here's the catch: if you're writing functions that are miles long, there's no chance whatsoever that .NET can inline it and you'll never get the performance benefits of letting .NET upgrade your code.

Keep It Simple

Write functions that do one thing, really well. Make them reusable, testable pieces, and short enough that even .NET can sum them up...

The Repository Pattern

I'm not sure if Martin Fowler conceptualized the repository pattern, but his book Patterns of Enterprise Application Architecture (PoEAA) is where I first came across the definition:

"Mediates between the domain and data mapping layers using a collection-like interface for accessing domain objects."

He has very carefully selected his words. I have my own definition. Consider it the layman's version:

"Separates data from its source." 

Let's dig into an example.

The Repository Pattern in .NET

Every .NET programmer has written some sort of code that accesses a database or web service and returns something. Traditionally, the ever-present n-tier/three-tier philosophy dictates that the code for that should be in its own package/layer, the data access layer. What that philosophy does not dictate is the method signature and the return type; they're extremely important. Let's look at your traditional DAL:

	public class PeopleDAL
	{
	public DataSet Person_GetAll()
	{
	//Returns a DataSet containing all people records in the database.
	}
	public DataSet Person_GetByPersonID(int personID)
	{
	// Queries the database for the particular user identified by
	// personID. If the user is located then the DataSet contains a
	// single record corresponding to the requested user. If the user
	// is not found then the DataSet does not contain any records.
	}
	public bool Person_Save(ref int personID, string fname, string lname, DateTime dob)
	{
	// Locates the record for the given personID. If the record exists,
	// the method updates the record. If the record does not exist, the
	// method adds the record and sets the personID variable equal to
	// the identity value assigned to the new record. Then the method
	// returns the value to the business layer because personID is
	// marked with the ref modifier.
	}
	public int Person_DeleteInactive()
	{
	//Deletes all inactive people in the database and returns a value
	//indicating how many records were deleted.
	}
	}

view raw classic-DAL.cs hosted with ❤ by GitHub

What will the dev on this project do if the People DB gets outsourced and is now accessed via webservice? Convert the web service return into datasets, or change all the business layer classes to work with whatever the new return is? Or, what if they change to a db that doesnt easily convert into datasets? Not a great position to be in... Why not change it to something more generic that will never change?...

Here's a look at the repository pattern implementation:

	public class PeopleRepository
	{
	public List<PersonDTO> Get()
	{
	//return a list of person data transfer objects here
	}
	public void Insert(PersonDTO person)
	{
	//insert a person here
	}
	public void Update(PersonDTO person)
	{
	//update a person here
	}
	public void Delete(PersonDTO person)
	{
	//guess
	}
	}

view raw PeopleRepository.cs hosted with ❤ by GitHub

Notice how this implementation could survive through any sort of data source change because it is using "a collection-like interface"? Much more maintainable.

The Repository Pattern in JavaScript

JavaScript's implementation would need to take into account the fact that AJAX requests (or all node.js functions) are meant to happen asynchronously. In order to allow for this, all we really need to do is implement the callback pattern, which really just boils down to passing an extra function.

	function PeopleRepository() {
	//when using constructor functions like this one to create objects in js,
	//always make sure you're doing so with the new keyword
	//or the scope will be off
	//
	//like so:
	if(!(this instanceof PeopleRepository) {
	return new PeopleRepository();
	//we just enforced new
	}
	//create a get function on the member
	this.Get=function(callback) {
	$.getJSON("some url",callback);
	};
	}
	//instance the repo like so (of course using new)
	var repo = new PeopleRepository();
	//call a get
	repo.Get(function(data) {
	//we could do something with the data that gets returned here
	});

view raw PeopleRepository.js hosted with ❤ by GitHub

That's it!