In working with a client recently, we ran in to a rather sticky situation. We were setting up a route to “persons/:id”, and as you would expect, we wanted to load the person in question and display the details of that person. The trick, though, is that we needed to wait until the persons collection was loaded to be able to retrieve the person from the collection. If we navigate to this route from somewhere else in the application, this isn’t an issue. The persons collection was already loaded and everything goes on normally. If we use a bookmark to get to this url directly, though, then there was no guarantee that the persons collection was loaded because we had not previously run any code to load the collection.

Depending on how the application is architected, and when the persons collection is expected to be loaded, there are a few options that I can see for solving this problem.

Option: Fetch The Model From The Server

The most basic option, and probably the easiest to deal with, is just to fetch the model from the server based on the id parameter that you get from the route.

In this case you just need to create a new model instance, set the `id` attribute on the model directly and then call `.fetch` on the model. It will make the trip to the server to get the data. You can either listen to a “change” event on the model or provide a “success” callback in the fetch method, to know when the data has been returned so that you can load it in to your view and display it as needed.

personById: function(id){  var person = new Person();  person.id = id;  person.fetch({    success: function(model, response){      App.showPerson(model);    }  })}

view raw 1.js This Gist brought to you by GitHub.

The major problem here is that you have not loaded the persons collection at all. If the persons collection is expected to be loaded because it’s being used for something related to displaying or working with the individual person model, then this option might not work for you. You could run some additional code to load the collection separately (asynchronously, since it works that way by default). This might help get around any potential issues of needing the collection.

Option: Use The Collection’s “reset” Event

Another easy option may be to load the collection when the request for the route is made. You would set up a new collection instance, bind a callback function to the collection’s “reset” event, and then call `.fetch` on the collection. The callback method would be responsible for retrieving the specific model from the collection and then creating and displaying the view.

