When I first started investigating Ember.js I wrote a post about an Ember addon called the SC.StateChart that is really part of the old Sproutcore framework. In that post, I wrote that I liked the enterState and exitState handlers of the StateChart and how they would be ideal for switching between views. As of Ember 0.9.6, the SC namespace is no longer supported and I decided to refactor/remove anything that was Sproutcore related. It was during this refactoring that I found a very similar object called the Ember.StateManager that already exists in the Ember core code. It turns out that the Ember StateManager is a very elegant solution to transitioning between views and attaching and removing views from the DOM.

The Ember StateManager is part of Ember’s implementation of a finite state machine. Simply put a state machine can be in only one of a finite number of states. The machine is only in one state at a time; the state at any current time is called the current state. It can change from one state to another when initiated by a triggering event or condition, this is called a transition. The classic example is a state machine that represents a lightbulb transitioning from the off state to the on state.

Let us flesh this out with some code. Below is a StateManager that I am currently working on:

• On line 1, I am defining a definition from which a StateManager instance can be created from. I am actually extending another definition called the RouteManager that extends StateManager. The RouteManager is part of an excellent addon called the ember-routemanager that ties the StateManager and a routing implementation together. More on this later.
• On line 3, the initialState property is set to instruct the StateManager which state to transition to when an instance of the StateManager is created. I am using the Ember path dot syntax to say that the initial state will be a state named home (line 11) that is a child of a parent state named main (line 6).
• On line 6 is the definition of the previously mentioned parent main state. A StateManager is composed of child state objects. In this example, the StateManager is composed of Ember.ViewState objects. Ember.ViewState objects can contain Ember.View objects (as you would expect).
• On line 15, is another state named vault that has a child state named index (line 20).

An Ember.ViewState object extends Ember.State and as the name suggests, Ember.View objects are associated with the Ember.ViewState . All child state objects in the above example are ViewState state objects and each view has a templateName property that is a relative path to a handlebars template.

Anybody from a .NET background will wince at the name ViewState but I can assure you, there is no connection whatsoever.

When a StateManger is composed of instances of ViewState objects, the StateManager will interact with Ember’s view system and manage which views are added and removed from the DOM based on the StateManager’s current state. One way of transitioning between states is to invoke the goToState method:

@routeManager = WZ.ContentRouteManager.create()
@routeManager.start()

@routeManager.goToState 'vault.index'

The above example will transition to the index state which is a child of the vault state. Using the Ember path syntax allows you to transition to a child state in one statement, no matter how deep it is. When you transition from one ViewState to another, the view of the currentState is destroyed and removed from the DOM as you exit the state and the view of the ViewState you are transitioning to is created and attached to the DOM as you enter the new state.

The StateManager can also receive and route action messages to its states via the send message, which you can read about in the Ember docs.

I find the StateManager to be a very elegant solution that is bereft of tedious boilerplate code. This is in stark contrast to Backbone.js where the user is left with both the architectural decision and the execution of how this should take place. I mentioned one such solution in my Backbone.js - Lessons learned post.

My first attempts at Backbone were littered with a lot of repetitive code like the following:

In Backbone, I think there is too much boilerplate code required to glue everything together. I have started using Derick Bailey’s excellent backbone.marionette recently with Backbone and you really need to use this if you are using Backbone regularly.

Nested ViewStates

When ViewState objects are nested like in the example below:

Both the StateManager’s currentState and any child states of the currentState will draw into the StateManager’s rootView property (line 2). In the above example, the RouteMangaer will initially transition to the path defined in the initialState property which in this case is the main.home path which points to the home state on line 11. This means that the handlebars template declared with the templateName property in both the main state’s child view object will be compiled and attached to the DOM and the handlebars template defined in the home state’s child view object will be compiled and attached to the DOM.

Below is how the main state’s view and the home state’s view look when they are rendered onto the browser: You can get quite inventive and compose reusable partial views as and when you need them. I am setting the rootView property which means I can just layer views onto the body element of the html document but you can also specify a rootElement property:

rootElement: '#some-other-element'

Routing

This brings us nicely on to routing, as I mentioned earlier, I am using the excellent ember-routemanager addon that ties the StateManager to a routing implementation. This addon allows you to create RouteManager instances that derive from the now infamous Ember StateManager. Below is a reminder of how I am extending the RouteManager:

It is worth noting that I am not creating an instance of the RouteManager but merely extending it which will allow me to create an instance on application start up or create instances in my jasmine specs.

What you should note from the above gist is that I am defining a route property on each child state object (lines 7, 12, 16 and 21). This allows me to use a combination of the route property and the nesting of the child states to define client routes that will transition to the required states and attach and remove the views from the DOM.

Below is how I create an instance of my derived RouteManager:

@routeManager = WZ.ContentRouteManager.create()
@routeManager.start()

The start method will start the RouteManger listening for location changes. This allows me to define routes either as the now familiar hash links:

<!--Transition to the vault.new state -->
<li><a href="#vault/new">New</a></li>

Or I can programatically set the location property which is useful for testing:

@routeManager.set 'location', 'vault/index'

All that you would expect from a routing frameworks seems covered, below is an example of a route with a dynamic parameter:

route: 'vault/:exerciseid'

Setting the browser location to #vault/5 would map to the vault state with an exerciseid of 5. Wildcards and regular expressions are also covered:

route: /(\d{4})-(\d{2})-(\d{2})/

Conclusion

I got quite excited as I explored this approach (I should get out more). This is a real productivity boom that could be further enhanced by having the route inferred using convention over configuration by dynamically creating the route with respect to the state’s nesting. The RouteManager/StateManager/StateMachine is a very elegant solution for transitioning between views that exists in many other smart client UI frameworks. Being a web developer, I just have not come across it before.

Testing the RouteManager

I ran into a few problems when testing the RouteManager. Below are some initial specs that now all pass:

One of the problems I had was clearing the rootView property and disposing of the RouteManager after each spec. This is solved in the afterEach method on lines 10 to 16 of the above gist where I am removing each view from the DOM and destroying the StateManger.

Please feel free to add any comments below.

Scenario

The rails project that I am currently working on presented an interesting problem which I am guessing is a reasonably common one. The problem is how to have a long running process run both independently of the browser and display results in the browser as and when they happen. This is my solution to the problem but I would love to hear how others have dealt with the same scenario.

The focal point of the application in question initiates a long running process that crawls a web site that is specified by user input (see image below) and screen scrapes each page in the site with the intent of collecting any data that meets a certain search criteria. This long running process could last many minutes and it is safe to say that each process will outlive the lifetime of a standard page request in terms of time. The long running process will persist any results that are found to a backend data store. The first requirement is that the job completes if the user closes down their browser. The next requirement is that if the user is connected to the browser, I want to visually display any results that are found by adding data rows to a data table as and when they happen and not have to wait until the process has executed to render all the results at once. Below is a screenshot of how the user inputs their search terms and how the data is displayed. While working on the window’s platform, I have often used Microsoft’s MSMQ for reliable messaging so I just needed to do some research into what was available on non-windows platforms. The message queue handler will be charged with doing the actual work of crawling around the website and persisting any results to the backend data store. This will fulfil my requirement of having the job complete if the user closes down the browser.

That just left displaying the results of the screen scraping in the UI as and when they are found. I could have used polling to periodically check for results on the backend store but this did not seem in keeping with the times and this also appeared to be a great excuse to play about with websockets. I just needed someway of having the queue handler pass the results back to the websocket layer as and when they are found.

Solution

The creation of a queue handler and a websocket layer are easy problems to solve separately, the hard part was finding a means for the two distinct boundaries to communicate together.

The websocket layer seemed very well covered on the ruby and rails platform and the EventMachine based, async EM-Websocket Ruby websocket server was an obvious choice.

