Leanpub: Publish Early, Publish Often

Backend Integration with Ruby on Rails

In this chapter we will have a look into solving common problems when combining Angular.js with the Ruby on Rails frameworks. The examples used in this chapter are based on an example application to manage a list of contacts.

Consuming REST APIs

Problem

You wish to consume a JSON REST API implemented in your Rails application.

Solution

Using the $resource service is a great start and can be tweaked to feel more natural to a Rails developer by configuring the methods in accordance with the Rails actions.

app.factory("Contact", function($resource) {
 return $resource("/api/contacts/:id", { id: "@id" },
   {
     'create':  { method: 'POST' },
     'index':   { method: 'GET', isArray: true },
     'show':    { method: 'GET', isArray: false },
     'update':  { method: 'PUT' },
     'destroy': { method: 'DELETE' }
   }
 );
});

We can now fetch a list of contacts using Contact.index() and a single contact with Contact.show(id). These actions can be directly mapped to the ContactsController actions in your Rails backend.

class ContactsController < ApplicationController
 respond_to :json

 def index
   @contacts = Contact.all
   respond_with @contacts
 end

 def show
   @contact = Contact.find(params[:id])
   respond_with @contact
 end

 ...
end

The Rails action controller uses a Contact ActiveRecord model with the usual contact attributes like firstname, lastname, age, etc. By specifying respond_to :json the controller only responds to the JSON resource format and we can use respond_with to automatically transform the Contact model to a JSON response.

The route definition uses the Rails default resource routing and an api scope to separate the API requests from other requests.

Contacts::Application.routes.draw do
 scope "api" do
   resources :contacts
 end
end

This will generate paths like for example api/contacts and api/contacts/:id for the HTTP GET method.

You can find the complete example on github.

Discussion

If you want to get up to speed with Ruby on Rails, I suggest that you look into the Rails Guides which will help you understand how all the pieces fit together.

Rails Security using Authenticity Token

The example code above works nicely until we use the HTTP methods POST, PUT and DELETE with the resource. As a security mechanism, Rails expects an authenticity token to prevent a CSRF (Cross Site Request Forgery) attack. We need to submit an additional HTTP header X-CSRF-Token with the token. It is conveniently rendered in the HTML meta tag csrf-token by Rails. Using jQuery we can fetch that meta tag definition and configure the $httpProvider appropriately.

var app = angular.module("Contacts", ["ngResource"]);
app.config(function($httpProvider) {
 $httpProvider.defaults.headers.common['X-CSRF-Token'] =
   $('meta[name=csrf-token]').attr('content');
});

Rails JSON response format

If you are using a Rails version prior 3.1, you’ll notice that the JSON response will use a contact namespace for the model attributes which breaks your Angular.js code. To disable this behavior you can configure your Rails app accordingly.

1 ActiveRecord::Base.include_root_in_json = false

There are still inconsistencies between the Ruby and Javascript world. For example, in Ruby we use underscored attribute names (display_name) whereas in Javascript we use camelCase (displayName).

There is a custom $resource implementation angularjs-rails-resource available to streamline consuming Rails resources. It uses transformers and inceptors to rename the attribute fields and handles the root wrapping behavior for you.

Implementing Client-Side Routing

Problem

You wish to use client-side routing in conjunction with a Ruby on Rails backend.

Solution

Every request to the backend should initially render the complete page in order to load our Angular app. Only then will the client-side rendering take over. Let us first have a look at the route definition for this “catch all” route.

Contacts::Application.routes.draw do
 root :to => "layouts#index"
 match "*path" => "layouts#index"
end

It uses Route Globbing to match all URLs and defines a root URL. Both will be handled by a layout controller with the sole purpose of rendering the initial layout.

class LayoutsController < ApplicationController
 def index
   render "layouts/application"
 end
end

The actual layout template defines our ng-view directive and resides in app/views/layouts/application.html - nothing new here. So let’s skip ahead to the Angular route definition in app.js.erb.

var app = angular.module("Contacts", ["ngResource"]);