personById: function(id){  var persons = new PersonCollection();
  // note that "bind" is now "on" in Backbone v0.9.x  persons.on("reset", function(collection, response){    var person = collection.get(id);    App.showPerson(person);  });}

view raw 2.js This Gist brought to you by GitHub.

There are some potential issues with this solution, though. If you already have the persons collection loaded, then you’re going to load it a second time just to get the one model from it. To mitigate this problem, you would need two different entry points in to the display of the person: one for when you hit the route directly through a bookmark, and one for when the user is already in the app and navigates to the person display through other means.

Having two different entry points in to this part of the app may not be a bad idea. This largely depends on how the application is architected. You wouldn’t want to duplicate all of the code that sets up the display of the person’s details in both of the entry points, but you wouldn’t want to have a bunch of ugly if-statements in that code to determine how to set things up, either. Some simple abstractions of the common bits would help keep this code manageable.

Option: Building An “onReset” Callback

The third option that I can think of – and the one that I implemented for this particular client project – is a variation of using the collection’s reset event. The idea is to build an “onReset” callback system that is aware of whether or not the collection has already been loaded or is still waiting to be loaded.

If you have the persons collection being loaded from some other application initialization code, then you don’t necessarily have the ability to use a simple reset event as shown above. You could try to use the reset event, but there’s a race condition that is introduced in low-latency, high speed networks (i.e. your local development machine).

If you don’t control when the `.fetch` method is called, then you may end up binding to the reset event after the collection has already been reset. In that scenario – which is very likely to happen when working in a local development environment – your view for the specific person model will never get displayed.

The solution I came up with is to have a callback mechanism built in to the collection, that pays attention to the collection’s reset event and knows to either wait for the reset event to be fired, or to fire the callbacks immediately because the collection has already been loaded. I’m calling this an “onReset” callback, for lack of a better description at this point.

The code to use the onReset callbacks would look something like this:

// App.js// ------// some initialization code that happens elsewhere, using Backbone.Marionette
App.addInitializer(function(){  App.persons = new PersonCollection();  App.persons.fetch();});


// PersonRouter.js// ---------------// The router callback that needs to get the person
personById: function(id){  App.persons.onReset(function(collection){    var person = collection.get(id);    App.showPerson(person);  });}

view raw 3.js This Gist brought to you by GitHub.

In this setup, adding an onReset callback guarantees the callback’s execution. If the collection has not yet been loaded, then it stores the callback and waits for the reset event to fire. If the reset event has already been fired, then it simply executes the callback immediately. Either way, your callback will be executed and you will have the collection available when it does.

Race Condition Reduced. Eliminated?

Here’s the implementation for the onReset code. It’s generally functional and I haven’t yet run in to any problems, yet.

OnResetCollection = Backbone.Collection.extend({  constructor: function(){    var args = slice(arguments);    Backbone.Collection.prototype.constructor.apply(this, args);
    this.onResetCallbacks = [];    this.on("reset", this.collectionReset, this);  },
  onReset: function(callback){    this.onResetCallbacks.push(callback);    this.collectionLoaded && this.fireResetCallbacks();  },
  collectionReset: function(){    if (!this.collectionLoaded) {      this.collectionLoaded = true    }    this.fireResetCallbacks();  },
  fireResetCallbacks: function(){    var callback = this.onResetCallbacks.pop();    if (callback){      callback(this);      this.fireResetCallbacks();    }  }});

view raw 4.js This Gist brought to you by GitHub.

You can then extend from OnResetCollection instead of Backbone.Collection to get this functionality.

I still worry that there’s a potential race condition in between the logic and the pop’ing of items off the array. I’ve travelled every logical path of execution for the asynchronous call and onReset call that I can think of, and I can’t find any issue. I would love to hear from someone more experienced with race conditions in JavaScript, though.

Rails wants you to put specific files in specific folder structures, based on the object type that will be in the file. Java demands that files in a folder structure are namespaced by that folder structure. VisualStudio also makes it seem like file / folder names should be the namespace / class name as well – but that’s just a good suggestion and not a requirement. Other languages and frameworks have some requirements for how you organize your files, too… with the exception of browser based JavaScript (… mostly…)

JavaScript File Organization: You’re Doing It Right

The reality of JavaScript in general web-based development (not talking about server side at all, here) is that it makes absolutely no difference how your files and folders are organized. Zero difference at all… at least as far as the JavaScript runtime is concerned.

The only thing that matters is that you include your files in your HTML with a <script> block, correctly. You also need to pay attention to which order they are included in most cases, to make sure things are defined before they are used (tools like RequireJS and other script loaders and module definition / loaders help with this).

What does this really mean? It means:

You’re Doing It RIGHT!

Yup. You’re doing it right, because it doesn’t matter how you do it.

What does matter, though, is that you and your team (if you have a team) pick an organizational convention and stick with it. It’s actually very more important for your team to have a good file and folder structure for your JavaScript. But you don’t need to worry about what that structure is. Pick a standard and use it. When it fails (and it will), re-work your structure so that it works within the newly understood constrains and move on.

Of course, that fact that your browser and it’s JavaScript runtime don’t care about your file and folder organization doesn’t I’m without my opinions on how files and folders should be organized.

For example…

M, V and C Folders

A lot of people organize JavaScript MV* application files in a folder structure like this (BackboneJS in this case):

To the best of my knowledge, this folder structure is based on the “models”, “views” and “controllers” folder structure that was popularized by Ruby on Rails. Sure others may have had it first, but it was Rails that made it popular. Other MVC framework followed suit and demanded that you put your controller objects in the controllers folder, your model objects in your models folder, etc. But unless you’re Rails (or another framework that wants to be like Rails), this folder structure is stupid.

I’m pretty sure that Rails uses this folder structure to assume the types of objects that are found within the files. And I know for sure that it uses file names to assume the class that will be defined within the file. That is, when rails sees a file called “/app/controllers/foo_controller.rb”, it expects to find a class called “FooController” and it expects that this class will inherit from some Rails controller base class. If these expectations are not met, errors are thrown to say so.

I understand why Rails does it this way: file and folder based conventions make it easy to assume what a file will contain, and that makes it easy for the runtime to optimize for performance when pre-loading and caching the code contained within the files. This makes sense to me in Rails because the convention is based on good ideas for optimizing the way Rails works and the way it looks for files and how it loads them.

But, unless you’re Rails or another framework that wants to assume certain files in certain folder contain certain code, this is a terrible way to organize files.

The Junk Drawer

There are some good examples of other standards along this line. For example, I tend to follow the convention of a “public” folder with “css”, “images”, and “javascripts” folders. But honestly, this folder structure exhibits many of the same problems of being stupid that organizing files in M, V, and C folders does.

The real problem with these types of folder structures is that they become junk drawers. Even DHH and the Rails core team recognize that this is a poor folder structure outside the confines of Rails+Ruby code. That’s one of the reasons they added the Asset Pipeline in Rails 3.1. DHH even called the “javascripts” folder a junk drawer, very directly, in a RailsConf keynote in 2011 (or was it 2010?) – complete with a slide showing a drawer full of junk.

With any application that moves beyond a trivial number of files, these content-type, mime-type, code-type and general type-based folder structures turn in to a bloated pile of junk that is very difficult to sift through. Who wants to look at a folder with 20, 50 or 100 files in it, when you only really care about 2, 5 or 10 of those files?

And what happens when you suddenly have an object type that doesn’t fit your pre-established conventions? You end with a “lib” folder, like Rails, which becomes the ultimate junk drawer. “It’s not a model? It’s not a controller? It goes in lib.” – no matter what the actual functionality contained within the file is. The “lib” folder is asking to be a junk drawer… demanding it, really. So, do you follow that same junk drawer convention for non-M, V or C type-based files in your JavaScript apps? That doesn’t any make sense to me.

How I Organize Files: By Functionality

I prefer to organize my JavaScript files the way I used to organize my C# files in .NET projects: by functional area of the application. That is, I group files together in folders based on the area of the application that they facilitate.

For example, my BBCloneMail application has the following folder structure for it’s JavaScript:

Note that I’m still using the “javascripts” parent folder, but underneath of that I’m organizing by functional area of the application. In the root “javascripts” folder, are the primary application files – the ones that define the overall application bits. In the “mail” folder are all of the files that relate to the “mail” application. And, in the “contacts” folder are all of the files that relate to the “contacts” application.

I don’t care what “type” is contained in the file. That’s a completely irrelevant way to organize files to me. It makes no sense for me to organize files this way because many of my files contain more than one “type” of object. For example, I often put very simple model, collection and view definitions that are very closely related, in the same file.

Why Type-Based Folders Might Be A Good Idea

In spite of all my over-opinionated hand-waiving above, there are some good reasons to use type based folders in JavaScript. One reason is asynchronous file loading based on conventions.

You might have a JavaScript app that makes use of a templating engine (of which there are dozens, these days). It’s not always a good idea to pre-load every possible template in to the user’s browser, for download size and performance reasons. Sometimes it makes sense to fetch the template that you want the first time it’s requested.

To do this, it might make sense to use a convention to retrieve the files. I’ve seen several Backbone apps that use a jQuery selector to load files, as one example of this. When a Backbone view specifies a template as “#my-view-template”, the application’s template manager would make a request to the server to load something along the lines of “/templates/my-view-template.html”.

If you’re trying to organize your templates in a functional area of the application, you’ll have the added overhead of inserting the functional area folder name, such as “/mail/templates/inbox-template.html” for an “Inbox” view in a “mail” app, trying to load an “#inbox-template” jQuery selector as the template to render.

So… there’s at least one possible reason to use a type-based folder. I would still stick the type-based folder name under my functional area, though. I don’t want to mix up the templates between my functional areas of the application, by accident.

A Tradeoff: Folder Names vs File Names

Here’s one potential trade-off for using functional folder names vs type based folder names: you might have to specify the type in the file name. For example, if you have a model type name “Person”, a collection type named “Persons”, and a view to represent a single person or a collection of persons, what do you call that view? If you’re organizing things by type, you can call every “Person” and “Persons”

This can be very confusing. I was recently working with a client who was using an editor that only shows the file name for the open files, and none of the folder path for the files. He ended up with 4 “person.js” files in his open file list. Which one was the Person model, view, router, or controller file? We had to open each file to find the one we needed, every time. So, we took the hit on the file names. The “person.js” file contained the person model, while “persons.js” contained the collection, “personviews.js” contained the view definitions and “personrouter.js” contained the router. Thus, we’ve moved the need for specifying the object type from the folder structure (with all it’s bad ideas for using that) to the file name.

I’ve read at least one blog post that advocated using type-based folder names specifically to avoid the “ugliness” of having type names in your files. I seriously laughed out loud when I read that. Whether the type is in the file name or folder name is a moot point. You’re likely going to end up specifying the type somewhere. I would much rather have it in my file names because it’s easier for me to see things grouped together based on functionality, than based on the type of object contained in a file.

It’s Just An Opinion, And A Loose One At That

My own use of these conventions and ideas is rather loose at this point. I don’t stick strictly to anything, and I mix and match based on the project type, number of files and other constraints that a given project presents. Because, like I said at the top of this egregiously long post, you’re doing it right.

No matter what file and folder structure you pick for you JavaScript apps (assuming you’re using a suite of libraries that doesn’t force you in to a specific folder structure), you’re doing it right. JavaScript in a browser environment really doesn’t care what the file and folder structure is. But that doesn’t mean we as developers shouldn’t care. Pick a file and folder structure that fits the constraints of your application and change the structure as your app’s constraints change.

I had a rather large number of remote repositories set up in my Backbone.ModelBinding repository on my box, due to the wonderful community of contributors. But it was time for me to clean out the remotes as I no longer needed any of the old ones. To make it easy, I used a simple bash script:

git remote | while read a; do
> git remote rm $a
> done

This took care of removing every single remote that I had in my ‘git remote’ list … including the “origin” that I actually did want, now that I think about it. :P

But my bash-scripting-fu is terrible, so I couldn’t figure out how to not destroy all of them. I tried adding an if statement in there to check if it’s not “origin”, but couldn’t get it to work. Anyone got some better bash-chops than me, and can point out how to do this?

 

A few days ago I pushed some changes to the form validation up to my WatchMeCode website. I was trying to fix a scenario where a browser cache would have some of the data in the purchase form already filled in. In that scenario, a potential customer would have to modify each field, even though they were already filled in, in order for my  Backbone code to see the data in the field.

To “fix” the problem, I switched my code from a “change” event to a “keyup” event for the text boxes … bad idea!

Browser Auto-Fill

Most (if not all) browsers have an auto-fill feature, these days. I use it in Chrome a lot. It saves me a few seconds here and there and generally makes it easier for me to fill in the same repetitious information across websites.

But there’s a problem with auto-fill. It doesn’t fire the “keyup” event. It fires the “change” event for the things it fills in, but not “keyup”. This resulted in the data being truncated when it populated my Backbone model.

In the above screenshot, since i had typed “deri” in to the email address, the email that is stored in the Backbone model would only be “deri” – and that’s obviously not a valid email address.

Easy To Fix

There are a number of very easy ways to fix this.

• Validate the email address format
• Use a combination of “blur”, “change”, and “keyup” events
• Delay reading the data until the user clicks the “Purchase” button
• Use a KVO (key-value observer) plugin like my Backbone.ModelBinding and let it deal with that for you

For the quick-fix to get my site working properly, I went with the combination of “change” and “keyup” events. I’ll be re-writing my purchase form sometime soon, and will likely delay reading the values until they click the “Purchase” button. I’m also going to put in better email address validation to make sure it at least has an @ and a . in it, and I’ll likely use the HTML5 “email” field and see how that will help me, if at all.

Not So Easy To Automate Testing

When I originally made the change to use the “keyup” event, I did all my usual testing – which did not include using auto-fill. All of my testing passed, so I pushed the site live.

How do you test for bugs like this in an automated way? Is there even an automated way to test a browser’s auto-fill? I’d like to avoid mistakes like this in the future, and some automated testing around it would certainly be nice.

Lesson Learned: Don’t Rely Solely On “keyup”

There certainly are some great things you can do with the “keyup” event – like autocomplete, for one – but it’s not a great idea to only use this when there’s a chance that the browser’s auto-fill will be used.

And unfortunately for me, 2 of my customers ran in to this problem before I got it fixed. It makes it very hard to email someone the download instructions for their order. One of them contacted me and I corrected the order. But the other purchaser has not yet contacted me, and I don’t have enough information to figure out who they are, so I can’t track them down. I hope this person realizes that they didn’t get their order, they contact me. My contact info is all over the site… so … hopefully … the lessons learned for running an e-commerce site are sometimes painful.

 

In one of my current apps for a client, I have an activity based security system that determines what the user is allowed to do. The trick to this system is that all of the authorization checks happen on the server, but the functionality that is being secured runs on the client, in JavaScript.

This is a bit of a problem. If I send all of the JavaScript that is uses to run any part of the system to the browser, then it’s possible that a clever user could enable it and do things they aren’t supposed to do. Of course, when they send a request back to the server, the server will verify they can do what they requested and block it… but the user should not be able to even try to do things they aren’t authorized to do, in the first place.

The solution that I’ve come up with, at a very high “functional area of the application” level, is simply not to send JavaScript to the browser if the user is not allowed to use it. This keeps me from having to do extra security checks in the browser, keeps the download for the user smaller and generally makes the app appear snappier because there is less code to run. More importantly, though, it keeps the user from being able to try things they can’t do.

Modules To The Rescue

I’m facilitating this through the use of modules in my JavaScript – both “module” as in the JavaScript module pattern, and “module” as in a packaged functional area of an application.

It’s worth noting, though, that I’m not using AMD (asynchronous module definitions), RequireJS, or any other “module” framework for JavaScript. The debate about the “right way” to do modules can rage on all it wants. I’m content with simple immediate functions and logical groupings of files while the more intelligent and invested people in the JS community figure that all out.

Each of the functional areas of my application is built in it’s own set of files. Each area has multiple files that it is composed within, but the files are grouped together for easy identification of what makes up a module. I also have an HTML template for each module which provides the needed <script> tags to include the code for that module.

Only Render What Is Needed

When I need a functional area of my site to be sent down to the user, I tell my server side template language to include the correct HTML file. For example, I’m doing this in an ASP.NET MVC application:

@{var user = (CustomPrincipal)User;}
@if (user.Can("locations/manage")){    @Html.LocationManagementScripts()}
@if (user.Can("locations/search")){    @Html.LocationSearchScripts()}

view raw 1.cshtml This Gist brought to you by GitHub.

In this code, I’m checking to see if the current user is allowed to manage locations. If they are, the extension method “LocationManagementScripts” is called. This in turn renders the “LocationManagementScript.html” file at this point in my HTML layout. That file contains all of the <script> tags for the location management JavaScript app. In the same way, I’m checking to see if the user can search through locations, and running the same basic process if they can.

Self-Initializing Modules

When a functional module is included after passing one of these checks, it needs a way to get itself spun up and started so that it can do it’s magic. It may need to render something on to the screen. It may need to register itself with the application’s event aggregator, or any of a number of other things. This is where my Backbone.Marionette add-on comes in to play for my Backbone apps.

Marionette has an explicit concept of an “initializer” tied to it’s Application objects. When you create an instance of an Application object, you can call “app.addInitializer” and pass a callback function. The callback function represents everything that your module needs to do, to get itself up and running. All of these initializer functions – no matter how many you add – get fired when you call “app.start()”.

myApp = new Backbone.Marionette.Application();
myApp.addInitializer(function(options){  var myView = new MyView({    model: options.someModel  });  MyApp.mainRegion.show(myView);});
myApp.addInitializer(function(options){  new MyRouter();  new SomeOtherView().render();});
myApp.start();

view raw 2.js This Gist brought to you by GitHub.

Each functional area of my application has it’s own initializer function. When a functional area has been included in the rendered <script> tags, the initializer gets added and when the “start” method is called, the modules for that functional area are fired up and they do there thing.

A Composite App, And Sub-Apps

One of the tricks to making all of this work, is that I need to have a primary “app” object that all of my modules know about. In the above example, the “myApp” object is this. Each of the modules for each of the functional areas has direct knowledge of this object and can call public APIs on it – including the “addInitializer” method.

A better example of what a module definition and initializer might look like, would be this:

// --------------------// app.js
myApp = new Backbone.Marionette.Application();
myApp.addRegions({  mainRegion: "#main"});

// --------------------// locationSearch.js
(function(myApp, Backbone){  var SearchView = Backbone.View.extend({    // ...  });
  myApp.addRegions({    searchRegion: "#search"  });
  myApp.addInitializer(function(){    var view = new SearchView();    view.render();    myApp.searchRegion.show(view);  });})(myApp, Backbone);

// --------------------// index.html
<script language="javascript">  myApp.start();</script>

view raw 3.js This Gist brought to you by GitHub.

In this example, I’m using the simple JavaScript module pattern to encapsulate my search functionality. I’m also providing an initializer for the module that instantiates a search view and shows it to the user using a region manager.

Each of these functional areas is basically a sub-application. Many sub-applications are used to compose a larger application and overall experience for the user. The composition of a larger application through various modules that are included / excluded based on some criteria are what really make this a composite application.

I also included the final call to “myApp.start()”, showing that I do this from my main HTML page and not from my JavaScript files. This provides a single point of entry for all of the registered modules, no matter which modules are registered. The “myApp” object really doesn’t care which modules are registered, honestly. It doesn’t need to care. It only needs to execute the initializers that happen to be present. If none are present because the user didn’t have permission to do anything, then nothing happens when this method is called and the user won’t see anything.

Security: Don’t Let Them See It If They Can’t Do It

If the security check to see if the user is allowed to use the location search feature fails, the rendered HTML won’t include the <script> tags for the “locationSearch.js” file. If this file is not sent down to the browser, then it will never register itself. If a module has not registered itself for initialization, it’s views won’t show up on the screen and the user won’t be able to try and use the feature. Further, the user won’t be able to “view source” on the page and find any stray JavaScript that they shouldn’t be able to use.

It’s Not Always That Easy

Of course there are other security concerns that are not this simple. When a functional area is closed off by authorization, it’s easy to keep things clean like this. We can compose the application at run time simply by including the right files and letting the code in those files register themselves for initialization. But when we have a functional area of the system that has finer grained authorization and permissions associated with it, things get a little more tricky.

I’m still learning and exploring this space. I have some ideas and am going to be implementing some of them soon. If anyone out there has any experience in handling finer grained security needs in JavaScript apps, I’d love to hear about it. Post links to your favorite resources for this, in the comments.

 

I’ve asked for an explanation, definition, blog post, book, or any other source of material that can get me up to speed on REST in web development a number of times. It’s a popular subject these days, and there seems to be an abundance of knowledge and information out there.

Except that it’s all wrong. Every last bit of it.

… or, at least the handful of people who inevitably respond with comments like “no one does REST correctly” and “that’s not REST” would have me believe.

Your Doing It Wrong

Frankly, I’m tired of this pedantic, obnoxious response. The same people that continuously say “no one does it right” can’t seem to tell me why it’s wrong or point me to a resource that does do it right.

Here’s the deal. If everyone does it wrong, then write a blog post or a book or a screencast or something that tells the world how to do it right. Until you can point people to what REST actually is, stop telling everyone that no one does REST right.

My Journey Into Being Wrong

I have work to do. I’m obviously going to do it wrong, but frankly, I don’t care at this point. My system will work just fine, just like every other “That’s not REST” system out there.

To help me learn how to be wrong, though, here are a few resources that I’m going to be checking out:

Get Some REST: A work in progress book from Steve Klabnik. I signed up for the mailing list and am eagerly waiting. There’s rumor that Steve might actually be doing it right.

RESTFul Web Services – I bought the Kindle version last night. It’s the book DHH says everyone should read and a few others also suggested it.

REST In Practice – I’m probably going to buy this one, too. It seems to have the “30,000 foot view” that I’m also looking for, according to one reviewer on Amazon.

If anyone else has any resources for how I can learn non-REST, RESTful best practices, I’d love to know.

(end of rant)

 

… Updates

Thanks to everyone who is responding in the comments here and via twitter. I’m going to update this post with the resources that people are pointing me to, from Twitter.

The majority of my experience with anything REST-like comes from working with Ruby on Rails, and mimicking it’s handling of HTTP verbs with Sinatra application. I know this isn’t anything near correct, which is why I’m looking to find good resources.

I’ve been getting a lot of “you don’t need to do pure REST” responses – which I agree with. One of my problems, though, is that I’m having a hard time figuring out what “pure” REST is so that I can know the difference between that and what I’m actually doing.

Sebastian Lambla points out that it’s not the entire REST community that pulls this crap. There are plenty of people that are helping, providing good information and creating good resources to throw at people like me that are wanting to learn. My problem is not with the REST community as a whole, but with the people that behave in the way I’ve pointed out, here.

The most consistent advice I’m seeing so far, is to start with the books I’ve listed / purchases already. That will at least get me heading down a better direction.

Resources From The Twitterverse

http://www.amazon.com/RESTful-Web-Services-Cookbook-Scalability/dp/0596801688

http://code.google.com/p/implementing-rest/

http://www.amazon.com/REST-Design-Rulebook-Mark-Masse/dp/1449310508

The #rest channel on http://freenode.net/ IRC

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

http://roy.gbiv.com/untangled/2008/rest-apis-must-be-hypertext-driven

http://amundsen.com

http://www.infoq.com/search.action?queryString=stefan+tilkov+rest&searchOrder=relevance&search=stefan+tilkov+rest

Just for fun I decided to put together a quick sample of some functional JavaScript – as in, functional programming done with JavaScript. I’m not really very familiar with functional languages other than playing with Haskell a bit and doing some functional-style stuff in C# and Ruby. I wanted to see what a functional JavaScript code base might look like.

A Functional Calculator

To keep things simple, I created a calculator using nothing but functions. Each function takes other functions as parameters and returns a function. The only exception to this is the simple `value` function which takes a value and returns a function that itself will return the original value.

Here’s the basic code I wrote for my calculator, including the aforementioned `value` function:

// A raw value, represented as a functionvar value = function(val){  return function(){    return val;  }}
// A function to add two functions togethervar add = function(x, y){  return function(){   return x() + y();  }}
// A function to subtract one function from anothervar subtract = function(x, y){  return function(){    return x() - y();  }}
// A function to multiply two functionsvar multiply = function(x, y){  return function(){    return x() * y();  }}

view raw funcalc.js This Gist brought to you by GitHub.

I wrote all this through the use of some Jasmine tests, but as a quick example of how it can work, here’s a simple formula and result:

var one = value(1);var two = value(2);var three = value(3);var four = value(4);
// (1 + 2) * 3 - 4 == 5var resultFunc = subtract(multiply(add(one, two), three), four);
// but it's still a function right now, so evaluate itvar result = resultFunc();consol.log(result); // => 5

view raw sample.js This Gist brought to you by GitHub. My Thoughts And Reactions

These are the interesting points that stand out in my head. I’m not sure if these are “correct” or not… it’s just what pops out in my mind.

If anyone has any corrections and additional thoughts or notes, I’d love to hear them – just drop me a line in the comments, below.

Functions And Functions As State

I’ve represented everything as a function – even the simple values of 1 through 4. And every function returns a function, except for the simple values, which return a function that returns the actual value.

In the process of returning functions from functions, I’m representing the state of the application as a series of functions.

This one is a bit odd for me to wrap my head around. I’m not sure if this is really correct, or if it’s just an oversimplification of what’s really happening here. There are no data-structures, though, only functions. So it stands to reason that the state is stored as a series of functions that can be evaluated to produce a result.

Update: The Wikipedia article on functional programming says that fp “avoids state”. So… am I wrong in thinking that I’ve represented the state with functions instead of data structures?

Funcional Command Pattern

The result isn’t actually evaluated until I invoke the`resultFunc` in the above example. But I have the `resultFunc`available as a variable and I can pass it around anywhere I want. This basically turns it into a command pattern implementation, only in a functional manner instead of an object manner.

Compose-able And DSL Functions

All of these functions are side effect free. None of them actually mutates any existing application state. Of course this is a really simple implementation, but that was one of my goals. I’ll need to play with some more complex ideas in order to really see how side effect free would play out.

One of the benefits of side effect free functions is that the code in the sample is far more declarative and compose-able than most code I write. Since each function does one very small and very simple thing, taking in other functions as parameters, it’s easy to build things.

var one = value(1);var two = value(2);var three = value(3);var four = value(4);
// (1 + 2) * 3 - 4 == 5var added = add(one, two)var multiplied = multiply(added, three)var resultFunc = subtract(multiplied, four);
// the result is the same. // it's been composed the same, functionally// it was just put together with more variables in the mixvar result = resultFunc();consol.log(result); // => 5

view raw compose.js This Gist brought to you by GitHub.

This is something that I’ve played with in other languages, and I like this aspect of functional programming. It’s a great way to build DSLs for example.

Compared To Object / Prototypal

Oscar Godson posted a version of my code alongside a prototypal version for a comparison.

/** Prototypal from Oscar Godson: http://jsbin.com/atopek/edit#javascript*/
var Calc = function(){  this.sum = 0; //could be a param  return this;}
Calc.prototype.add = function(x){  this.sum = this.sum + x;  return this;}
Calc.prototype.multiply = function(x){  this.sum = this.sum * x  return this;}  Calc.prototype.subtract = function(x){  this.sum = this.sum - x;  return this}
Calc.prototype.result = function(){  return this.sum;}
console.log(new Calc().add(1).add(2).multiply(3).subtract(4).result())

view raw prototypal.js This Gist brought to you by GitHub.

I like seeing them side by side. It’s interesting the see all of the different ways that JavaScript can do the same thing. It also shows me just how ugly I think the functional version is. When you compare the actual formula in the comments to the functional JS code, the code is inside-out-backwards. The prototypal code with it’s method chaining is closer to the formula, though it’s still a bit off.

I think it’s easier to read and understand the chaining, though. It also reminds me of LINQ and monads – pipes and filters with a single result coming from the end of it.

More Fun Functional Stuff To Try

I haven’t done anything like memoizing or currying for these simple examples, but those are ideas I want to play with, too. I’ve written a currying function in JavaScript once or twice, and there’s plenty of examples in the good JS books. Memoizing is also available in Underscore.js but should be trivial to implement a naive version of it. I’m sure there are plenty of other things that would be fun to try, as well.

Code And Continuing Thoughts (Maybe)

If you’re interested in seeing this code, it’s on Github.

I’m thinking about taking this a little further over time, just for fun. I’ve posted these comments in the read me (actually – they started there…) and I’ll continue to update the read me as I progress (assuming I actually do continue exploring this and don’t just forget about it like so many other things).

This is really pretty simple stuff… but it’s fun to write asimple exercise like this and think about what’s going on, why and see how it affects the way I think and approach software development.

My wife wanted to see my WatchMeCode website so she could post it on her Pinterest (which is a site I don’t understand… but that’s beyond the point).

IE Hates HTML5

She pulled it up on her work laptop, which was equipped with… IE8! … and it looked like this:

Of course that’s not at all what I expected the site to look like. I expected it to look more like this:

This site is one of the first I’ve built using the modern HTML5 tags like <header>, <section>, <article>, and <footer>. I know IE doesn’t like tags that it doesn’t recognize and IE8 or below certainly don’t recognize HTML5 tags.

Modernizr To The Rescue!

The answer is simple, fortunately. Grab a build of Modernizr and drop it in to your site… only, I already had it in my site. So why was it still looking all broken and stupid?

It turns out I had the Modernizr script at the very bottom of the HTML <body> tag – one of the tricks for performance optimization of loading scripts. However, including Modernizr at this point means that IE won’t recognize the new HTML5 tags until after the page has already loaded, thus the broken site design.

Push the Modernizr script up to the top of the <head> and everything works. Of course, I’m using some CSS3 so it’s not perfect, but it’s certainly nice in comparison to the broken version:

Now the interesting bit is that I don’t really need IE support in my website. I only get 3.6% of my traffic from IE users – I really don’t expect people that are interested in the guts of JavaScript to be IE users after all. But with a fix as simple as this, it’s not a big deal to go ahead and add minimal support just to keep the site

Use Modernizr… At The Top Of Your HTML

The morale of the story: use Modernizr. It’s just that easy. Of course it does a lot more than just include an HTML5 shim for older browsers, too. There’s a ton of great stuff in it. But in my case, that’s all I really needed it for.

And when you do use it, be sure to include it in the <head> of your HTML so that it applies before the rest of your page loads.

This started out a comment in a Google+ stream, which is in response to the brujahahahahalols that have been going around concerning ActiveRecord, FubuMVC and Rails. I’m not defending any of these posts or perspectives. I have my own opinions on the problems and benefits of the various things mentioned… but I wanted to specifically talk about something that Chad mentions: bloated object interfaces, or too many methods on an object.

It seems to me that claims of object bloat and Separation of Concerns (SoC) / Single Responsibility Principle (SRP) violations for languages like Ruby are often based on the idea of interface-based method dispatch… the idea that an object must implement an interface in order to have the method available. Now I’m not saying that all claims of these violations are from this perspective, by any means. I don’t know if this was Chad’s perspective or not. I can only assume based on how he worded things. And obviously there are some horrible chunks of code out there, in any language, with any type system or method dispatch system, that really do violate these principles.

Still… I wonder how much of the bloat or perception of bloat is based on the wrong perspective…

SoC/SRP: 354 Methods On An Object!

ActiveRecord might truly be a horrible beast with far too many concerns in one given place. I haven’t dug into that source code very much. From what I remember of it, it’s huge and difficult for me to understand (but then, it does a metric-ton-squared of meta-programming, so I guess I’m not surprised that it’s hard for me to understand).

I have dug deep in to Mongoid, though (a MongoDB ODM for ruby), which sits on top of various pieces of ActiveRecord. I’ve submitted a handful of patches for Mongoid and have spent a fair amount of time studying it to learn how it works. On the surface, it also looks like a ton of bloat and SoC/SRP violations. Run “puts my_model.methods.sort”, and you’ll see 354 methods… it makes you wonder…

1.9.2p290 :001 > require 'rubygems'1.9.2p290 :002 > require 'mongoid'
1.9.2p290 :003 > class Foo1.9.2p290 :004?>   include Mongoid::Document1.9.2p290 :005?> end
1.9.2p290 :006 > f = Foo.new1.9.2p290 :007 > f.methods.count => 354 
1.9.2p290 :008 > f.methods.sort => [:!, :!=, :!~, :<=>, :==, :===, :=~, :[], :[]=, :__id__, :__send__, :_accessible_attributes, :_accessible_attributes=, :_accessible_attributes?, :_active_authorizer, :_active_authorizer=, :_active_authorizer?, :_children, :_collection, :_collection=, :_create_callbacks, :_create_callbacks=, :_create_callbacks?, :_destroy_callbacks, :_destroy_callbacks=, :_destroy_callbacks?, :_id, :_id=, :_id?, :_id_change, :_id_changed?, :_id_was, :_id_will_change!, :_index, :_index=, :_initialize_callbacks, :_initialize_callbacks=, :_initialize_callbacks?, :_parent, :_parent=, :_protected_attributes, :_protected_attributes=, :_protected_attributes?, :_root, :_save_callbacks, :_save_callbacks=, :_save_callbacks?, :_type, :_type=, :_type?, :_type_change, :_type_changed?, :_type_was, :_type_will_change!, :_update_callbacks, :_update_callbacks=, :_update_callbacks?, :_updates, :_vacant?, :_validate_callbacks, :_validate_callbacks=, :_validate_callbacks?, :_validation_callbacks, :_validation_callbacks=, :_validation_callbacks?, :_validators, :_validators=, :_validators?, :`, :acts_like?, :add_atomic_pull, :add_to_set, :apply_defaults, :as_document, :as_json, :assign_attributes, :associations, :atomic_delete_modifier, :atomic_insert_modifier, :atomic_path, :atomic_position, :atomic_pulls, :atomic_pushes, :atomic_selector, :atomic_sets, :atomic_unsets, :atomic_updates, :attribute_method?, :attribute_method_matchers, :attribute_method_matchers?, :attribute_present?, :attributes, :attributes=, :becomes, :begin_validate, :bit, :blank?, :breakpoint, :build, :cached, :cached=, :cached?, :capture, :cascade!, :cascades, :cascades=, :cascades?, :changed, :changed?, :changed_attributes, :changes, :class, :class_eval, :clone, :collection, :collection_name, :collection_name=, :create_relation, :cyclic, :cyclic=, :cyclic?, :db, :debugger, :default_scoping, :default_scoping=, :default_scoping?, :defaults, :define_singleton_method, :delayed_atomic_pulls, :delayed_atomic_sets, :delete, :deleted?, :destroy, :destroyed=, :destroyed?, :display, :do_or_do_not, :dup, :duplicable?, :embedded=, :embedded?, :embedded_many?, :embedded_one?, :enable_warnings, :enum_for, :eql?, :equal?, :errors, :exit_validate, :extend, :fields, :flagged_for_destroy=, :flagged_for_destroy?, :freeze, :from_json, :from_xml, :frozen?, :has_attribute?, :hash, :hereditary?, :html_safe?, :id, :id=, :identifier, :identify, :in?, :inc, :include_root_in_json, :include_root_in_json=, :include_root_in_json?, :index_options, :index_options=, :initialize_clone, :initialize_copy, :initialize_dup, :insert, :inspect, :instance_eval, :instance_exec, :instance_of?, :instance_values, :instance_variable_defined?, :instance_variable_get, :instance_variable_names, :instance_variable_set, :instance_variables, :invalid?, :is_a?, :ivar, :key_formatter, :key_formatter=, :kind_of?, :mass_assignment_authorizer, :matches?, :metadata, :metadata=, :method, :method_missing, :methods, :model_name, :move_changes, :nested_attributes, :nested_attributes=, :nested_attributes?, :new?, :new_record, :new_record=, :new_record?, :nil?, :object_id, :parentize, :pending_attribute?, :pending_nested, :pending_relations, :persisted?, :polymorphic, :polymorphic=, :polymorphic?, :pop, :presence, :present?, :previous_changes, :primary_key, :primary_key=, :private_methods, :process, :process_attribute, :process_nested, :process_pending, :process_relations, :protected_methods, :psych_to_yaml, :psych_y, :public_method, :public_methods, :public_send, :pull, :pull_all, :push, :push_all, :pushable?, :quietly, :raw_attributes, :read_attribute, :read_attribute_for_validation, :referenced_many?, :referenced_one?, :reflect_on_all_associations, :reflect_on_association, :relation_exists?, :relations, :relations=, :relations?, :reload, :reload_relations, :remove, :remove_attribute, :remove_change, :remove_child, :remove_inverse_keys, :remove_ivar, :rename, :require_library_or_gem, :require_library_or_gem_with_deprecation, :require_library_or_gem_without_deprecation, :reset__id!, :reset__type!, :reset_persisted_children, :respond_to?, :respond_to_missing?, :respond_to_without_attributes?, :run_callbacks, :run_validations!, :safely, :sanitize_for_mass_assignment, :save, :save!, :scopes, :scopes=, :scopes?, :send, :serializable_hash, :set, :set_relation, :settable?, :setters, :shard_key_fields, :shard_key_fields=, :shard_key_selector, :silence, :silence_stderr, :silence_stream, :silence_warnings, :singleton_class, :singleton_methods, :substitutable, :suppress, :syncable?, :synced, :synced?, :taint, :tainted?, :tap, :timeless, :timestamping?, :to_a, :to_enum, :to_json, :to_key, :to_model, :to_param, :to_query, :to_s, :to_xml, :to_yaml, :to_yaml_properties, :trust, :try, :typed_value_for, :unsafely, :unset, :untaint, :untrust, :untrusted?, :update, :update_attribute, :update_attributes, :update_attributes!, :update_inverse_keys, :updateable?, :upsert, :using_object_ids, :using_object_ids=, :using_object_ids?, :valid?, :validated?, :validates_acceptance_of, :validates_confirmation_of, :validates_exclusion_of, :validates_format_of, :validates_inclusion_of, :validates_length_of, :validates_numericality_of, :validates_presence_of, :validates_size_of, :validates_with, :validation_context, :validation_context=, :with_options, :with_warnings, :write_attribute, :write_attributes, :y, :you_must]

view raw mongoid.sh This Gist brought to you by GitHub.

But when I look at the source for Mongoid, it’s one of the most beautiful sets of code that i’ve seen in Ruby. From my perspective, it has a very clean separation of concerns and follows many other good OO principles to the core (at least until it has to interact w/ activerecord).

The interface bloat that we see on an object like the one above comes as a result of a few different things: Ruby base objects, and applying the many different Mongoid mixins to a Ruby model, via `include Mongoid::Document`.

Perspective: Interface-based vs Message-based

The problem might not be ActiveRecord, or Mongoid, or any other “bloated framework that violates …” and how the objects that use these frameworks look when we list the interface of a model. The problem might really be that we are listing the interface to the model as if it were the truth of this object’s implementation. The problem might just be our perspective.

Does the object above really implement all of these methods? Or has it been composed from many different mixins, with many different hats to wear in different scenarios (Udi Dahan’s “role specific interfaces”, or dependency inversion in general)?

Watch Where You’re Pointing That Perspective!

If we look at a message-based method dispatch in the same light and perspective as we do a interface-based dispatch, things look bad. If we look at the message-based, first-class-mixin system as a series of responsibilities, though, with each responsibility having it’s own protocol definition and each responsibility and protocol captured into an object that can be composed into a larger piece (again, mixins), things look much better.

Yes, my “Foo” object in the above example still has 354 methods on it. But how many of these do you really care about for a given scenario? What role do you expect this object to play, when? Ruby, Rails, ActiveRecord, Mongoid… Python, JavaScript, and the rest of the dynamic ecosystem give us a lot of power and flexbility. (Insert abused “Uncle Ben” quote from Spiderman… with great power come blah blah blah blah…)

I received an email from someone who was looking through my BBCloneMail and Backbone.Marionette source code. One of the comments they made talked about how my router callback methods were nothing more than pass-throughs, calling out to another object. (I think this is one of the points that Tim Branyen was making in the comments of my previous post, too).

Here’s an example of the code that the email was referring to:

  MyRouter = Backbone.Router.extend({    routes: {      "": "mail",      "inbox": "mail",      "inbox/categories/:category": "mailCategory",      "inbox/:id": "mailMessage"    },
    mail: function(){      BBCloneMail.MailApp.show();    },
    mailCategory: function(category){      BBCloneMail.MailApp.showCategory(category);    },
    mailMessage: function(messageId){      BBCloneMail.MailApp.showMessage(messageId);    }  });

view raw 1.js This Gist brought to you by GitHub.

The emailer suggested that I factor out the boilerplate code and set up some custom functionality to go straight from the route definition to a method call on another object, In other words, instead of having to implement a callback method on the router itself, having the callback method be on another object.

Removing The Callback Functions

I like the idea so I hacked together a working version directly in to the BBCloneMail application. The result is that my router went from the code above, to this:

  MyRouter = BBCloneMail.AppRouter.extend({    routes: {      "": "showInbox",      "inbox": "showInbox",      "inbox/categories/:category": "showCategory",      "inbox/:id": "showMessage"    }  });

view raw 2.js This Gist brought to you by GitHub.

Now my router is nothing more than configuration! There are no callback methods directly in the router anymore. The callbacks that I defined are located on another object, instead.

To make this work, my “AppRouter” expects to receive an “app” object when it’s instantiated. This is the object that contains the callback methods I specified.

new MyRouter({  app: BBCloneMail.MailApp});

view raw 3.js This Gist brought to you by GitHub.

All of the parameters that you define in the route are forwarded to your app object’s callback method. So, when the empty (“”) route fires, the “showInbox” method on the “BBCloneMail.MailApp” object will be called with no parameters. And when “inbox/:id” fires, the “showMessage” method on “BBCloneMail.MailApp” will receive a single parameter with the id from the route.

The AppRouter Code

Here’s the code that I put in to my AppRouter, to make this work:

  Routing.AppRouter = Backbone.Router.extend({
    constructor: function(options){      Backbone.Router.prototype.constructor.call(this, options);
      if (this.appRoutes){        this.processAppRoutes(options.app, this.appRoutes);      }    },
    processAppRoutes: function(app, appRoutes){      var method, methodName;      var route, routesLength;      var routes = [];      var router = this;
      for(route in appRoutes){        routes.unshift([route, appRoutes[route]]);      }
      routesLength = routes.length;      for (var i = 0; i < routesLength; i++){
        route = routes[i][0];        methodName = routes[i][1];        method = app[methodName];        router.route(route, methodName, method);
      }    }
  });

view raw 4.js This Gist brought to you by GitHub.

This code doesn’t preclude you from using the standard “routes” and callbacks, either. You can mix and match the standard routes and the appRoutes however you want. The routes defined in appRoutes get processed after the standard routes, though. This means it’s possible for an appRoute to override a normal route.

Still Needs Work

You can see it live in my BBCloneMail app right now. It may not stay there for long, though, as I’m constantly changing that code. Also – I haven’t thoroughly tested this so there may be some browser compatibility issues that I haven’t run into yet… or some other issues that I don’t know about. I’m going to keep playing with this idea and once I get it to something I really like, I’ll re-write it (test-first of course) into Backbone.Marionette.

I’m also looking for feedback on this. I realize there are some limitations to this, and there are probably some dumb thing I’ve done, too. If anyone has any suggestions for how to improve this, I’d love to hear it.

In my last post on Backbone, I offered my opinion on why I don’t look at Backbone as an MVC framework. I left off with a statement about forgetting the MV* family for a moment, and focusing on what’s really important: how the pieces of Backbone fit together to help us create better JavaScript application. What this really comes down is responsibility. What are each of the pieces of Backbone really responsible for?

Backbone.History

The primary responsibility of the History object is managing the browser’s navigation history, which facilitates the forward and back buttons and more.

This is one of the little-known pieces of Backbone as it sits behind the scenes 99% of the time. Typically, the only time you see it come in to play is when you have a Router and you call the history object to kick off the browser’s history manipulation:

Backbone.history.start();

view raw history.js This Gist brought to you by GitHub.

In truth, the History object does most of the work that you think a Router does. It facilitates the browser’s forward and back buttons by manipulating the browser’s history. It updates the URL’s route (either hash fragment or pushState) and it monitors changes in the URL’s route. It basically does everything that needs to be done with history, so that we can define and use one or more Routers in our application.

Backbone.Router And Routes

A router’s primary responsibility is to organize the route definitions and callback methods into logical groupings (typically based on related objects or related functionality). In reality, the Router organizes an app’s code for doing this but actually making the update to the route and paying attention to the route happen through the History object. Hence, the Router is used to organize our code and facilitate history manipulation and response, but not to directly manipulate or manage history.

A Router has a few secondary responsibilities, as well: 1) tokenizing the application’s state in to the browser’s URL, and 2) rehydrating an application based on a token found in the browser’s URL.

On a related not: A route is the tokenized representation of our application’s state.

Tokenizing State:

As our application progresses, it moves through various states. Some of those states can be represented by simple tokens. For example, viewing an email in GMail can be represented with a token like this:

This token is a bookmark-able state that the application transitioned into. When I hit refresh on my browser window, GMail will display the same email message to me that I saw when I clicked on the mail item originally.

When our Backbone applications reach various states, such as viewing an email, we use a router to update the browser’s URL. We do that through `router.navigate`:

myRouter.navigate("some/route");

view raw navigate.js This Gist brought to you by GitHub. Rehydrating From A Tokenized State:

A router responds to changes in the route and calls the least amount of code possible to put our application in to the state we need. We do this through the use of the router’s callback methods (or events):

MyRouter = Backbone.Router.extend({  routes: {    "some/route": "someMethod"  },
  someMethod: function(){    // do stuff here  }});

view raw router.js This Gist brought to you by GitHub.

But the router is not in control the application, the application’s state, or anything else. It does not control the views or models. A router simply takes the route and figures out which part of the application to call.

Think about a Rails or ASP.NET MVC router. Would you have the router in either of those generate some HTML and send it back to the browser? Not a chance! You would use a controller and view for that. In the same way, we shouldn’t use a backbone router to “control” our application. Rather, we should let the router figure out which route callback needs to be fired, and from there we should call some part of our application that can be in control of the application state.

Sometimes a route callback is a 1-liner that calls out to another objects. Sometimes it is 2 or 3 lines to find an item by id and then call out to another part of our app to get things running. But a router should never instantiate a view and manipulate the DOM directly with jQuery or placing the view in to the DOM. That’s the responsibility of the application and it’s state, and a route callback is only one possible entry point into the application’s state.

Backbone.Model And Backbone.Collection

Models and collections have one primary responsibility: maintaining application state. They do this by remaining in memory, with all of their associated data remaining in tact, until we change that data or de-reference the object allowing it to be cleaned up. They also do this by managing persistence with a back-end server, when needed.

In-Memory State

A stateful object is one that lives in memory with a set of specified data, even after we’re done calling methods on it. A backbone model and collection are typically stateful objects because we hold references to them in our app. This keeps them in memory and allows us to read and change the state of the object. Changing the state of an object may change the state of the overall application.

myModel.set({someAttr: "some value"});
// ... later in the code ...
alert(myModel.get("someAttr")); // => alerts "some value"

view raw memorystate.js This Gist brought to you by GitHub. Persistent State

When the state changes, it sticks around in that state until we explicitly change it again. But the state of a model or collection in Backbone can be rather volatile. If a user leaves our application, closes their browser or hits the refresh button on the browser, the state of our application may be lost. If we need to maintain the application state between sessions of our app, we have to persist the state somewhere. We do this by calling various persistence methods on our models and collections:

// save changes to the model, back to a servermyModel.save();
// get all of the models for this collection, from a servermyCollection.fetch();

view raw persistence.js This Gist brought to you by GitHub. Backbone.Sync

Backbone.Sync is responsible for the network communications of the persistence operations found in models and collections. It does this by delegating to jQuery’s $.ajax method, and by default will communicate using JSON data over a RESTful API on a server.

You typically don’t touch or notice Backbone.Sync because it’s hidden behind the model and collection APIs for persistence. When Backbone’s persistence mechanisms don’t fit your needs, though, Backbone.Sync is where you want to change things to match what your back-end server requires. There are many different implementations of Backbone.Sync, including some for non-RESTful server, for use with Socket.io, and much much more.

Backbone.View

The primary responsibility of a view is to coordinate interactions between the end user and the application’s services.

The interactions between the user and the application’s services are facilitated through many different means, including the use of jQuery or Zepto.js to handle DOM level events, calling in to models and collections directly through the user of `this.model` and `this.collection` respectively, and generating new HTML that will be displayed to the end-user in response to changes in the application state.

MyView = Backbone.View.extend({  events: {    "click #someElement": "someMethod"  },
  someMethod: function(){    alert("you clicked it!");  },
  render: function(){    $(this.el).html("<button id='someElement' value='click me'></button>");  }});

view raw view.js This Gist brought to you by GitHub.

In spite of their importance and having their fingers in all the pies of Backbone, views are not in control. They respond to changes in the application state in order to render the right HTML at the right time. They also facilitate changing the state by calling other objects that can change the state, but only on behalf of the user who initiates a state change by interacting with the DOM. Views are effectively the middle-man of a Backbone app.

Of course views can be used in some very simple scenarios where they respond to, manipulate, and maintain the state of an application. But this should only be done when you’re using a Backbone view to help organize some jQuery code without building a full Backbone application.

Backbone.Events

The primary responsibility of Backbone.Events is to decouple the knowledge of state changes from the response to those state changes, through the use of the observer pattern.

Backbone.Events is the little powerhouse that facilitates nearly every aspect of a Backbone application. This is the one piece of Backbone that is found in every other piece of Backbone. Every time you call “bind” or “trigger” on any Backbone object, you’re using Backbone.Events.

Events let us decouple the various pieces of our app while still providing a unified way for all of those pieces to communicate. Aside from being used in every other piece of Backbone, we can also use Backbone.Events in our own objects. One of my personal favorite ways to do this is through the use of an event aggregator to decouple and facilitate communication between higher level application concerns.

var vent = _.extend({}, Backbone.Events);
vent.bind("foo", function(){  alert("bar");});

// ... later in the codevent.trigger("foo"); // => alerts "bar"

view raw vent.js This Gist brought to you by GitHub. Your Code

Understanding what each of these pieces is responsible for will help guide our decisions in how we use them. Can I put this jQuery selector and DOM manipulation directly in my model? Sure, I can. Should I? Heh – no. A clear separation between DOM manipulation and data manipulation is important. Separating the other concerns of the application are equally as important, of course.

Here’s the kicker, though. You’ll notice that none of what I’ve talked about in any of these responsibilities includes workflow, large scale structure, managing dependencies or any of a number of other subjects. There’s a lot that Backbone gives us, and it’s a great tool set to own. But beyond a specific set of tools that should be used to facilitate a specific set of responsibilities in our applications, you still need to know how to write good JavaScript. And you still need to write your own code to handle the rest of your applications’ needs.

I got tired of manually typing “git push origin master” and “git push heroku master” to push changes in my BBCloneMail app up to Github and then deploy to Heroku. So I automated that with a rake task.

Then I got tired of the same 10 commands to generated new Docco docs for BBCloneMail and push that up to my Github `gh-pages`… so I automated that with a rake task, too.

The end result is 23 lines of rake tasks (including spaces and task definitions) to automate the updating of my project’s Docco documentation, push repository commits up to Github and then deploy to Heroku:

desc "Deploy site and docs to github and heroku"task :deploy => [:push_github, :push_heroku, :docco]
task :docco do  `docco public/javascripts/bbclonemail*.js`  `git add -A`  `git stash`  `git checkout gh-pages`  `rm -rdf docs`  `git add -A`  `git stash pop`  `git commit -am 'updating docs'`  `git push origin gh-pages`  `git checkout master`end
task :push_github do  `git push origin master`end
task :push_heroku do  `git push heroku master`end

view raw rakefile.rb This Gist brought to you by GitHub.

The only complexity in this is the process to update the Doco docs for the project. These commands ensure that the docs are built from the branch I’m currently on (which is always `master` for this project), but are only committed to the `gh-pages` branch, for the Github “Pages” feature. It also pushes the changes up to Github for me.

Now I just run `rake deploy` from the command line and everything is done for me. File this under “that was easy”.

I’ve seen this question / statement / argument more than a few dozen times. I don’t particularly care whether or not people try to understand Backbone in terms of MVC frameworks, because that’s how we learn. We adapt new ideas based on existing knowledge experience, before we fully understand the new idea. However, I do care that people continue to say Backbone is an MVC framework, because it confuses people when they don’t see a “Controller” and see things like “Routers/Views are sort of a controller“.

I’m not going to “set the record straight” or try to offer the definitive answer on this, though. I’m not a core contributor to Backbone. I didn’t build it and I don’t have any say in how it’s truly architected and designed. So, none of what I say is official. I am going to offer my opinion, though. I feel my years of experience in working with MV* family applications at least gives me enough knowledge to do that… which, honestly, is only going to muddy the waters more because I seem to be in the minority on this opinion.

There Are No Controllers In Backbone

There simply aren’t. In spite of the documentation saying that routers or view may be sort of maybe almost kind of close to some of what a controller might do, there are no controllers. It’s not a construct that exists in the backbone namespace, and there’s no implementation that represents what a controller does, architecturally.

A router is not a controller. It’s a router. A view is not a controller. It’s a view. Yes, both routers and controllers share some of what a traditional MVC framework would call a controller. No, neither of these is a controller.

More MVP Than MVC

I’ve spent 5+ years building MV* family applications in thick-client / GUI systems (Windows / WinForms / WinMobile) and on the web (Rails, ASP.NET, ASP.NET MVC, etc). Backbone clearly fits in to this family, but it’s also clearly not MVC. My opinion says that it’s closer to MVP, where the backbone view is closer to a P (presenter) and the HTML/DOM is the V (view).

Consider this picture of an MVC process flow (from Wikipedia):

Here, the models contain data which is used to populate views. Actions that a user initiates are handled by the controller which processes the request and updates the models. The models are then fed back to the views and the cycle starts over. It’s cyclical in nature.

And now consider this picture of an MVP process flow (from LessThanDot.com):

Notice the difference? Right – it’s not circular. That’s the big difference between MVC and plain-jane MVP (a.k.a. “passive view“). MVP does not work in a circular fashion the way MVC does. Instead, it relies on a presenter (the “P” in MVP) to be the coordinating brains of the operation. The presenter in an MVP app is responsible for taking the data from the models and stuffing it in to the views. Then when an action is taken on the view, the presenter intercepts it and coordinates the work with the other services, resulting in changes to models. The presenter then takes those model changes and pushes them back out to the view, and the elevator of moving data up and down the architectural stack begins again.

Does the idea and responsibility of a presenter sound familiar when thinking about Backbone? It should… it fits almost concept for concept with Backbone’s views, in my mind. But that doesn’t mean Backbone is an MVP implementation, either. It only means that views should be thought of as presenters, not controllers.

Neither MVP, Nor MVC, Nor MVVM, Nor …

Ultimately, trying to cram Backbone in to a pattern language that doesn’t fit is a bad idea. We end up in useless arguments and overblown, wordy blog posts like this one, because no one can seem to agree on which cookie-cutter pattern name something fits in to.

Backbone, in my opinion, is not MVC. It’s also not MVP, nor is it MVVM (like Knockout.js) or any other specific, well-known name. It takes bits and pieces from different flavors of the MV* family and it creates a very flexible library of tools that we can use to create amazing websites.

So, I say we toss MVC/MVP/MVVM out the window and just call it part of the MV* family. Or better yet, let’s just call it “The Backbone Way” and forget about trying to fit some cookie cutter mold around a fluid and flexible library.Then we can focus on what Backbone actually provides and how these pieces should work together to create our apps.

Although I’ve mentioned it in this blog already, and have been tweeting about it, we’ll call this the official announcement for my new Backbone.Marionette library.

Backbone.Marionette: Make your BackboneJS apps dance with a composite application structure!

Why?

Over the last … however many months I’ve been using Backbone, I’ve developed a number of opinions around building apps. I have a particular style of code that I write, with a particular set of functionality that is common through most of (if not all of) my apps. Backbone.Marionette is another of the many plugins I’ve created, that encapsulates my opinions.

To date, i have the following libraries for Backbone, with more ideas in my head based on the work I’m currently doing:

• Backbone.ModelBinding
• Backbone.Memento
• Backbone.Marionette

My goal with these plugins is not to say “this is how you must work with Backbone”. Rather, I want to provide options and opinions for those that are running into the same problems that I’ve run into. When I find myself solving the same problem over and over again, I find myself wanting to extract the solution into a library. This lets me get on with my real application development instead of focusing on solving the same problem again.

The trick with my plugins, is to provide a set of libraries that all work independently, but can be combined in very creative ways to create some even more amazing. Even within each library, I’m trying to take an approach that allows you to use only the parts that you want. Of the three plugins I’ve written, I think ModelBinding is the most restrictive / hand-holding. Memento and Marionette both offer a great deal of freedom and flexibility vs the configurability of ModelBinding.

What?

Marionette is a library of tools that you can use when you want to, without being forced to use every single piece of it. These tools include:

• Application initialization
• View management
• Event aggregation

Though the number of pieces is currently small, each of these pieces is very flexible and can be used without requiring any other piece. They can also be integrated into existing applications as-needed, allowing you to migrate an app from your existing code to Marionette.

How: Application Initialization

This was the big piece for me in building Marionette. I noticed that at some point that my BackboneJS applications tend to gather a cruft of procedural mess in an “application object”. This application object has always been responsible for starting up the various bits of the app: routers, initial views, instantiating collections and initial models, etc.

The problem is that these objects have usually ended up in a giant tangled mess with far too many concerns. For example, here’s some code from an image gallery that I wrote a few months ago. Note that this is only the application startup code:

ImageGallery.App = function(initialImages){  var vent = _.extend({}, Backbone.Events);
  var images = new ImageGallery.Images(initialImages, {    vent: vent  });
  var mainView = new ImageGallery.MainView();
  var controller = new ImageGallery.Controller(images, mainView, vent);
  var router = new ImageGallery.Router({    images: images,    mainView: mainView,    controller: controller  });
  var showImage = function(image){    controller.showImage(image);    router.navigate("/image/" + image.id);  }
  vent.bind("image:selected", showImage, this);  vent.bind("image:edit:cancelled", showImage, this);  vent.bind("image:edit:saved", showImage, this);  vent.bind("image:deleted", function(){    controller.home();  });
  vent.bind("image:add", function(){    controller.addImage();    router.navigate("/add");  });
  vent.bind("image:next", images.next, images);  vent.bind("image:previous", images.previous, images);
  vent.bind("image:edit", function(image){    controller.editImage(image);    router.navigate("/edit/" + image.id);  });
  this.initialize = function(){    var imageListView = new ImageGallery.ImageListView({      collection: images    });    $("#image-list").html(imageListView.render().el);
    new ImageGallery.MenuView({      vent: vent    });
    Backbone.history.start();  }}

view raw gallery.js This Gist brought to you by GitHub.

It’s a giant mess and it’s difficult to understand and maintain.

The solution involved recognizing that I was putting far too many concerns into a single place, combined with a healthy dose of encapsulation. I want each functional area of my application to have it’s own start up code, encapsulated within that functional area’s code. I don’t want to have to mash all the functional areas together into one procedural mess. So, I build the `Backbone.Marionette.Application` object.

This object provides a number of different features, one of which is the ability to register application initialization callbacks. To do this, you need to create an instance of an Application object, first. Then call the `addInitializer` method and provide a callback function. The initialization functions are then kicked off when you call the `start` method on your application:

// create your application instanceMyApp = new Backbone.Marionette.Application();
MyApp.addInitializer(function(){  // do stuff here, to kick off your application});
MyApp.addInitializer(function(){  // more start up stuff here});
// run all of the initializers!MyApp.start();

view raw initializer.js This Gist brought to you by GitHub.

You can optionally pass an object through the start method, as well. This object is made available to all of the initializer callbacks as a single parameter to the callback function. Additionally, there’s a “initialize:before” and “initialize:after” event that the application object raises, using Backbone’s Event functionality.

The trick is to keep your code organized and put your initializers next to the code that they initialize. Don’t just cram all of your initializers into a single file, recreating the same mess from my image gallery. Put your initializers near the code that they initialize. Keep them separate, keep it clean and decoupled. Add as many initializers as you need. Just remember that you have no guarantee of the order in which they run.

For more info on the application object, see the documentation.

How: Event Aggregation

The `Application` object comes with an event aggregator built into it. You can call the `.vent` property of any Application instance and have full access to the Backbone Event system. I won’t go into any more detail about this right now, as you can read up on the basics of how I use event aggregators in my previous blog post.

Of course you can still build your own event aggregator with one line of code.

var vent = _.extend({}, Backbone.Events);

view raw vent.js This Gist brought to you by GitHub.

In fact, this is all I’m doing in the Application object. I just put it there as a convenience so I don’t have to create one manually for every app:

How: View Management

In one of my recent blog posts on composite JS apps I talked about the use of a region manager, and the code that I wrote in that post has been migrated into Backbone.Marionette as the `RegionManager` object.

The intent and purpose of a RegionManager is the same as I’ve previously talked about. The difference in Marionette is how you access a RegionManager. You have two options: use the `addRegions` method on your Application instance, or manually create a RegionManager object. The choice gives you flexibility, allowing you to use a RegionManager without using the rest of Marionette, if you want to.

The `addRegions` method on the Application object accepts a single parameter of a JavaScript object literal. The keys for this object become the names of the regions, and the value of each key should be a jQuery selector that points to the HTML DOM element that your region manager will manage:

MyApp.addRegions({  navigationRegion: "#navigation",  mainRegion: "#main-content"});

view raw region.js This Gist brought to you by GitHub.

You can also pass a RegionManager definition as a value. See the documentation for more info on this.

Once the application is started, each of the keys that specified will be available on the application object instance. You can then call the `show` method on your region managers to show your Backbone views in that region.

Documentation And Source Code

I’ve linked to the documentation several times, which is found on the Github repository that houses the code:

http://github.com/derickbailey/backbone.marionette

I also have the annotated documentation that I’ve previously talked about, available at:

http://derickbailey.github.com/backbone.marionette/docs/backbone.marionette.html

BBCloneMail: A Reference Application

In addition to the source code and documentation, I’m building a sample application that can be used as a reference for building Backbone applications with Backbone.Marionette. The name “BBCloneMail” comes from the idea of a “Backbone clone of GMail” to demonstrate a composite application. Though it’s styling is different than Gmail’s, you can clearly see the influence in the layout, the use of categories (labels) and the drop list to switch between the mail and contacts apps.

You can find BBCloneMail online at:

http://bbclonemail.heroku.com

The source code is here:

http://github.com/derickbailey/bbclonemail

And the annotated source as documentation is here:

http://derickbailey.github.com/bbclonemail/docs/bbclonemail.html

But Wait! There’s More!

This is the first official release of Backbone.Marionette: v0.1.0… I expect the functionality to continue to grow and evolve as I use it in more application, and as (hopefully) I see other people using it and contributing their own needs to the code.

In my last post on composite JS apps, I mentioned needing a search and search results section of my app. I’m starting off with a very simple search box that will let a user enter a name or description of an item, and the back-end server will return a JSON result set that I display on the screen. Since Backbone can encapsulate all of the server communication for me, I wanted to take advantage of this and set up a Backbone.Collection to do the search.

Fetch And Url

Calling the `fetch` method on a collection will cause the collection to make a call back to the server to retrieve the requested collection. The collection that is returned is determined by the `url` attribute of the collection. This attribute can either be a string or a function.

If you’re dealing with a model and a RESTful back-end, it’s often easy enough to set the collection’s url to a string, such as “/images”. This would load all of the images from the server, as a JSON document, and populate the collection.

If you’re doing something more complex and you need to figure out the url at runtime, though, you can set the `url` attribute to a function. My search process requires me to pass urls that look like this: “/items/{search-term}”, where {search-term} is the actual search term typed in to the search box. To get the url formatted like this, I need to append the search term to a base url string when the `url` function is called. Unfortunately, there’s no way to pass parameters to the `url` function. To make this work, then, I rely on my collection to hold the bits of search info that I need and then I have my `url` function read them:

SearchResults = Backbone.Collection.extend({  url: function(){    return "/items/" + this.searchTerm;  }});

view raw url.js This Gist brought to you by GitHub.

With this function in place, I can create an instance of my collection, set the .searchTerm on it and then call .fetch:

var results = new SearchResults();results.searchTerm = "some search term";results.fetch({  success: someView.showTheResults});

view raw manualcall.js This Gist brought to you by GitHub.

However, I’m not very happy with having to remember to do things like this whenever I want to do a search. I would rather have a simple “search” method that I can call, which handles all of these details for me.

Encapsulating Search

To encapsulate the search process, including the creation of a collection, setting the .searchTerm and then calling .fetch, I want to create a function that hangs directly off of the SearchResults collection. This way I can simply call `SearchResults.search(…)` and get a result set back. To do this, I need to use the 2nd parameter of the Backbone.Collection.extend method. This parameter is an object literal, just like the first parameter. But, unlike the first parameter, it adds the functionality you specify directly to the collection’s constructor function, and not to an instance of the collection.

SearchResults = Backbone.Collection.extend({  url: function(){    return "/items/" + this.searchTerm;  }}, {  search: function(searchTerm){    var results = new SearchResults();    results.searchTerm = "some search term";    results.fetch({      success: function(){        MyApp.vent.trigger("search:results", results);      },      error: function(collection, response){        MyApp.vent.trigger("search:error", response);      }    });   }});

view raw searchresults.js This Gist brought to you by GitHub.

Here you can see my SearchResults object with the `url` function in the collection instance, and the `search` function in the collection definition. I’ve also added a call to my event aggregator to notify my application when the search results have returned or have produced an error.

Performing The Search

Now I can call my search and subscribe to the event that tells me when they have returned, so I can display them:

// handle the search results in a viewBackbone.View.extend({  initialize: function(){    MyApp.vent.bind("search:results", this.showResults, this);  },
  showResults: function(results){    this.collection = results;    this.render();  },    render: function(){    var html = $("#some-template").tmpl(this.collection.toJSON());    $(this.el).html(html);  }});
// do the actual search, based on a search// term that was entered in to the search boxSearchResults.search("some search term");

view raw search.js This Gist brought to you by GitHub.

Of course, I’m sure there are many other ways of accomplishing the same thing with a Backbone.Collection. This is the solution that I’m currently using, but I would love to see the solutions that you’ve come up with for searches. Drop a comment here and let me know how you’re doing it!

With the first bits of my Backbone.Marionette plugin being available on Github now, I wanted to try out the Backbone-style of annotated source code as documentation. I like the way Backbone has this set up, and I often refer to it when I want to know how something works internally, or find a specific piece of code to copy.

You can find the annotated code for Backbone.Marionette here.

Note that this only part of the documentation solution for a project, though. If you expect to annotate your source code and call your documentation done, you’re a scumbag oss coder:

That being said… commenting your code is a great way to provide additional documentation. It will help people understand the code they are reading, and help them write better code using your library or framework.

Docco

To generate the annotated document for Backbone.Marionette, I used Jeremy Ashkenas’ “Docco” tool – the same one he uses to generate Backbone’s annotated source code. The great thing about this project site: it’s build using the Docco tool. :)

There are a number of different ports for this tool available, so you can run it in NodeJS, Ruby, Python, .NET and more. I decided to use the NodeJS version that Jeremy built, mostly because I’m always looking for an excuse to use NodeJS tools. The process of getting this up and running was surprisingly simple, though it did involve a few steps and a bit of guess work on my part. Hopefully this blog post will help others get around the guess work.

The Source Code

If you read through the source code for Backbone.Marionette, you’ll find a bunch of standard // comments throughout the code. This is pretty normal stuff, for the most part. I’ve added some comments above my objects and methods, to help explain what they are and how to call them.

The only significant difference between a normal command and a Docco ready comment is that some of the comments have a //————— line underneath of them. This tells Docco that this is going to be a section header, in the compiled documentation. Using a fixed with font, set the number of – in that comment line to the same width as your header title:

// This Is A Header// ----------------

// This is a normal comment, that will become part of the// annotations after running through the Docco tool. Use this// space to describe the function or other code just below // this comment. For example: //// The `DoSomething` method does something! It doesn't take any// parameters... it just does something.
function DoSomething(){  // and by the way, this will show up  // in the docco file, too. :)  alert("I'm doing something!");}

view raw comments.js This Gist brought to you by GitHub.

Other than that, comment your code as you normally would. You can also do some cool tricks like using `bacticks` around code, and the generated document will encompass that inside of a <code> tag, with CSS set accordingly. There’s likely some other tricks you can do, too, as this is all run through a Markdown processor to build the docs.

Side note: if you haven’t learned Markdown yet, do yourself a favor and learn it. It’s becoming the ubiquitous documentation and code commenting style around the development community. I think this is largely due to Github supporting it and encouraging it’s use in readme files and Github wiki pages. I’m at the point where I take notes in Markdown, when attending technical sessions or taking notes from conversations.

Docco Prerequisites

There are a few things you’ll need to install if you want to use the NodeJS version of Docco:

• NodeJS
• NPM (Node Package Manager)
• CoffeeScript
• Python
• Pygments

If you’re on a Windows machine, you can find installation instructions for NodeJS, NPM and Python around the web fairly easily. Here’s the instructions for OSX:

NodeJS (via Homebrew):

sudo brew install node

view raw nodejs.sh This Gist brought to you by GitHub.

NPM:

sudo curl http://npmjs.org/install.sh | sh

view raw npm.sh This Gist brought to you by GitHub.

CoffeeScript:

sudo npm install -g coffee-script

view raw coffeescript.sh This Gist brought to you by GitHub.

Python:

May be included in OSX… might be part of XCode. I’m on OSX Lion and I have the latest XCode. I didn’t need to install anything for Python to be available to me. Python is needed for the “easy_install” tool, which is Python’s package manager (similar to NPM or RubyGems).

Pygments:

sudo easy_install pygments
sudo npm install -g pygments

view raw pygments.sh This Gist brought to you by GitHub.

I’m not actually sure if you need to install the NPM pygments… I did, and things worked well for me. I’m assuming this is needed so NodeJS can run the Pygments tool.

Installing Docco

Once you have all the prerequisites in place, installing Docco is a one liner:

sudo npm install -g docco

view raw docco.sh This Gist brought to you by GitHub.

Now you have access to the `docco` command line tool.

Running Docco On Your Code

This is super easy. Just run `docco {file pattern}` from the command line. For example, the above `comments.js` file can be run like this:

docco comments.js

view raw commandline.sh This Gist brought to you by GitHub.

You can also use file patterns such as `*.js`

Setting Up A Rake Task

I don’t like to run things manually when I don’t have to. Since my Marionette project uses Sinatra and Rake to run it’s Jasmine test suite, I decided to create a Docco task. Here’s what that would look like, for the above comments.js file:

desc "Build the Docco annotated source documentation"task :docco do  `docco comments.js`end

view raw rake.rb This Gist brought to you by GitHub.

Now I can run `rake docco` from the command line and it will build the docs for me. … yeah, this is probably overkill, but I wanted to do it anyways. :)

The Results

Here’s the results of running Docco against the above comments.js file (view it here, if you’re in an RSS reader):

In my previous post on Composite JavaScript Apps, I introduced a few of the high level design ideas and implementation details that I have been using in an application that I’m building. Since then, the requirements for that app have grown significantly and I’ve made more progress toward a better composite application design.

Content Swapping

My simple item management application started out with nothing more than these three regions on the screen:

Once this was in place, though, a new requirement came along… a complex search with search results. To implement this, I needed to modify the application’s interface to swap the grid and add/edit form out and put in a search results screen instead. The idea is that when the user does a search, the main content area will show the search results. The user can then go back to the location management aspect of the app whenever they need to. After a bit of searching, I found a high level pattern that made this easy, and also realized that I had previously implemented the core of this pattern without knowing it.

Microsoft Prism: Regions and Region Managers

Several years ago, Microsoft released a framework for it’s WPF and Silverlight runtimes, called Prism. This was essentially the big composite app framework that people used to build well structured and decoupled apps in XAML. I never had a chance to use this framework directly, but I worked with a team of developers that did use it.

One of the things that I liked about what I saw in Prism was the way it used the idea of “regions” and “region managers” to compose the user interface. The gist of it is that you could define a visible area of the screen and build out the most basic layout for it without knowing what content was going to be displayed in it at runtime. Then at runtime, your application modules could register themselves to have content displayed in the various regions of the screen.

This pattern fits perfectly with the direction that my Backbone app is heading, so I decided to borrow the names and build my own version in JavaScript.

A Simple Region Manager

In Prism, a region is defined in the XAML markup. In web applications, it’s defined in HTML markup. Similarly, in XAML a region manager is code that you write in C# or other .NET languages, while a region manager in a web app is going to be JavaScript. Backbone.js provides a good separation between the markup and the code to run that markup through it’s Views, so I initially thought about going down this path for my region manager. After a bit of thinking, though, I realized that I didn’t necessarily need a Backbone view. What I really need, at the very core, is a JavaScript object that do the following:

• Represent an existing DOM node
• Change out the contents of that DOM node
• Call any required rendering and initialization for content views that will be displayed
• Call any required cleanup for content views when they are removed

What I came up with as an initial pass at handling these needs, is the following (hard coded specifically to use a “#mainregion” element from the DOM):

RegionManager = (function (Backbone, $) {    var currentView;    var el = "#mainregion";    var region = {};
    var closeView = function (view) {        if (view && view.close) {            view.close();        }    };
    var openView = function (view) {        view.render();        $(el).html(view.el);        if (view.onShow) {            view.onShow();        }    };
    region.show = function (view) {        closeView(currentView);        currentView = view;        openView(currentView);    };
    return region;})(Backbone, jQuery);

view raw regionmanager.js This Gist brought to you by GitHub.

Does that look familiar? It certainly does to me. I’ve written this same code dozens of times and blogged about it in my Zombies! RUN! post. So, it turns out that I’ve been using what I’m now calling a “region manager” for a while – I just didn’t realize it, previously. Oh, happy day! I’m just formalizing a concept I had introduced somewhere else, instead of having to create something new and unknown. :)

Using The Region Manager

An in-depth use of the region manager has been covered in my Zombies post already. As a refresher, though, you only need to provide a Backbone view to the `show` method and the region manager will take over from there.

MyView = Backbone.View.extend({  render: function(){    $(this.el).html("some html contents");    $(this.el).hide();  },
  close: function(){    this.remove();    this.unbind();  },
  onShow: function(){    $(this.el).show(500);  }});
RegionManager.show(new MyView());

view raw view.js This Gist brought to you by GitHub.

The usual `close` method exists so we can handle our zombie problems. I’ve also added a bit more to the API that the region manager can handle, making it more robust and allowing it to handle more complex UI needs. Specifically, an `onShow` method fires on your view if you’ve provided one, just after the view’s `el` has been added to the DOM. This method will let you call into code that expects the DOM elements to exist, to manipulate them.

In this simple example, I’m using the `onShow` to fade the contents of the view in to view, using jQuery’s `.show` method and giving it a 500 milliseconds (1/2 of 1 second) time to do the fade. It’s a simple idea, but one that I’ve found is needed when using some libraries, such as the jQuery layout plugin. Again, this isn’t an idea that I came up with, either. I took this directly from my experience in working with WinForms applications. `onShow` is a standard event in the lifecycle of a Windows form, in .NET. It works well there, and it works well here in JavaScript, too.

But Wait! There’s More!

Well, maybe there isn’t anything more at this point in time. But there will be soon. As I’m traveling down the composite application path, I’m starting to extract the useful bits into a library so that I don’t have to rebuild the same things over and over again. If you’re interested in watching this grow over time, checkout my Backbone.Marionette repository on Github. It’s nearly empty at the time of writing this blog post, as it’s a work in progress. I plan on making a large announcement about it when I have more to share, sometime in the future.

I was digging around on twitter and I found a great comment from @BenAtExocortex:

“Javascript has no block scope (!) but one can use self-executing functions instead (as Javascript has function scope.)”

What Ben is referring to is that JavaScript doesn’t scope your variables to if statements or other blocks the way C# and other languages would. Consider this example in C#:

public void DoSomething(){  // c# scopes variable declaration inside of blocks  if (true){    int i = 0;  }  // this is a compiler error or warning  i++;}

view raw block.cs This Gist brought to you by GitHub.

On the “i++” line, the C# compiler (or Resharper / Telerik JustCode / etc) would throw a compiler error or warning, telling you that the variable isn’t defined at this point. This happens because the variable declaration is scoped to the if statement.

In JavaScript, though, the same code is perfectly fine:

function doSomething(){  // javascript scopes variable declaration inside of blocks  if (true){    var i = 0;  }  // this is perfectly fine, and results in i == 1  i++;}

view raw block.js This Gist brought to you by GitHub.

This is because JavaScript scopes your variables to functions and not to if-blocks. But, we can achieve block-like scope through the use of immediate functions like this:

function doSomething(){  // outer scope variable  var i = (function(){    if (true){      // inner scope variable      var x = 0;    }    x++;    return x;  })();  // the result is i == 1, inside of doSomething's scope}

view raw block2.js This Gist brought to you by GitHub.

The “i” var in the “doSomething” function is assigned the value returned by the immediate function. The “x” var is scoped to the immediate function giving us block-like scope for our variables.

Of course, this does add a bit of noise to our JavaScript. Chances are if you need something like this you’ll really want to extract a proper function. There’s also some memory and performance implications due to re-defining and executing the immediate function every time you run “doSomething”. But, if you understand the implications and you need to achieve block-like scope in your JavaScript to isolate temporary variables, this is one way to do it.

I hear a lot of talk about how it’s a performance penalty to use globally scoped variables in JavaScript (not to mention, dangerous / dumb). When a function looks for a variable, it checks the current scope, then it checks any outer scopes that the function may be nested in, and finally it reaches the outer-most scope: the global scope of the JavaScript runtime.

It occurred to me, as I was wrapping up the edits for my “Variable Scope In JavaScript” screencast, that this is evidence to suggest that access to the global scope, from anywhere other than the global scope in a JavaScript runtime environment, is nothing more than a closure.

Look at it this way: when we access the “foo” variable from within the “sayFoo” function of this code

(click the link for the JSFiddle, if you’re in an RSS reader) the runtime has to step out of the “sayFoo” function and find the “foo” variable declared in the “outerScope” function.

Now look at similar code accessing the `$` variable from jQuery, as well as a `bar` variable defined in the outermost, global scope:

Honestly, I had always assumed that there was something special about the global scope of a JavaScript runtime. I had assumed that the browsers and other runtimes had to build some special mechanism in which the global scope was made available to other scopes. It looks like global scope is nothing more than the bi-product of the closure support that JavaScript has built into it, in combination with the outermost scope of the runtime (a DOMWindow or some other scope for CommonJS implementations).

… mystery, suddenly not so mysterious.

There’s an unfortunate dichotomy of “Backbone vs Knockout” floating around these days. It’s mostly in the .NET space where Knockout tends to get the most attention but I’ve heard others mention this, too. It’s an unfortunate argument, though. Both libraries are great, both are very powerful and both solve different problems in the front-end development space. The major difference between the two is the focus of each.

Strengths And Weaknesses

Knockout aims to provide slick, easy to use model bindings between the HTML and Model. It’s very XAML/Silverlight/WPF like in it’s implementation and usage patterns (this makes sense considering where it came from). Knockout does not provide guidance or constructs beyond the model, though. It’s up to the developers to build well structured JavaScript applications beyond the models and model bindings. This often leads developers without good JavaScript experience down a bad path because they don’t realize that they need to consider good application structure when using Knockout. Of course this problem is not the fault of Knockout by any means. It’s simply a lack of understanding of what the tool provides, or how to structure large JavaScript apps, in many cases.

Backbone, on the other hand, takes a “good JavaScript app architecture” approach. It focuses on providing constructs that can be used to organize your code in meaningful ways. One thing to note about Backbone is that it’s not a heavy-handed, prescriptive MVC framework. In truth, it fits within the MV* families, but is not MVC or MVVM or any other specific variant. It takes ideas from a lot of these variants and provides a library of constructs that can be used when needed, without requiring the use of any of them. This is one of the reasons I’ve stuck with Backbone – it’s flexible. It lets me use only a View when I want to, or only a Model when I want to. Unlike Knockout, Backbone does not directly address the model binding space. It provides plenty of hooks and open / flexibility in it’s design and implementation, though, allowing model binding to be integrated in to it.

Model Binding

It really is a shame that there is such a “Backbone vs Knockout” mentality when these tools should play together and create an even better experience for the developer and end-user. The big problem has been that they clobber each other when it comes to the idea of a “model”. However, Knockout’s recent releases have an API that can be used to bind anything to Knockout. With that, here’s a project up on Github that brings both KO and BB together:

https://github.com/kmalakoff/knockback

There’s also my own Backbone.ModelBinding plugin which aims to bring a lot of model binding capabilities to Backbone without using Knockout (while being heavily inspired by it):

https://github.com/derickbailey/backbone.modelbinding

Knockout -> Backbone

For what it’s worth: I know a handful of people that start with Knockout because of the astounding demos and jaw-dropping ease of creating model bindings. After building some very large JavaScript apps, though, they wished that they had gone with something like Backbone which provides a better structure out of the box for large apps. I’m not saying you can’t built large JavaScript apps with Knockout. You have to build the infrastructure or find another infrastructure to support the large app design needs, though.

Knockout AND Backbone

With Knockback bringing both of these projects together, maybe you don’t need to choose one or the other for the system at large. Maybe you can get down to choosing which one is right for the specific page your building, including both of them when needed.