When it came to queuing, I first looked at the popular resque library as my background job processor or queue handler but I could not find anyway for the queue handler to speak to the websocket layer. I then looked into RabbitMQ which has many more features that are a better fit for my needs. As there is a gem for everything in Ruby, I quickly tracked down the AMQP gem which is a feature rich well maintained, fast, asynchronous RabbitMQ ruby client.

AMQP stands for Advanced Message Queueing Protocol and is an open standard for passing business messages between applications or organisations. You can think of it as an interface describing a common set of functionality that all message queuing systems must provide if they implement the AMQP interface.

RabbitMQ RPC

After a bit of digging about, I came across a messaging pattern that was a good fit for my problem which is the RPC pattern. We all know about RPC (Remote Procedure Calls) in general computing terms but how does this translate to the message queuing world?

In the context of my application, the RPC pattern manifests itself like this:

The user will submit a url to perform the search that will be sent to the websocket layer via the following clientside coffeescript code:

The above code contains an Ember.js controller with a start_parsing method/action on line 2. When the user enters a url, this method is called and an Ember url_search model object is created containing the url of the site to be scraped.

• On line 3, a new websocket connection is attempted.
• The onopen event fires when a successful connection has been negotiated. Line 7 provides an event handler for the onopen event that transforms the url_search object into a JSON string and sends it to the websocket server.
• On line 12, an onmessage handler is provided for the websocket layer to transmit any results that are found while screenscraping the site.

Below is the EM-WebSocket server that the Ember controller listed above will communicate with:

• On line 2, we start the EventMachine event loop by calling the run method. The event loop can be thought of an endless loop that can be stopped and started by designated events or the expiration of a timer. Everything from line 2 onwards is the block that is passed to the run method and is executed during the lifetime of the event loop.
• On line 3, the connection details for the rabbitmq server are specified (more on this later).
• On line 11 the WebSocket server is started via the start method.
• Line 14 provides an event handler for the server side websocket onopen event.
• Line 19 is the server side onmessage event handler which is triggered when the Ember controller of the previous gist, sends a message containing the JSON of the url search request.
• Line 22 calls the yet to be exposed publish method that will send a message request to our rabbitmq server instance.

The RabbitMQ RPC Client

So far, we have initiated a new websocket connection with the server and sent a JSON string that can be transformed into an object that describes what website to crawl and scrape results from.

I stated earlier that the RabbitMQ RPC pattern will allow the backend queue handler to communicate with the websocket layer. The webscocket layer can be thought of as the RabbitMQ client and the backend queue handler can be thought of as the RabbitMQ server. The websocket layer outlined above is our RabbitMQ client layer that will send a request message containing the JSON string sent from the front end Ember controller code outlined in the first gist.

In order for the RabbitMQ client to receive responses from the RabbitMQ server, we will need to specify a callback queue that the RabbitMQ server can send messages to. In the context of my application, the RabbitMQ server will send data scraped from the specified web site back to the front end code that will render a new row in a table for each result found.

In order to put this into the context of my application, below is the code that both creates a callback queue for the RabbitMQ server to communicate with and publishes the request message to the RabbitMQ server.

• On line 2, I am creating what is well known in messaging circles as a correlation id. The correlation id or unique identifier will be used to correlate (obviously) or associate the RPC responses with the request.
• On line 4, a RabbitMQ connection is made from the configuration hash specified in the pervious gist.
• On line 6, I am creating the callback queue that the RabbitMQ server will send responses to. The important thing to note here is that I am specifying an empty string as the first argument for the queue creation. If you do not specify a name then an anonymous queue is created. The RabbitMQ server will assign the queue a random name which can be used later to let the RabbitMQ server queue handler know which queue to send the RPC response messages to.
• Line 8 sets up the callback queue to receive messages from the RabbitMQ server.
• Lines 9 to 11 contains the code that handles any message sent from the RabbitMQ server. Line 11 sends any results back the UI code if the WebSocket connection is still open. This will in turn, trigger a client side onmessage handler:

socket.onmessage = (evt) ->
  Lead.get('leads_controller').addLead evt.data

• On Line 14 the append_callback method is invoked which takes a block of code as one of its arguments. The block will be executed when the declare event of the queue creation is triggered. It is important to wait until this event has been fired because we want to ensure that the anonymous queue has been created and the name of the anonymous queue is available to send to the RabbitMQ server.
• Line 15 publishes the message to the RabbitMQ server. It is important to note the :reply_to and :correlation_id arguments that help tie the RPC calls together. The RabbitMQ server will now know the details of the anonymous queue to send any responses to.

The RabbitMQ RPC Server

So far, we have sent a message from the front end code containing any arguments required in a JSON string, we have also set up a callback queue that we can send any parsing results to and finally we have published the request message and specified the name of the anonymous response queue that we can send any results of the screen scraping to.

Below is the code for the rabbitmq server in nearly all of its entirety:

• Line 17 defines the Thor task that contains the RabbitMQ server code. What I like about Thor is that a Thor task is just a plain old Ruby method defined in a ruby class that inherits from the Thor superclass.
• Line 19 calls the AMQP start method that opens a connection to the RabbitMQ server.
• Line 22 creates the queue that will listen for request messages from the RabbitMQ Client or websocket layer.
• Line 33 uses the subscribe method of the AMQP queue object that takes a block as an argument which gets passed a message each time a message is published to the queue. The block takes 2 parameters, the header which is the metadata of the message and the body of the message which will be the JSON passed from the client. The metadata header is especially important in this case because it will contain both the correlation_id and the reply_to details that were created in the RabbitMQ client layer and give us all the data we need to communicate any results back to the RabbitMQ client layer.
• Line 38 creates the parser object that does the actual crawling and screenscraping.
• Line 40 calls the find_potential_leads method of the parser object that takes a block and yields any leads found back to the block that will allow me to publish any leads via the reply_to queue back to the websocket layer.
• Line 42 serialises the result into a JSON string ready to pass back to the websocket layer.
• Line 45 publishes the json string back to the RabbitMQ client websocket layer by specifying the repy_to and correlation_id from the header of the incoming message.

And that is job done, I have communication between my websocket layer and my RabbitMQ server layer using this quite simple RPC approach.

I have created the RabbitMQ server process as a Thor task. I like the name spacing capabilities of Thor that lets me execute namespace tasks with respect to their environment like:

thor worker:dev:start_consumer

I also like that Thor tasks can easily accept parameters which is in stark contrast to how Rake handles parameters.

Conclusion

I struggled for quite a long time to find something that fitted my needs. My next steps are to refactor the client code to use SockJS for better cross browser support.

If you disagree with any of the above or can point out a better way then I would love to hear from you, please leave a comment below.

I am currently using Ember.js for a side project and I have ran into some interesting and unexpected behaviour while driving the development of the front end code test first. I am using the excellent javascript bdd library Jasmine as my test runner and I must also issue a warning that the code examples listed below are in coffeescript. I have also been using the excellent guard-jasmine gem to automatically run my tests when any files are modified which really is a great experience.

I had vaguely heard of the Ember runloop in a few of the articles that I had read but I had not had to deal with it directly until I started getting more and more unexpected behaviour in my tests.

This is best illustrated with some code. Below is a simple Ember controller/object that creates a view in its constructor:

The above code creates an Ember model object in the constructor of the controller on line 5 which is then bound to the view on line 9. The view is then attached to the DOM on line 12.

Below is my original failing test that I wrote:

I wrongly expected that the code on line 4 would create the controller and subsequently attach the view to the DOM immediately. What was equally as perplexing was that the view appeared to be immediately appended onto the DOM when viewed in the browser.

I threw this question out to the ever expanding universe (twitter) and the ever expanding universe (twitter) responded in kind. I cannot actually remember who answered (apologies) but the response was along the lines of:

Ember defers the DOM manipulation until later via the runloop. You can make the runloop execute immediately by calling Ember.run.end()

This advice was only half right, more on that later.