app.config(function($routeProvider, $locationProvider) {
 $locationProvider.html5Mode(true);
 $routeProvider
   .when("/contacts",
     { templateUrl: "<%= asset_path('contacts/index.html') %> ",
       controller: "ContactsIndexCtrl" })
   .when("/contacts/new",
     { templateUrl: "<%= asset_path('contacts/edit.html') %> ",
       controller: "ContactsEditCtrl" })
   .when("/contacts/:id",
     { templateUrl: "<%= asset_path('contacts/show.html') %> ",
       controller: "ContactsShowCtrl" })
   .when("/contacts/:id/edit",
     { templateUrl: "<%= asset_path('contacts/edit.html') %> ",
       controller: "ContactsEditCtrl" })
   .otherwise({ redirectTo: "/contacts" });
});

We set the $locationProvider to use the HTML5 mode and define our client-side routes for listing, showing, editing and creating new contacts.

You can find the complete example on github.

Discussion

Let us have a look into the route definition again. First of all the filename ends with erb, since it uses ERB tags in the javascript file, courtesy of the Rails Asset Pipeline. The asset_path method is used to retrieve the URL to the HTML partials since it will change depending on the environment. On production the filename contains an MD5 checksum and the actual ERB output will change from /assets/contacts/index.html to /assets/contacts/index-7ce113b9081a20d93a4a86e1aacce05f.html. If your Rails app is configured to use an asset host, the path will in fact be absolute.

Validating Forms Server-Side

Problem

You wish to validate forms using a server-side REST API provided by Rails.

Solution

Rails already provides model validation support out of the box for us. Let us start with the Contact ActiveRecord model.

class Contact < ActiveRecord::Base
 attr_accessible :age, :firstname, :lastname

 validates :age, :numericality => {
   :only_integer => true, :less_than_or_equal_to => 50 }
end

It defines a validation on the age attribute. It must be an integer and less or equal to 50 years.

In the ContactsController we can use that to make sure the REST API returns proper error messages. As an example let us look into the create action.

class ContactsController < ApplicationController
 respond_to :json

 def create
   @contact = Contact.new(params[:contact])
   if @contact.save
     render json: @contact, status: :created, location: @contact
   else
     render json: @contact.errors, status: :unprocessable_entity
   end
 end

end

On success it will render the contact model using a JSON presentation and on failure it will return all validation errors transformed to JSON. Let us have a look at an example JSON response:

1 { "age": ["must be less than or equal to 50"] }

It is a hash with an entry for each attribute with validation errors. The value is an array of Strings since there might be multiple errors at the same time.

Let us move on to the client-side of our application. The Angular.js contact $resource calls the create function and passes the failure callback function.

Contact.create($scope.contact, success, failure);

function failure(response) {
 _.each(response.data, function(errors, key) {
   _.each(errors, function(e) {
     $scope.form[key].$dirty = true;
     $scope.form[key].$setValidity(e, false);
   });
 });
}

Note that ActiveRecord attributes can have multiple validations defined. That is why the failure function iterates through each validation entry and each error and uses $setValidity and $dirty to mark the form fields as invalid.

Now we are ready to show some feedback to our users using the same approach discussed already in the forms chapter.

<div class="control-group" ng-class="errorClass('age')">
 <label class="control-label" for="age">Age</label>
 <div class="controls">
   <input ng-model="contact.age" type="text" name="age"
     placeholder="Age" required>
   <span class="help-block"
     ng-show="form.age.$invalid && form.age.$dirty">
     {{errorMessage('age')}}
   </span>
 </div>
</div>

The errorClass function adds the error CSS class if the form field is invalid and dirty. This will render the label, input field and the help block with a red color.

$scope.errorClass = function(name) {
 var s = $scope.form[name];
 return s.$invalid && s.$dirty ? "error" : "";
};

The errorMessage will print a more detailed error message and is defined in the same controller.

$scope.errorMessage = function(name) {
 result = [];
 _.each($scope.form[name].$error, function(key, value) {
   result.push(value);
 });
 return result.join(", ");
};

It iterates over each error message and creates a comma separated String out of it.

You can find the complete example on github.

Discussion

Finally, the errorMessage handling is of course pretty primitive. A user would expect a localized failure message instead of this technical presentation. The Rails Internationalization Guide describes how to translate validation error messages in Rails and might prove helpful to further use that in your client-side code.