So what was this crazy man’s talk of a runloop? To understand what the runloop is, it is worth considering one of Ember’s strengths or main selling points which is its bindings support. A binding simply connects the properties of two objects in such a way that when one property changes, the value of the other one changes. With Ember you would generally not change the DOM directly, you would instead make a change to the model and let the relevant bindings reflect this change. This is MVC done properly with changes to view being reflected in the model via the observer pattern. With backbone.js, you generally react to DOM events which is quite limited because it is all too easy for the model and view to become unsynchronised and tedious error prone code is required to keep the two in sync.

It turns out that the runloop is a critical piece of the Ember machinery that ensures all bindings propagate data changes to their bound listeners. In the example I outlined above, I have the following binding that binds my model to the view:

urlSearchBinding: 'controller.url_search'

Then in my handlebars template, I am binding the value of an input field to the search_url property of the model:

view Ember.TextField size="60" valueBinding="urlSearch.search_url"

The upshot of this is that when a user enters some text into the input field, the search_url property of the model will change to the text that has been entered into the input field. The reverse is also true, a change to the model will result in the input changing. We could take this further and have another bound object whose property subsequently changes when the search_url property changes of our model and so on. This is could turn into a performance and synchronisation overhead if the Ember runtime was constantly reacting to each binding as and when they change.

Behold the runloop

The runloop is charged with batching up all the binding updates into one final set that can be executed all at once at a designated point in the runloop. Typically Something triggers the start of the runloop which is more often than not, one of the many supported browser DOM events that Ember has registered itself to listen for, e.g. click, mouseup, etc., etc., etc. The runloop can also be triggered manually with code or from the expiration of a timer. If we change a property using the set method of an ember object like below:

@url_search.set('search_url', 'http://thesoftwaresimpleton.com/')

The change to the binding is not propagated immediately but instead is placed on a queue or deferred for later execution at the end of a running runloop. When a runloop is triggered from a DOM event or manually in code, the bindings are not flushed until a certain point in the execution lifecycle of the runloop. The runloop is also in charge of other things like executing expired timers.

The important thing to remember here is that Ember waits until all the bindings have been propagated or flushed before updating any views which is why my code works fine when running in the browser but not in my test. The runloop had not finished and the bindings had not been flushed so the view did not update.

It is thankfully possible to manually start a runloop with code which turned out to be the missing link in my initial tests. A runloop can be manually started at any time by placing your code between an Ember.run.begin() and an Ember.run.end() statement. Once Ember.run.end() is called, you can be assured that all your binding changes will be flushed and any timers will be expired. Only after Ember.run.end() has been called will any views be updated. With this assurance, I can now test for the existence or changed state of DOM elements in my tests. Below is how the now infamous failing test can be made to pass:

On line 5, I am triggering the runloop via the convenience method Ember.run which accepts a function as an argument. Ember.run() will take care of wrapping the passed in function between Ember.run.begin() and Ember.run.end() statements. Needless to say, the test now passes.

The runloop is now incorporated into the majority of my tests where I ensure that the unit or critical part of the application that I want to test is running in the context of a runloop. Below is an example of a test where I test my interaction with an Ember state manager:

On line 8 I ensure that the send method of the state manager is wrapped in a runloop.

Conclusion

I am not sure if I would have discovered the runloop had I not been writing tests. I think the runloop is an amazingly powerful concept and is used in many other frameworks and platforms. I think one of the IPhone frameworks uses it in a similar fashion.

Before I finish, I want to point out another trapdoor that I fell down before becoming better acquainted with the now infamous runloop. My first attempt at dealing with the runloop is in the gist below where I just blindly added Ember.run.end() to my test on line 5 in order to end the runloop and flush the changes:

This is bad for a number of reasons, namely because other tests will now rely on Ember.run.end() being called from this test and as we all know, tests should be atomic and not rely on things being in a particular state due to the execution of another test. If I delete the test, the runloop no longer completes. What is equally as bad is that the runloop is being terminated unexpectedly for other tests. This was another blind alley I gladly wandered down before deciding to do the research and write about it in this blog.

If I have got any of the above wrong then please leave a comment below. I would love to be corrected.

I’ve been hacking away on quite a detailed results page that uses Ember.js and Handlebars templating to render html on the client when it receives JSON objects from a websocket connection on the server. This turned out to be much more difficult than I first envisioned and I thought I would blog about it in order to help anybody else who struggles with some common problems. If anybody with greater Ember knowledge than my own can point to a better way then please leave a comment below.

Scenario

Below is a screen capture of what I finally ended up with.
Each row in the table displays the company details that are extracted from a website screen scraping search operation. Each row can be expanded to display any additional child detail. The child detail can contain any additional email addresses and contact details that have been scraped from a web site search and belong to the parent company detail row.

Enter the Ember.ArrayProxy

One of Ember’s strengths is its excellent databinding support and out of the box, it comes with the Ember.ArrayProxy. The ArrayProxy is a construct that wraps a native array and adds additional functionality for the view layer. In this example, I am going to use the Ember.ArrayProxy as a means to publish a collection of objects that I can easily bind the collection to using the handlebars #each helper (more on this later).

It is worth noting that you might also see the ArrayProxy out in the wild called the ArrayController. I was informed by somebody on twitter that the ArrayController is now just an alias to the ArrayProxy. A quick look at the source confirmed this:

Ember.ArrayController = Ember.ArrayProxy.extend();

The ArrayController is a throwback to Ember’s sproutcore days and will at some stage be depreciated (I think). I prefer the name ArrayProxy because it is not a controller in the MVC sense of the word and ArrayProxy is a better description of the object’s behaviour.

Below is how my extended ArrayProxy ended up:

• The constructor of the ArrayProxy superclass is overriden on line 2.
• On line 3 I am calling the base class constructor of the superclass ArrayProxy with @_super(). If you do not call @_super() the ArrayProxy will not initialise peroperly. I only found this out after a lot of head scratching as to why my ArrayProxy was not working.
• On line 5, we are setting the initial array that will be wrapped by the ArrayProxy. This is done by setting the content property. The content property must be an object that implements either Ember.Array or Ember.MutableArray. For the starting position of our view, we want the ArrayProxy bound to an empty array. Ember.A() will return an empty Ember array.
• On line 7, we create that will reference the handlebars template. The virtual path to the handlebars template is set on line 8 and on line 10 we attach the initial view to the DOM.
• The addLead method on line 12 takes a string of JSON as an argument, creates an Ember model object and uses the setProperties method to set multiple properties of the Ember model object with a hash which we create from the passed in string. Below is how the Lead class looked initially:

Lead.Lead = Em.Object.extend

• On Line 15, the newly created object is added to the wrapped array with the pushObject method. This reveals the beauty of the ArrayProxy, when pushObject is called, the bindings will automatically update and render the new lead in the view’s output. The removeObject method works the same in reverse. This requires a lot less boiler plate code than would be required with backbone.js.

Problem 1 - Numbering the results

I will get to the code for the handlebars template shortly, but first I want to show the first problem I came across and that was how to number the results of the table. Below is an image that highlights the numbering of each row: Below is my handlebars template that will render each object added via the pushObject method. This is the template that the Ember view in the previous gist pointed to.

On line 13 of the gist, I am using the #each helper which facilitates iterating over an enumerable object. When I first came across the #each helper used in conjunction with the ArrayProxy I thought it would re-render the list each time you called pushObject but this is not the case. A new item is rendered from #each for each new object inserted into the array when pushObject is called.

I am binding the #each helper to an accessible object instance named Lead.leads_controller which is actually an instance of the ArrayProxy defined in the previous gist. The ArrayProxy acts as a normal array and has enumerable behaviour.

When I first wrote this template, I used the #collection view helper instead of #each. The #collection view helper creates a view for every item in the list. I was informed again via twitter that the #collection view helper would soon be depreciated so I refactored the code to use #each and created a separate view for every item in the list which you can see on line 14 with the following line:

#view Lead.Views.Leads contentBinding="this"

The contentBinding property is set to this which in this context is the current item in the list. This is a derived view that I have created named Lead.Views.Leads and is listed below:

The important bit is the Ember property adjustedIndex that is listed on line 4.

If you are unfamiliar with coffeescript, below is how this would look in javascript:

adjustedIndex: function(){
                 this.getPath('_parentView.contentIndex') + 1;
               }.property();

This function defines what is known as an Ember computed property. Computed properties allow you to treat a function like a property. This is useful because we can treat the computed property like any normal object properties in our handlebars template. In the above example we are accessing the contentIndex property of the _parentView object and incrementing it by 1. The fact that the _parentView object is prefixed with an underscore is usually a convention to tell the user of the code that this a private member but I don’t think we are doing much harm in this instance.

This seems like a lot of work for this example but computed properties are a powerful feature and can have observable behaviour that allows your template to be auto updating which is one of the main selling points. We can also now reuse this view to get the adjustedIndex at any point in this template or others.

Problem 2 - Conditionally Display Results with Handlebars

When it comes to displaying child results, I want to be able to display a message to the user if no results have been found. For example below is a message I want displayed in the event that no email addresses could be found in the context of the parent row. Handlebars comes with the #if helper which does what you would expect with one gotcha. Handlebars does not support conditional statements like

#if content.emails.length > 0

or

#if x < y

I agree with this because any logic like this should be wrapped up into a helper to make sure the template stays clean.

Below is the part of the template that renders the child emails rows:

• On line 1, we are referring to a property named hasEmails of the bound item which in this case is the Lead class I displayed earlier that the handlebars #if helper uses as a boolean expression.
• On line 2 and in the event that hasEmails returns true, we are binding the #each helper to the emails array property of the parent object.
• On line 3, we are reusing the view we created earlier to utilise the adjustedIndex property.
• On line 10 we use the handlebars else expansion that can be used with any block helper to represent what the output if the given expression evaluates to a falsey value.

Below is the Lead class I mentioned earlier with two new computed properties named hasEmails and hasContacts that will be used as boolean expressions by the #if helper. I am using the Ember.computed function to create the computed properties this time round but the result is the same as before and it looks a bit neater and a bit more in keeping with coffeescript.

Conclusion

Ember certainly feels like a much richer framework than backbone.js which of course means it is a larger framework with more to learn. There are different abstractions to utilise like the ArrayProxy and I think handlebars is the most feature complete of all the templating libraries I have tried so far. I am going on to experiment with handlebars partials next.

I have been using Backbone.js in my day job recently for quite a few months on a thick client javascript application. I have enjoyed the order and structure that the framework has brought to my javascript code. I have also learned a lot of organisational and structural techniques by reading the book JavaScript Patterns recently.

Like most developers, I am working on a sure fire billion dollar side project. In order to maintain the clear distinction between my day job and my side project, I have decided to use Ember.js as my client side framework for this billion dollar baby. I have been very impressed by what I have found so far. I have also found an interesting new paradigm for clientside MV* that inspired me to write this post. I don’t want to say too much about the differences between backbone and Ember or even too much about Ember as there is a wealth of information already out there but I will point out my preferences for using Ember.js over Backbone.js:

• Bindings - Ember relies heavily on bindings as the core abstraction while backbone relies on raw DOM events. A binding simply connects the properties of two objects so that whenever the value of one property changes, the value of the other one changes. For example below is a simple Ember controller that contains a simple Ember view:

On line 7 is a property called urlSearchBinding. Ending a property with Binding tells Ember to create a binding between the object defining the binding which in this case is the view and the referenced object on the right hand side of the property definition which in this case is the url_search object. I can now reference this binding in my handlebars template like this:

On line 2 of the above gist, a binding is created between the value property of the Ember.TextField object and the search_url property of the urlSearch object that is bound by the urlSearchBinding on the view. The upshot of this is that whenever the value attribute of the input changes, the urlSearch’s search_url property changes. I much prefer this approach than having to pull values out of the DOM. There is a lot more to bindings that you can read about in the Ember Docs. You can also set up observables that help tie the whole Ember MVC pattern together.

• Out of the box Handlebars support - Ember takes a more opinionated view on which clientside templating library to use and comes already hooked up with Handlebars support. It is possible to compile your templates serverside on Rails by hooking up a Rails initialiser to look something like this. I use underscore.js templating with backbone and handlebars is by far the superior library. I have also used JQuery templating which is my least favourite of the three I have tried.

OK, but what about StateMachines?

While looking into Ember I found an interesting Ember addon called the Ember Statechart. I have no idea why they called this a statechart and not a statemachine which is really what it is. The state machine pattern is a tried and trusted way of organising computer programs that has existed for a hell of a long time. Simply put a state machine can be in only one of a finite number of states. The machine is only in one state at a time; the state at any current time is called the current state. It can change from one state to another when initiated by a triggering event or condition, this is called a transition. The classic example is a state machine that represents a lightbulb transitioning from the off state to the on state. It is also possible to associate actions to a state, for example:

• Entry Action - which is performed when entering a state.
• Exit Action - which is performed when exiting a state.

In the ember statechart, these two actions or handlers manifest themselves as the enterState action and the exitState action and appear on every state. These actions or handlers are a perfect fit for complex UI interactions. A client MV* application is truly stateful and there is always init and dispose code that needs to happen as you transition between views or states. The entry and exit state actions provide a perfect place to initialise the views, persist state, hide and show elements or dispose of views and resources. I recently coded a complex tabcontrol that could have benefitted greatly from a statemachine to switch or transition between tabs.

Enough talk, show me some code

Below is a very simple example of a statechart:

Now let me breakdown the code

• On line 1 a derived statechart class is defined by extending SC.Statechart. The fact that the Statechart is namespaced with SC and not Ember gives a hint as to when this addon was written.
• On line 2 the monitorIsActive property can provide you with debug info if enabled. I have yet to use this facility, so it is currently set to false.
• On line 4 the substatesAreConcurrent property indicates if the state’s immediate substates are to be concurrent (orthogonal) to each other.
• On line 6 is the rootState definition, all statecharts must have a rootState or an exception is thrown. All the other states I have defined as orthogonal substates of this rootState.
• Line 7 sets the initialSubstate to the notParsing state (line 9) for when the instance is instantiated.
• Lines 9 and 17 define the two substates named notParsing and parsing. In my application the user enters a url and the application parses any lead details from the site in question. At some point the user will submit their request and the application will start parsing the results.
• Below each of these subStates are the enterState and exitState actions that in this instance are simply showing and hiding elements or in the case of the parsing substate, the execution control is also passed from the statechart to the parsing_controller.
• On line 15 is an additional action on the statechart called startParsing that can be called like this:

crawl: =>
  Lead.state_chart.sendAction 'startParsing', @url_search

• You can define these actions within states or substates and invoke them via the sendAction method and pass up to two arguments.
• On line 16 I am calling the gotoState method of the statechart that transitions between states and invokes the exitState action of the current state and enterState of the state that is being transitioned to.
• On line 28 I have a stopParsing action that when called via the gotoState method will transition back to the notParsing state and trigger the parsing state’s exitState action and the notParsing state’s enterState action. This will reset the page and let the user enter another submission.

Below is a test that helped me assert the statechart was working as expected.

Conclusion

There is a lot more to the statechart than I have mentioned here and there are some nice touches like the performAsync function that you can call when an synchronous action needs to be performed whenever entering a state or exiting a state and resumeGotoState that resumes an active goto state process that has been suspended after such an async operation. I also came across this nice routing example that you might find useful.

I am still totally undecided as to where the statechart fits in. I think it could take the place of the missing controller in Backbone as it is all to easy to overload your model or view with behaviour and things like a destroy method are still missing on the backbone view at this time of writing. On the Ember side of things where you do have controllers or even the Ember.ArrayController which is very useful, I use the statechart to ensure that the view and business logic do not communicate with each other. I think this separation of concern makes things easier to maintain and stops views, controllers or models from becoming bloated.

I think the statemachine paradigm is a very nice addition to the current Javascript MV* patterns that are out there. When you are dealing with MVC on the server, it is not real MVC. Real MVC is when a model can notify (through the observer pattern) the views about its changes. Ember facilitates this beautifully through its bindings. On the server, the controller simply passes the model data to the views that handle the HTML generation which is sent to the browser. Websockets could potentially change this but their adoption is not quite wide spread yet. On the clientside we get real MVC and things like an entryState action and exitState action fit beautifully as a way to transition or rearranging your page in response to user interaction.

I am not sure if I am advocating MVCS but I really recommend you take a look at this piece of kit because it is definitely food for thought.

Please feel free to comment on anything below.

I have been using Backbone.js for a few months now and I have found the learning curve to be a steep one. As is the case with any flexible framework, there are a number of ways of doing anything in Backbone.js and I think the framework could do with some tightening up to stop users having to roll their own custom implementations for common scenarios such as disposing of views.

For those that have been sleeping under a rock recently, Backbone.js is a client side MVC framework that should not require any introduction. The client side MVC framework seems to be a bit of a du jour thing at the moment but I think it is important to have some sort of organisational structure around JavaScript or the looseness of the language can quickly turn any javascript code into the now infamous ball of mud. Backbone.js is one way of achieving such a conformity.

The point of this post is to solidify where my current thinking is with Backbone.js and to welcome any comments from my readership of 10 or so readers that might point me to a better and brighter land. I must also warn you that I will be using coffeescript for the code examples instead of pure javascript and if this offends, please read no further.

Scenario

The scenario I want to illustrate is a simple one, I want to show how I transition from the state outlined below were a user selects from a list of what are called in the application context, business units: To a more detailed report illustrated in the image below: The user can go back and forward between these views and drill down into further views of the information but I want to concentrate on this simple scenario outlined above in the two screenshots.

Gotcha 1 - Don’t Have Views That Reference Each Other a.k.a. Coupling

In the scenario I have listed, I need some way to gather the user’s checkbox selection and pass these values to another view that renders the table and chart of results. My first few attempts at this in other applications was to let one of the views hold a reference to another and pass the information that way. An example of this type of naive implementation might look something like this:

You can see on lines 12 and 14 that I am creating a new view and calling render on it directly as a reference. This felt very wrong as there is now a coupling between the views. Thankfully somebody on twitter kindly pointed me in the direction of this post from Derek Bailey who is a wealth of information on Backbone.js.

The post outlines an alternative to creating and coupling one view in another like in the example above with the ManagementReportView. We instead create a central object that manages the raising of events and the subscribers for those events. Martin Fowler calls this the Event Aggregator pattern. This serves the purpose of decoupling the views from each other. The entire listing of the event aggregator is on line 3 of the following gist:

We are taking advantage of the way Backbone already handles events. The Backbone Events object is a module that can be mixed in with any object, giving the object the ability to bind and trigger custom named events. On lines 4 and 5, we are making sure that any of the views that want to publish or subscribe to events have a reference to the vent object. With this in place, I can simply raise an event from the BusinessUnitView and pass the newly created collection as an event argument. Below is the BusinessUnitView refactored to take advantage of the event aggregator:

The first addition is on line 3 where the view obtains a reference to our extended Backbone.js Events object and on line 20 where the custom Events object is used to trigger a custom event that is uniquely identified by a string. We are using the convention of a colon separated string (reportingbusinessunitview:load) to namespace the events and avoid collisions. Below is the code listing for the ManagementReportView that subscribes to the event listed above:

On line 3 of the above gist, we are using the bind method of the Events object to specify a callback that will be triggered when the event is raised and any optional arguments can be passed to the callback which in this instance is the newly created businessunits backbone collection that we created from the user input in the previous view. On line 7 we define the callback event handler. The load callback on line 7 is declared using the fat arrow => syntax. Coffeescript will take care of binding methods to this if you declare a function using the fat arrow => instead of the skinny one ->. This means you don’t need to use the underscore _.bindAll method as I would in javascript which can be quite tedious and relies on your diligence. One of the many reasons why you should be using coffeescript. On line 8 of the load callback we are setting the view’s collections reference to the argument raised from the triggered event and line 9 brings us to our next gotcha:

Gotcha 2 - Handle Backbone Model Events and not DOM Events Wherever Possible

Part of my reason for warming to backbone is that it brings conformity and organisation to my JavaScript/Coffeescript. It is all too easy for traditional browser based javascript to descend into a sea of DOM event handlers. Wherever possible, I have my views respond to backbone model or collection events. On line 9 of the above gist, I am adding an event handler to the reset event which is fired whenever a backbone collection is replaced with a bulk insert. On line 10 we are calling the built in fetch method of the backbone collection to retrieve the data from the remote server. When the data returns successfully from the remote server, the reset event is fired and we have bound the render event as a callback to this event on line 16. You can subscribe to events that are fired whenever elements are added or removed from a collection or when an individual model’s attributes change and you should get accustomed to all of these behaviours. Retrieving the data from the remote server brings me to gotcha 3 and in effect the render method:

Gotcha 3 - SRP - Keep Your Views Skinny

It is all to easy to end up with bloated views that do way to much and my first few attempts at backbone suffered from this. I’ve seen code that make calls to the remote server in the view and this is wrong. Let the collection/model do the remote call and subscribe to an appropriate backbone collection/model event. Below is the listing of the BusinessUnits object:

As this is javascript (coffeescript really) we can override any of the built in backbone collection methods like I am doing with the url method on line 6 but you can if required override fetch or parse methods for tighter control.

It is worth noting that the render method creates further subviews to attach to the parent view’s element. When refactoring backbone code, you tend to split your views up into finer detail or subviews to further inforce SRP.

The inner workings of the render method brings me to my last and most troublesome gotcha.

Gotcha 4 - Kill All Your Zombies…..Dead

I cannot take the credit for the excellent zombie analogy or in fact any of the revelations in this post, this again goes to Derek Bailey and a combination of this post and this Stackoverflow question and answer session. I have combined the contents of the above 2 links into how I now handle this common scenario.

If we refer back to the screenshot I showed at the start: I want to render a subview for every row in the above screenshot that has a cross or a tick image in the table columns. The gotcha outlined here is that I need to dispose of these views whenever the Back button on the top right is clicked. If I don’t dispose of the subviews, new and additional subviews will be added every time the user transitions to this view with a new collection selection. Multiple event handlers and general round chaos will occur and I have been there and it can be distressing to the uninitiated. There will be a number of views that are not attached to any element floating about in memory which gives them their zombie status.

Let us take a look again at the render method:

render: =>
  self = @

  @collection.each (item, counter) ->
    self.renderView(self.el, 'append', new ReportBusinessUnitView(model: item, vent: self.vent))

Here we are simply iterating over our collection and appending onto this view’s element a new subview for each element of the collection. We are actually calling a method named renderView of our own BaseView class that extends the Backbone.View class. More on that later but for completeness, below is the ReportBusinessUnitView class:

I’ve also found underscore’s templating to be much faster than JQuery’s templating engine which I initially started out using. Below is the underscore template:

The code will take care of iterating over our collection and attaching the subviews to our parent view. But if the user pressed back and then chose another selection and transitioned to this view again, we would add further subviews to this parent view. We need some way of keeping track of and disposing of our subviews.

To get round this problem, we have defined our own base class that uses underscore’s extend method to mixin additional functionality with that of the Backbone.Collection class by adding custom methods onto the Backbone.Collections prototype.

On line 7, we are defining a method named renderView which takes a jquery wrapped DOM element, a string denoting a function of the JQuery object to call and a backbone view. On line 8, we use javascript’s ability to reference and call a method on an object like accessing a hashtable. This string will generally be something like ‘append’ or a means of attaching the subview to the DOM. On line 9 we intialise an array to hold the subviews if it has not already been initailised using coffeescript’s ruby like ||= operator. Finally we push the newly created view onto the array.

We call the method like this:

@collection.each (item, counter) ->
    self.renderView(self.el, 'append', new ReportBusinessUnitView(model: item, vent: self.vent))

We pass the view’s element, the string ‘append’ which will be called on the jquery object in the renderView method like this $.fn[func].call and the subview we want attached. This is very neat and I can take absolutely no credit for writing it. We now have a store of all the views that are added.

All that remains is a means of disposing of these views and below are the two methods that take care of this on our custom BaseView class:

We can either call dispose on line 8 that will remove all subviews and the view itself or disposeViews on line 14 that will only remove the subviews. Dispose takes care of not only unbinding any event handlers but also of removing the element from the DOM. We can simply call one of these methods in an appropriate place on the view like this:

@disposeViews()

This has made backbone much more manageable although I cannot claim credit for much of the code.

That is it for this post and I will be amazed if anyone has made it this far. Please feel free to leave any comments. Below is the full listing of the BaseView class:

Previous Posts

• Part 1
• Part 2
• Part 3: Creating Gradients With Compass

I have been using these posts to cement the knowledge I am gleaning while transforming the markup for a product I am building. I find that trying to transmit the knowledge via blogging is the only way to really learn something or else it is easily forgotten. In the last three posts I have gone from defining my project file structure to creating the markup and CSS3 (with the extreme help of sass) for the header element in the image below. In this post, I want to outline the steps I took to create the following login page:

In the past, I hate to admit that I would have used a table to align the inputs with their labels but this time round I want to use css to control the layout. With that said, below is the haml that generates the markup for the above login form:

The above haml generates the following markup:

The only points of interest in the above markup are the new HTML5 attributes that are attached to the input elements on lines 8 and 10 of the above gist. These attributes are:

• The required attribute which as you might have correctly deduced is used to specify that the element requires user input. Some browsers will alter the default appearance of required elements with a red border for example and most should stop you submitting the form if the mandatory field is left blank. It is worth remembering that this is HTML5, things can and will change until ratification.
• The placeholder attribute which if set will place default text in an input field if the input element is empty or not in focus.

With the markup out of the way, we can now concentrate on some of the new CSS3 bells and whistles that I have used via sass and compass to create some of the nice effects in the form.

First of all, I want to concentrate on the login form itself: Below is the sass that is used to create the sunken effect for the text of the header and label elements that are outlined in the above image.

On line 1, is the definition of a mixin that I have used to avoid duplication in the two css selectors that assign styles to the <h2> and <label> elements. The mixin is used on lines 6 and 12 via the @include directive.
On line 3 of the above gist, I am using the new css3 text-shadow property that does what it says on the tin and adds a shadow effect to the text of a block element to make it stand out more.

It is worth noting that I keep all my colour variable definitions in a separate sass partial file named _colors.sass. This allows me to change the colour scheme in one file and not have to jump around the project files looking for the definitions. Below is an excerpt from colors.sass that shows the variable declarations used in the above gist:

$label-color: #445668
$label-box-shadow: #f2f2f2

The form element of the log in page uses a few of the new css3 techniques to add the new and now infamous css3 border-radius property that gives the form the nice rounded corners effect. It is often jokingly stated that the main purpose of CSS3 is to facilitate the adding of rounded corners to block elements.

But first of all, I want to show how I got this rippled effect on the bottom of the form: I have used the new css3 box-shadow property to achieve this effect. As the name suggests, the box-shadow property is used to apply an inset or drop shadow to a block element. It is also possible to add multiple box-shadows to an element as in this example. As this is a css3 experimental property there are the usual vendor specific prefixes for this property….that is unless you use compass and you can use the box-shadow mixin like I am below:

#new_user_session
  @include box-shadow($login-box-shadow-color 0 0 2px, $login-box-shadow-color 0 1px 1px, #fff 0 3px 0, $login-box-shadow-color 0 4px 0, #fff 0 6px 0, $login-box-shadow-color 0 7px 0)

I am passing in alternating box-shadow colour definitions to the mixin that are delimited by commas to give the appearance of a ripple. The above sass generates the following css:

#new_user_session {
  -moz-box-shadow: rgba(0, 0, 0, 0.2) 0 0 2px, rgba(0, 0, 0, 0.2) 0 1px 1px, white 0 3px 0, rgba(0, 0, 0, 0.2) 0 4px 0, white 0 6px 0, rgba(0, 0, 0, 0.2) 0 7px 0;
  -webkit-box-shadow: rgba(0, 0, 0, 0.2) 0 0 2px, rgba(0, 0, 0, 0.2) 0 1px 1px, white 0 3px 0, rgba(0, 0, 0, 0.2) 0 4px 0, white 0 6px 0, rgba(0, 0, 0, 0.2) 0 7px 0;
  -o-box-shadow: rgba(0, 0, 0, 0.2) 0 0 2px, rgba(0, 0, 0, 0.2) 0 1px 1px, white 0 3px 0, rgba(0, 0, 0, 0.2) 0 4px 0, white 0 6px 0, rgba(0, 0, 0, 0.2) 0 7px 0;
  box-shadow: rgba(0, 0, 0, 0.2) 0 0 2px, rgba(0, 0, 0, 0.2) 0 1px 1px, white 0 3px 0, rgba(0, 0, 0, 0.2) 0 4px 0, white 0 6px 0, rgba(0, 0, 0, 0.2) 0 7px 0;
}

The above css creates the rippled effect.

Now let us get back to those nice rounded corners that are this season’s black in the fashionable world of css3: The css3 border-radius property is used to give a block element rounded corners and as we cannot be bothered to type all these vendor specific prefixed properties, we are going to use the compass border-radius mixin. Below is the border-radius mixin applied to the login form element:

#new_user_session
  @include border-radius(10px)

Which generates the following css:

#new_user_session{
-moz-border-radius: 10px;
-webkit-border-radius: 10px;
-o-border-radius: 10px;
-ms-border-radius: 10px;
-khtml-border-radius: 10px;
border-radius: 10px;
}

As you can see, compass takes care of the vendor specific pain.

Below is the sass in its entirety that is employed to create the css styling effects of the form minus the inputs.

The only point that I have not covered is the gradient effect that is created using the compass border mixin on line 6 of the above gist. I described linear gradients in the previous post.

Input Styling

I have used a combination of all the techniques mentioned so far to add some definition to the input elements: Below is the sass that is used to create the box-shadow, linear-gradient and border radius effects:

CSS3 Transitions

With CSS3 you can now achieve some effects that would have in the past required javascript to achieve. One of these techniques is known as a css3 transition. This allows the author to specify a css change or transition from one css style to another. It is also possible to put a time delay on the transition.

This is impossible to show without a demo and as my site is not on a public facing server yet, so I am going to have to point to these examples.

In my log in page, I am specifying that I want the text input’s border and background to change when the cursor is hovered over the input control: We can also put a delay on the transition which equates to a tasteful delay of a specified time before the transition occurs.

Below is the sass I have used to create this nice time delayed transition:

I am using the compass transition-property and transition-duration mixins to produce this effect. The compass documentation for the transition mixins can be found here.

Button Effect

Lastly I want to describe how the styling was created for the button: I have used the fancy-buttons library to easily create this effect.

With the library imported, I can simply use the fancy-button mixin to generate the css3 styles like this:

input[type=submit]
  @include fancy-button(#617798, 14px, 1em, 4px)
  width: auto
  text-transform: uppercase

I will leave things here for this article, if you made it to the end of the article then pat yourself on the back!

Previous Posts

• Part 1
• Part 2

In the previous two posts, I have started to outline the transition of my yet to be completed product from old school xhtml, css and javascript into the new world of HTML5 and CSS3. As the product is not even on the market yet, I am taking the bold step of tackling the design myself. I am a css and design heretic so this is quite a difficult step for me. On the plus side, I will learn a lot on the way no matter what the outcome is. In this article, I want to touch on creating gradients with sass and compass.

A gradient in the context of css is a gradual transition between two colours. This transition can be transformed through a vertical axis or a horizontal axis. Below is how my application looks after I have applied the styles that I will create in this article.
I have applied gradients to both the header section and the navigation bar of the html document. CSS3 comes with a gradient property and most of the modern browsers have their own prefixed slants on this property. As we are using compass and sass, we can forget about the need to create these vendor specific duplicated linear-gradient properties. Yet another reason for using compass is that compass will output the vendor specific cross browser rules. The latest version of compass has the excellent images module and I am going to take advantage of the background-image mixin to create the gradient effect. Below is the rule that will be applied to the new html5 <header> element of our document:

body > header
  background-color: $header-bg
  @include background-image(image-url('noise.png'), linear-gradient(darken($header-bg, 20), $header-bg, lighten($header-bg, 11)))

I am using the background-image mixin to generate the linear-gradient as recommended in the latest compass docs changelog which states:

The linear-gradient and radial-gradient mixins have been deprecated. Instead use the background-image mixin and pass it a gradient function. The deprecation warning will print out the correct call for you to use.

We are also passing in a fallback image if the browser does not support linear-gradient.

For IE6 and IE7 there is the filter-gradient mixin. I will probably create an IE < 8 conditional stylesheet and try this out at a later stage.

It is also worth noting that we are taking advantage of the sass functions lighten and darken to avoid having multiple colour hex values to change. The above background-image mixin will generate the following css:

/* line 1, /Users/paulcowan/projects/leadcapturer/app/assets/stylesheets/partials/_header.sass */
body > header {
  background-color: #6a85af;
  background-image: url(/assets/noise.png), -webkit-gradient(linear, 50% 0%, 50% 100%, color-stop(0%, #acbbd3), color-stop(50%, #6a85af), color-stop(100%, #4f6992));
  background-image: url(/assets/noise.png), -webkit-linear-gradient(#acbbd3, #6a85af, #4f6992);
  background-image: url(/assets/noise.png), -moz-linear-gradient(#acbbd3, #6a85af, #4f6992);
  background-image: url(/assets/noise.png), -o-linear-gradient(#acbbd3, #6a85af, #4f6992);
  background-image: url(/assets/noise.png), -ms-linear-gradient(#acbbd3, #6a85af, #4f6992);
  background-image: url(/assets/noise.png), linear-gradient(#acbbd3, #6a85af, #4f6992);
}

I hope you can see the projection of one line of vendor independent compass/sass code to the many lines of browser/vendor specific css code.

Navigation Bar

We will use the same technique to apply a gradient to the navigation bar: We are going to use the new semantic <nav> element of html5 to mark up the navigation and then apply css rules to it. Below is the haml for the new navigation bar:

And here is the rendered output of the above haml

<nav role="navigation">
    <ul role="user">
      <li>
        <a href="/logout">log Out</a>
      </li>
    </ul>
    <ul role="main-navigation">
      <li>
        <a href="/Home/Index" data-method="get">Capture</a>
      </li>
      <li>
        <a href="/Archive/Index" data-method="get">Archives</a>
      </li>
    </ul>
</nav>

I am also using the new html5 semantic role attribute. HTML5 has many of these new semantic markers that help devices such as screen readers pick out the relevant sections.

I want to take this opportunity to show the power of both sass variables and the extremely useful sass functions desaturate, darken and lighten to DRY up your css. Below are the variable declarations we will be using for the navigation bar:

Only on line 1 do we actually specify any hex value for a variable, in the subsequent variable declarations, we pass in relevant percentage values to the lighten and darken functions to keep everything in ratio. A change to the $nav-bg variable will cause the other variables to adjust accordingly.

A full list of similar sass colour functions can be found here.

Below is the listing for the _navigation.sass partial file that contains the rules for the <nav> tag outlined above:

Besides the background-image mixin on line 4 that I described previously, we are taking advantage of a couple of other useful sass mixins:

• Horizontal List (line 11): which transforms a <ul> list horizontally.
• link-colors (line 20): Which sets the colors for a link in one mixin.

I will leave things here for this post but in the next post I will describe the layout I am going to use for the main section of the page. I had previously used the compass blueprint library which is a css grid layout framework but the world has moved on and I am going to see what else is available. If anyone can recommend a more modern approach please leave a comment below.

Please leave any comments below. Feedback is always appreciated.

Previous Posts

• Part 1

In the last post I took a walk through the basic set up of my sass files that I will be using for the update of my site to the new landscape of html5.

Below is the file layout for my sass files: I went on to mention that the application.css.sass file above is used as a manifest and I just use it to point to my application point of entry screen.sass.

application.css.sass looks like this:

@import "screen"

screen.sass currently looks like this:

In the last post, I explained how the reset mixins in lines 2 and 3 provide a facility for removing browser inconsistencies by a mechanism known as css reset rules. I now want to explain the contents of the other files that are imported via the sass @import directive.

SASS Partials

All the files that are imported on lines 5 to 12 of screen.sass are sass partials. Any sass file that is imported as part of a parent or main css file and does not need its own individual css file is what is known as a partial. A sass partial file does not make sense on its own. In this example, screen.sass will generate one css file that is made up of seven partials. This is very analgous to rails partials or any partial in any mvc framework. The convention for a sass partial is to begin the filename with a _ character. If you refer to the opening image, each file in the partials directory begins with an underscore. This tells sass not to generate an individual css file for the partial and only use it for imports. To confuse matters, you drop both the _ and the file extension in the @import statement.

The first import statement on line 5 imports a currently empty file named _utilities.sass. This file will be used for housing any reusable mixins or sass functions that we create on our journey to market. Next up we have the partial _colors.sass.

SASS Variables

_colors.sass currently looks like this:

The point of _colors.sass is to have a central location were we can adjust the colour scheme of the website. The explicit colour values that will be referenced in other sass files for things like background colours etc. are stored in what are known as sass variables.

One of the glaring misses in CSS is the ability to store reusable values in variables. This can lead you to having to use potentially faulty search and replace techniques in your text editor to swap hex code values and manage colour palette changes in your stylesheets. With sass you can assign values to variables, and manage colours, border sizes etc. in a single location.

SASS variables start with the $ character and can contain any character that is valid in a CSS class name. In line 1 of _colors.sass, I am storing the hex value of the colour that I will use for the header section of my page. As colors.sass is imported in screen.sass, the variables that are declared in _colors.sass will be available in any partials that are imported in screen.sass. Below is an example of how the sass variable can be used:

body > header
  background: $header-bg

Line 3 of _colors.sass contains the following variable declaration:

$subtitle-color: lighten($header-bg, 58)

The return value of the lighten function that is outlined above is used to assign the value of the $subtitle-color variable and is one of the many utility functions that are included in SASS. The lighten function unsurprisingly lightens the colour by a percentage value. In the above example, we can tie the $subtitle-color variable to the $header-bg variable so they will always be in ratio. A quick look at the sass docs will broaden your knowledge of what sass functions are available.

Before carrying on, below is the rendered HTML from our main application.html.haml file which we will be applying css rules to:

Typography

The next sass partial file that we are importing from the parent screen.sass is the _typography.sass file, which currently looks like this:

This file as the file name suggests is where all the type face instructions will be centrally held. On line 1 of _typography.sass, we are declaring a css class with a name of heading and then declaring the font-family we want to use and the fall back options. It is unlikely you will have heard of the Orbitron font-family and that is because we are importing it from the Google Web Fonts API. I mentioned this in the previous post. We can import fonts from the google web fonts api by declaring a separate <link> element for each font we want to import. The declaration for importing the Orbitron font is below:

%link{:rel => "stylesheet", :type => "text/css", :href => "http://fonts.googleapis.com/css?family=Orbitron:regular,italic,bold,bolditalic"}

On line 4 of the typography.sass file, we are using the css selector body > header h1 to select the first h1 element of the new html5 header element. On line 7 of _typography.sass, @extend is used to tell sass that we want the body > header h1 selector to inherit all the styles defined in another selector. This is worth the sass price of admission alone. The ability to DRY up your css by inheriting other selector rules reduces repeating yourself tenfold. This is one of the many reasons why sass will (not should) become the new css.

In line 11 of _typography.sass we come across the first use of what is arguably sass’s most important feature which is known as a sass mixin. A mixin as the name suggests, mixes in rules into other rules. We extract the rules using the @mixin directive. For example we could create a mixin defined like below:

@mixin BigText
  font-size: 20px
  font-weight: bold
  text-transform: uppercase

We can mixin these rules into other rules using the @include directive.

body > header h1
  @include BigText

It is also possible to pass arguments to mixins just as is outlined in line 11 of typography where we are mixing in the rules of the compass Text-Shadow mixin. This mixin will create the rules for the new css3 text shadow property. The CSS3 text-shadow property has been around for some time now and is commonly used to recreate Photoshop’s Drop Shadow type shading to add subtle shadows which help add depth, dimension and to lift an element from the page.

@include text-shadow(rgba(#000, 0.8) 0 0 8px)

Below is a screenshot of what the some total of our css styling looks so far: I think you will agree that this looks pretty ugly but as we continue, I will progressively make it look better: As you can see, I am not a designer but this looks reasonable enough to me but probably less so to others. Ok, back to sass…

On line 18 of _typography.sass, we come across the strange syntax of #{headings()}. This helper function is part of the compass library. This helper function will emit all the h[n] headings for you. Below is the css that is rendered from this function:

.heading, body > header h1, h1, h2, h3, h4, h5, h6 {
  font-family: "Orbitron", "Georgia", "Helvetica Neue", Arial, San-Serif;
}

I am going to leave things here for now but in the next post I will outline some other cool sass techniques such as gradients.

Please feel free to leave comments below.

I have been working on this as a side project for some time now and I have decided to take a deep dive into what is available in HTML5 and CSS3 and update the front end code. This yet to be birthed product is written in JRuby and is a rails application. I have recently been through the pain of upgrading to Rails 3.1 in order to take advantage of the dazzlingly new, shinny and controversial Rails 3.1 asset pipeline. I have been using sass and compass for some time and I had previously used the compass blueprint library for layout and utilities. This feels a bit dated now so it is high time to refresh. I have previously blogged about sass, compass and blueprint here.

I am trying to avoid dissolving into deep depressive rants about things and I could go off on one about the Rails 3.1 abstraction levels reaching their natural meltdown limits with this Rails release. It is not quite .NET webforms but it is certainly heading in that direction.

Markup Refresh

I am going to take this site refresh one blog post at a time. I want to be sure I remember my transitions.

The head is the only sensible place to start in HTML so here is my new header code which is written in your favourite mark up language and mine HAML:

The above is my main rails layout file. The following are the main points of interest:

• In HAML the HTML declaration is a two pronged approach. You first of all place the doctype marker !!! in the .html.haml file:

!!!
 %head

Secondly, you need to tell HAML the output format on application start up which is specified in the main rails environment.rb file.

Haml::Template.options[:format] = :html5

With these options set, we can pass the rendering of the correct !DOCTYPE instruction to the HAML runtime. This generates the following HTML declaration:

<!DOCTYPE html>

• On lines 3 and 5 of the gist, we are declaring the single application javascript and css declarations that are generated from the Rails 3.1 asset pipeline.

• On lines 8 - 11 we are going to take advantage of the Google Web Fonts API and CSS3 to embed some nice looking fonts in the application. There is a separate declaration and import for each web font that the application will make use of. More on this in later posts.

• On line 13 we encounter our first new HTML5 tag, the header element. The semantic header tag specifies an introduction, or a group of navigation elements for the document.

• On line 14, the hgroup tag is used to group the document’s title and associated subtitles. The hgroup tag can only contain a group of h1 to h6 elements.

Below is the beautifully indented output of the HAML markup:

SASS Folder Structure

When I first started using SASS there was nowhere near the level of docs and blog posts available to the end user. As part of this site refresh, I took a look on github at some of the open source projects using SASS to find guidance on how some of the SASS officionados, use SASS.

It is also worth mentioning before proceeding that I use the possibly now old school and pythonesque sass syntax and not the more css like scss syntax. When I started with sass there was no scss syntax but to be honest, I think .scss was introduced to make sass more designer friendly. As a developer, I feel more at home with whitespace delimiting my blocks rather than the now horribly out of fashion curly braces.

The screenshot below outlines a popular file organisation pattern for structuring your SASS files:

The first point of entry is the application.css.sass file. Back in what are probably now classified as the old days, a separate process running the compass.exe would watch the sass directory for changes to your sass files. Any changes were compiled into your ~/public folder. With rails 3.1, we’re getting css and javascript served up through application.css and application.js. These main application files are really just manifest files that bundle everything in the stylesheets or javascripts folder into one file.

First Rails 3.1 SASS Gotcha

Out of the box, the application.css.sass file looks something like this:

/*
 * This is a manifest file that'll automatically include all the stylesheets available in this directory
 * and any sub-directories. You're free to add application-wide styles to this file and they'll appear at
 * the top of the compiled file, but it's generally better to create a new file per style scope.
 *= require_self
 *= require_tree . 
*/

The requite_tree statement above tells the system to bundle everything in the stylesheets folder into a single file via the magic of sprockets.

When I first started using this approach in Rails 3.1, I quickly found out that sass variables or indeed sass scopes were not shared across files. This is because application.css.sass is really for combining plain css files into one via the magic of sprockets. With sass files, you need to use the @import directive in the application.css.sass file to import additional sass files. If you are using application.css.scss with require_tree, the runtime will still compile your sass and combine the resultant css into one file but there will be no shared scopes for things like variables, mixins etc. It took me a while to figure that one out. Remember I mentioned the raised abstraction levels in Rails 3.1?

With that in mind, my application.css.sass file looks like this:

@import "screen"

The application.css.sass file is now just a pointer to the main application logic file, screen.sass.

At this time of writing, my screen.sass file currently looks like this:

On line 1 we are using the @import directive to import the compass library into our code. Using sass without compass is a complete waste of an incredible resource, compass has a wealth of useful features that are hard to ignore. If you are not using compass with sass, you might as well be using the less framework. Compass has a multitude of mixins, functions and other utilities that make css all of a sudden fun to a css heretic like me.

Lines 2 and 3 of screen.sass bring the output or generated styles of two of these compass mixins into the rendered application.css output via the sass @include directive. The @include directive takes the name of a mixin and optionally arguments to pass to it, and includes the styles defined by the mixin into the current rule. The following link has some examples that illustrate how they can be used.

Both these mixins generate what are known as css reset rules. Reset stylesheets try to reduce browser inconsistencies in things like default line heights, paddings, margins and font sizes. The goal of the reset stylesheet is to give you a completely style free starting point. For example some browsers indent unordered lists, others do not. The reset rules level the playing field and gives you a neutral cross browser starting point to add your own.

The first mixin, the global-reset mixin is based on Eric Myer’s 2.0 global reset rules.

The second mixin, the reset-html5 mixin, provides a basic set of HTML5 elements so they are rendered correctly in browsers that do not recognise them and reset in browsers that have default styles for them.

Below is the css that is produced from these mixins:

I think I prefer the 2 lines of sass code to the output above. There are a number of compass reset mixins that can be utilised in your code.

I think I will leave things here, in the next post I will reveal what is inside the other files in the above screen.sass file.

If you are a web developer and you are not using sass/compass, I have to ask the question….why?