ASCIIcasts - Full Episode Feed

Better SASS With Bourbon

Sun, 11 Mar 2012 21:57:22 +0000

If you’re tired of typing vendor-specific prefixes for CSS properties you should take a look at the Bourbon library which includes several SASS mixins and functions to make working with CSS more convenient. In this episode we’ll show you how to use it in a Rails application.

Adding Bourbon to a Rails Application

The application we’ll be working with is shown below. Its design needs some work so we’ll add Bourbon to the app and use some of its features to improve the way the page looks.

Installing Bourbon is easy. All we need to do is add it to the gemfile and run bundle.

/Gemfile

source 'https://rubygems.org'

gem 'rails', '3.2.2'

# Bundle edge Rails instead:
# gem 'rails', :git => 'git://github.com/rails/rails.git'

gem 'sqlite3'


# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.2.3'
  gem 'coffee-rails', '~> 3.2.1'

  # See https://github.com/sstephenson/execjs#readme for more supported runtimes
  # gem 'therubyracer'

  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'
gem 'bourbon'

To use Bourbon with Rails’ asset pipeline we’ll need to change the way that the default application.css file works. By default this file will use a Sprockets manifest to load each of the other stylesheet assets. The problem with this is that Sprockets compiles each SASS file into CSS individually which makes it difficult to share the Bourbon mixins across the SASS files. To fix this we can use SASS to load all the scss files instead of Sprockets.

We’ll need to rename our the application.css file to application.css.scss, then we can then remove the Sprockets manifest and use SASS’s @import command to pull in the files that we want to include. For now we’ll just include the bourbon file provided by the gem.

/app/assets/stylesheets/application.css.scss

@import "bourbon";

We’ll need to restart the Rails server for these changes to be picked up. After we’ve done that when we reload the page all the styling has gone.

If we look at the /assets/application.css file in the browser we’ll see that it’s blank. Bourbon doesn’t add any CSS to our application directly, it just makes it more convenient for us to add our own CSS through SASS. It’s still up to us to write all the CSS we need for our application so we’ll put the layout and project files back in application.css.scss. We set up these CSS files earlier but now we’ll be able to use Bourbon in them.

/app/assets/stylesheets/application.css.scss

@import "bourbon";
@import "layout";
@import "projects";

When we reload the page now it will bring us back to the design we had earlier.

Modifying The Header

The first improvement we’ll make to our design is to change the font. The page currently uses the browser’s default font, which is usually Times New Roman. Bourbon includes a font-family add-on which provides aeveral variables for setting the type of font. These include fallback fonts for when the first font required isn’t available. We’ll use one of these to set the body’s font.

/app/assets/stylesheets/layout.css.scss

body {
  margin: 0;
  padding: 0;
  background-color: #FFF;
  font-size: 14px;
  font-family: $verdana;
}

Next we’ll add a gradient to the header. Bourbon provides a linear-gradient module and we can use this to add a gradient and set its colours. We’ll add a gradient that fades from light grey to a darker grey. Note that we haven’t set a direction for the gradient; this means that the default value of top will be used.

/app/assets/stylesheets/layout.css.scss

#header {
  color: #FFF;
  padding: 15px 100px;
  font-size: 30px;
  font-weight: bold;
  @include linear-gradient(#777, #444);
}

A default background colour is included in linear-gradient so we’ve removed the background-color property from the header. We also want a drop shadow under the header and Bourbon provides a mixin for adding these. We can use this in a similar way to the box-shadow CSS3 property but the mixin will generate all the vendor-specific prefixes for us. We’ll add a black shadow with no offset and with a six pixel shadow with a three pixel spread.

/app/assets/stylesheets/layout.css.scss

#header {
  background-color: #555;
  color: #FFF;
  padding: 15px 100px;
  font-size: 30px;
  font-weight: bold;
  @include linear-gradient(#777, #444);
  @include box-shadow(0 0 6px 3px #000);
}

When we reload the page now these changes can be seen.

Modifying The Items

Next we’ll make some changes to the list of items. First we’ll add rounded corners to the box that surrounds each project. Needless to say Bourbon has a border-radius module to do just this. The project-specific styling is in a projects.css.scss file so we’ll make this change there and add a six pixel radius.

/app/assets/stylesheets/projects.css.scss

.project {
  border: solid 1px #AAA;
  margin: 20px 0;
  padding: 7px 12px;
  @include border-radius(6px);
  
  &:hover { background-color: #F8FCCF; }
  
  h2 {
    margin: 0;
    a { text-decoration: none; }
  }
}

Next we’ll change the way that the background colour of each item changes when we hover over it. Instead of it changing immediately we’d like it to fade in to that colour. We can use transitions to do this, passing in the attribute we want to change, the time it should take to do the change and the easing effect.

/app/assets/stylesheets/projects.css.scss

.project {
  border: solid 1px #AAA;
  margin: 20px 0;
  padding: 7px 12px;
  @include border-radius(6px);
  @include transition(all, 500ms, ease-in-out);
  
  &:hover { background-color: #F8FCCF; }
  
  h2 {
    margin: 0;
    a { text-decoration: none; }
  }
}

Now the background colour will fade in over half a second when we hover over a project and fade out over the same time when the cursor moves out.

The last change we’ll make to this page is to improve the “New Project” link. We’d like it to look more like a button instead and Bourbon includes a buttons add-on that we can use to make different styles of button. Our link has a new_project class so we’ll use that to style it and turn the link into a simple green button.

/app/assets/stylesheets/projects.css.scss

.new_project {
  @include button(simple, #3FB344); 
}

When we reload the page now we’ll see the rounded corners and the styled link. (You’ll have to take the background colour fade on trust.)

The button has inherited some attributes from the anchor tag such as the underlined text and we want it to be a little larger. We’ll add some more CSS to do this.

/app/assets/stylesheets/projects.css.scss

.new_project {
  @include button(simple, #3FB344); 
  text-decoration: none;
  font-size: 16px;
}

We now have a nice button for adding a new project.

An Example Of The CSS That Bourbon Generates

Now that the page is looking better let’s look at the CSS that Bourbon has generated. We can’t show it all here as there’s a lot of it but as an example here’s the generated CSS for the header and we can see the code for the gradient that we added.

css

#header {
  background-color: #555;
  color: #FFF;
  padding: 15px 100px;
  font-size: 30px;
  font-weight: bold;
  background-color: #777777;
  background-image: -webkit-gradient(linear, left top, left bottom, color-stop(0%, #777777), color-stop(100%, #444444));
  background-image: -webkit-linear-gradient(top, #777777, #444444);
  background-image: -moz-linear-gradient(top, #777777, #444444);
  background-image: -ms-linear-gradient(top, #777777, #444444);
  background-image: -o-linear-gradient(top, #777777, #444444);
  background-image: linear-gradient(top, #777777, #444444);
  -webkit-box-shadow: 0 0 6px 3px black;
  -moz-box-shadow: 0 0 6px 3px black;
  box-shadow: 0 0 6px 3px black;
}

There’s a lot of code here that we’ve not had to write manually thanks to Bourbon.

SASS also includes several functions that can help out with generating CSS when dealing with colour changes, variations and adjustments. There’s more information in episode 268 on what can be done with SASS alone.

Twitter Bootstrap Basics

Sun, 04 Mar 2012 17:10:27 +0000

Twitter’s Bootstrap helps you build beautiful web apps quickly. It provides a variety of CSS and JavaScript for making layouts, navigation, forms and a lot more and it even includes support for responsive web design. As an example, if you visit its homepage and alter the width of the browser window the page layout will change to best fit that width. This can really improve the experience of using web applications on mobile devices.

It’s well worth taking some time to explore the Twitter Bootstrap website to see everything that it provides but in this episode we’re going to show you how you can use it with a Rails application. One option is to download the static CSS and JavaScript by clicking on the “Download Bootstrap” button and then move the appropriate files into /app/assets directory. This isn’t the best approach if you’re using Rails, however. Twitter Bootstrap is written using LESS, which is a CSS preprocessor and which is very similar to the SASS used by Rails.

To get the most flexibility from Twitter Bootstrap it’s best to use it with a dynamic language, such as LESS, instead of using the static compiled files which it outputs. To get LESS working with Rails we’ll need the help of some Ruby gems. There are several gems available for integrating Bootstrap with Rails. In this episode we’ll be using the twitter-bootstrap-rails gem but we’ll mention some of the alternatives later. We’ve chosen this gem as it works directly with LESS and offers some nice generators to help us get started. We’re getting a little ahead of ourselves here, though as we don’t even have a Rails application to work with yet.

Adding Bootstrap to a New Rails Application.

We’ll start with a new app that we’ll call store and we’ll generate a scaffold for a Product model so that we have something to work with.

terminal

$ rails new store
$ cd store
$ rails g scaffold product name price:decimal --skip-stylesheets
$ rake db:migrate

Note that we’ve used the --skip-stylesheets option in the scaffold as we want to use Bootstrap’s CSS instead of the scaffolding’s. We’ve also migrated the database so that the products table is created. Here’s what the generated scaffold page looks like. It isn’t very pretty as we don’t have any styling applied. It’s time to add Twitter Bootstrap.

The first step is to add the twitter-bootstrap-rails gem to the assets group in the gemfile. This gem is only needed in this group as it’s only used by the assets pipeline. If we’re using static assets in production then it won’t be needed.

/Gemfile

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.2.3'
  gem 'coffee-rails', '~> 3.2.1'

  # See https://github.com/sstephenson/execjs#readme for more supported runtimes
  # gem 'therubyracer'

  gem 'uglifier', '>= 1.0.3'
  gem 'twitter-bootstrap-rails'
end

We’ll need to run bundle next to install twitter-bootstrap-rails along with its dependencies. This gem has a number of dependencies including libv8 and less-rails and these enable our app to interpret the LESS syntax. Now that we have Bootstrap installed we can run its generator to install it.

terminal

$ rails g bootstrap:install
      insert  app/assets/javascripts/application.js
      create  app/assets/javascripts/bootstrap.js.coffee
      create  app/assets/stylesheets/bootstrap_and_overrides.css.less
        gsub  app/assets/stylesheets/application.css
        gsub  app/assets/stylesheets/application.css

This sets up Bootstrap under the /app/assets directory. One key file that was generated is bootstrap_and_overrides.css.less. This file loads up Bootstrap and it’s a good place to customize the styling to suit your application. After we restart the server and reload the page we can see that the styling is already starting to look better, but there’s still a lot to do.

Improving The Layout

We’ll focus first on the application’s layout. The twitter-bootstrap-rails gem provides a bootstrap:layout generator for generating a layout file, but we won’t use that here. Instead we’ll walk through the steps required to change the layout to give you a better idea as to how Twitter Bootstrap works.

There are two kinds of layouts, fixed and fluid. A fixed layout is a specific pixel width, while a fluid layout will expand to the full width of the browser. Specifying either container or container-fluid as the class of the wrapper div will determine which layout is used. We’re going to use a fixed-width layout here so we’ll add a div with a container class to the body of the layout file.

/app/views/layouts/application.html.erb




  Store
  <%= stylesheet_link_tag    "application", :media => "all" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tags %>



  <%= yield %>

Twitter Bootstrap uses a 12-column grid system. This makes it easy to implement column-based layout designs by specifying the width of each column. This layout is responsive so if we reduce the width of the browser the layout will change accordingly. Let’s say that we want a sidebar in our design and that we want this to take up 25% of the width of the page. We can do that by modifying the layout file like this. We’ll just add some static text to the sidebar for now.

/app/views/layouts/application.html.erb

<div class="container">
  <div class="row">
    <div class="span9"><%= yield %></div>
    <div class="span3">
      <h2>About Us</h2>
      <p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.</p>	
    </div>
  </div>
</div>

When we reload the page now we’ll see our new two-column layout.

Adding a Navigation Bar

Next we’ll add a navigation bar to the top of the page with some links for navigating the site. The components section of the documentation describes the various navigation options that Twitter Bootstrap provides, including a navbar. This navbar can be customized to suit our needs and we can add links, dropdown sections, search fields and so on. The documentation has good examples of how we can add each type of item. We’ll add our navbar at the top of the layout page’s body.

/app/views/layouts/application.html.erb

<div class="navbar navbar-fixed-top">
  <div class="navbar-inner">
    <div class="container">
      <a class="btn btn-navbar" data-toggle="collapse" data-target=".collapse">
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </a>
      <a class="brand" href="#">Some Store</a>
      <div class="nav-collapse">
        <ul class="nav">
          <li><%= link_to "Browse Products", products_path %></li>
          <li><%= link_to "Price List" %></li>
          <li><%= link_to "Contact Us" %></li>
          <li><%= link_to "Cart" %></li>
        </ul>
      </div>
    </div>
  </div>
</div>

Our navigation has a brand name section and some placeholder links. The section at the top is interesting. It handles the collapsing behaviour when the browser resizes for the navigation. Reloading the page now will show our new navbar.

Note that we see the collapsed version of the navigation. This is because the browser window’s width is set to around 800px which means that it isn’t wide enough to show the full version. If we widen the window the navigation will appear.

There’s a problem when we do this, however. The top part of the page is covered by the navbar. This is a side effect of using a fixed navbar and the documentation tells us that to avoid this unwanted effect we should add at least 40 pixels of padding to the top of the body element between the Bootstrap CSS and the responsive CSS. We do this inside the bootstrap_and_overrides CSS file. This file includes the bootstrap and responsive files and the documentation says that padding needs to be added between these.

/app/assets/stylesheets/bootstrap_and_overrides.css

@import "twitter/bootstrap/bootstrap";

body { padding-top: 60px; } 

@import "twitter/bootstrap/responsive";

// Set the correct sprite paths
@iconSpritePath: asset-path('twitter/bootstrap/glyphicons-halflings.png');
@iconWhiteSpritePath: asset-path('twitter/bootstrap/glyphicons-halflings-white.png');

// Your custom LESS stylesheets goes here
//
// Since bootstrap was imported above you have access to its mixins which
// you may use and inherit here
//
// If you'd like to override bootstrap's own variables, you can do so here as well
// See http://twitter.github.com/bootstrap/less.html for their names and documentation
//
// Example:
// @linkColor: #ff0000;

When we reload the page now the top of it is no longer hidden behind the navbar.

Final Tweaks to The Header

Our application’s layout file is pretty much complete now but there are a couple of thing we need to add in the head section to ensure that it works everywhere.

/app/views/layouts/application.html.erb

<head>
  <title>Store</title>
  <!--[if lt IE 9]>
    <script src="http://html5shim.googlecode/svn/trunk/html5.js" type="text/javascript"></script>
  <![endif]-->
  <%= stylesheet_link_tag    "application", :media => "all" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tags %>
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>

The first piece of code we’ve added here improves the HTML 5 support in older versions of Internet Explorer. The second is a viewport meta tag and this fixes the responsive design behaviour on mobile devices.

Improving The Views

What about the other views in this application? There’s a lot that Twitter Bootstrap provides that can improve the look of the scaffold-generated code we have. First we’ll add a few product records so that we have some more content to work with.

Next we’ll use Twitter Bootstrap to improve the look of this page. Instead of walking through each change manually we’ll use one of the generators provided by the gem. This generator is called themed and is designed to work on top of scaffolding so we need to pass it the name of a scaffold. We also pass in the -f option to force it to overwrite the generated view files.

terminal

$ rails g bootstrap:themed products -f

When we reload the products page now it looks much better. The table is a lot cleaner and the “edit” and “destroy” links now look like buttons instead of like plain text links.

Similar changes have been applied to the pages for viewing and editing a single product. We can view the source for these templates to see exactly how this works.

/app/views/products/index.html.erb

<h1>Products</h1> <table class="table table-striped"> <thead> <tr> <th>ID</th> <th>Name</th> <th>Created at</th> <th>Actions</th> </tr> </thead> <tbody> <% @products.each do |product| %> <tr> <td><%= product.id %></td> <td><%= link_to product.name, product_path(product) %></td> <td><%= product.created_at %></td> <td> <%= link_to 'Edit', edit_product_path(product), :class => 'btn btn-mini' %> <%= link_to 'Destroy', product_path(product), :method => :delete, :confirm => 'Are you sure?', :class => 'btn btn-mini btn-danger' %> </td> </tr> <% end %> </tbody> </table> <%= link_to 'New', new_product_path, :class => 'btn btn-primary' %>

A couple of CSS classes have been added to the table that displays the products. Similarly classes have been added to the “Edit” and “Destroy” links to improve their look. The biggest change has happened to the partial that contains the form for creating or editing a product.

/app/views/products/_form.html.erb

<%= form_for @product, :html => { :class => 'form-horizontal' } do |f| %> <fieldset> <legend><%= controller.action_name.capitalize %> Product</legend> <div class="control-group"> <%= f.label :name, :class => 'control-label' %> <div class="controls"> <%= f.text_field :name, :class => 'text_field' %> </div> </div> <div class="control-group"> <%= f.label :price, :class => 'control-label' %> <div class="controls"> <%= f.text_field :price, :class => 'text_field' %> </div> </div> <div class="form-actions"> <%= f.submit nil, :class => 'btn btn-primary' %> <%= link_to 'Cancel', products_path, :class => 'btn' %> </div> </fieldset> <% end %>

The code in here has changed significantly from the scaffolding code and it serves as a nice example as to how you can get a form to look really good with Twitter Bootstrap.

We’re nearing the end of this episode now and we said we’d mention some alternatives to the twitter-bootstrap-rails gem. There’s a list of these in this article on Ruby Source which explains how Twitter Bootstrap works and shows the various options and gems that are available for integrating it with Rails.

ActiveAttr

Sat, 25 Feb 2012 20:00:46 +0000

Back in episode 219 we used ActiveModel to create a model that isn’t backed by a database table but which still has some ActiveRecord features, such as validations. ActiveModel is great but isn’t very convenient to use directly like this. For example it takes quite a bit of code just to make a simple model that has some validation support.

/app/models/message.rb

class Message
  include ActiveModel::Validations
  include ActiveModel::Conversion
  extend ActiveModel::Naming

  attr_accessor :name, :email, :content

  validates_presence_of :name
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
  validates_length_of :content, :maximum => 500

  def initialize(attributes = {})
    attributes.each do |name, value|
      send("#{name}=", value)
    end
  end

  def persisted?
    false
  end
end

There is a gem called ActiveAttr that can help with this. It’s described by its author Chris Greigo as “what ActiveModel left out” which is a fair description of what it does. Using it makes it much easier to create a table-less model that behaves similarly to ActiveRecord and we’ll show you how it works in this episode.

Using ActiveAttr With a Contact Form

We’ll be working with an application which has a “Contact Us” form. When the form is filled in and submitted we want to send an email but not save the message to the database. We don’t want to use ActiveRecord at all here but we do want to use some of its features, such as validations, so that if the user fails to fill the form in correctly they see some error messages explaining what they’ve done wrong.

We’ve already created the controller and view for this and they work very similarly to what we’d have if we used Rails’ scaffolding. We’ll walk through it quickly now. The MessagesController has new and create actions. When the new action is triggered it will create a new instance of Message and render out a template.

/app/views/messages/new.html.erb

<h1>Contact Us</h1>

<%= form_for @message do |f| %>
  <% if @message.errors.any? %>
    <div class="error_messages">
      <h2><%= pluralize(@message.errors.count, "error") %> prohibited this message from being saved:</h2>
      <ul>
      <% @message.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>
  <div class="field">
    <%= f.label :name %><br />
    <%= f.text_field :name %>
  </div>
  <div class="field">
    <%= f.label :email %><br />
    <%= f.text_field :email %>
  </div>
  <div class="field">
    <%= f.label :content, "Message" %><br />
    <%= f.text_area :content, :rows => 5 %>
  </div>
  <div class="actions"><%= f.submit "Send Message" %></div>
<% end %>

This view holds the code for the form. Note that we’re using form_for to define the form and passing it the message model instance from the controller. We display error messages just as we would with scaffold-generated code so from the view template this looks just like code to handle an ActiveRecord model. When the form is submitted it triggers the controller’s create action.

/app/controllers/messages_controller.rb

class MessagesController < ApplicationController
  def new
    @message = Message.new
  end

  def create
    @message = Message.new(params[:message])
    if @message.valid?
      # TODO send message here
      redirect_to root_url, notice: "Message sent! Thank you for contacting us."
    else
      render "new"
    end
  end
end

This action makes a new Message instance base based on the parameters from the form then checks that the new message is valid. If so it will email the message and redirect back to the home page. If it’s invalid it will render the form again. We need this message model to behave just like ActiveRecord, except that we’re just validating it not saving it to a database table.

The Message model currently uses ActiveModel to handle this behaviour and you can see its code at the top of the this episode. We don’t want to use this approach here, though. Instead we’re going to use ActiveAttr. To do this we’ll need to add the gem to the gemfile and run bundle to install it.

/Gemfile

gem 'active_attr'

We can now use ActiveAttr in our model.

/app/models/message.rb

class Message
  include ActiveAttr::Model
end

Note that Message doesn’t inherit from another class, it’s just a simple Ruby class. By including ActiveAttr::Model we’ll add some functionality that builds on ActiveModel to make this class behave more like an ActiveRecord model. We can define attributes for the model by using attribute and we can add validations in the same way we would for an ActiveRecord-derived class.

/app/models/message.rb

class Message
  include ActiveAttr::Model
  
  attribute :name
  attribute :email
  attribute :content
  
  validates_presence_of :name
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
  validates_length_of :content, :maximum => 500
end

We now have a fully-functional model that behaves like an ActiveRecord model. If we try visiting the form again and submit it without filling in any of the fields we’ll see validation errors just like we expect but the model code is quite a bit simpler.

Mass Assignment Protection

ActiveAttr also provides mass assignment protection. Let’s say that we have a priority attribute on the Message model and that we don’t want it to be settable through form values. We can use attr_accessible to define the attributes that should be accessible just like we would with an ActiveRecord model.

/app/models/message.rb

class Message
  include ActiveAttr::Model
  
  attribute :name
  attribute :email
  attribute :content
  attribute :priority
  
  attr_accessible :name, :email, :content

  validates_presence_of :name
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
  validates_length_of :content, :maximum => 500
end

We can test this behaviour in the console. If we create a new Message and try to set its priority this will fail, although we can set priority directly.

console

1.9.3p0 :001 > m = Message.new(priority: 1)
 => #<Message content: nil, email: nil, name: nil, priority: nil> 
1.9.3p0 :002 > m.priority
 => nil 
1.9.3p0 :003 > m.priority = 1
 => 1

ActiveAttr also allows us to call an attribute with a question mark to force its value to be boolean just like ActiveRecord does. Future versions of ActiveAttr will also allow us to pass additional options to attribute so that we can specify the attribute’s type and also a default value.

/app/models/message.rb

 attribute :priority, type: Integer, default: 0

These options aren’t yet available but they should be coming soon so it’s worth checking ActiveAttr’s Github page so see if these features have been released.

That’s it for this episode on ActiveAttr. It’s a great way to make table-less models. The documentation has further details of what you can do with it. We’ve used the ActiveAttr::Model module which includes everything but there are separate modules for its different features which can be used if you only need part of ActiveAttr’s functionality.

Passing Data to JavaScript

Sun, 19 Feb 2012 18:34:51 +0000

When JavaScript plays a large part in a Rails application it often becomes necessary to pass data from the app on the server to JavaScript to be used by the client. In this episode we’ll explore some techniques for doing just that. Below is a simple page from a simple Rails application. The idea here is that we want JavaScript to take over and handle fetching and displaying the products. To do that we’ll need to pass some information from our app to the JavaScript that runs on the client.

The view template for this page is simple as the page suggests.

/app/views/products/index.html.erb

<h1>Products</h1>

<div id="products">
  Loading products...
</div>

Let’s say that the JavaScript in the app needs to know the URL to call to fetch the list of products. We don’t want to hard-code this in the JavaScript code and so we’ll generate it dynamically in our Rails app. One way we can do this is to use javascript_tag in the view.

/app/views/products/index.html.erb

<%= javascript_tag do %>
  window.productsURL = '<%= j products_url %>';
<% end %>

Note that we use Rails’ j method to make sure that the URL is safely escaped for embedding in JavaScript. Now we can use this variable in any of the JavaScript or CoffeeScript files that this page references.

/app/assets/javascripts/products.js.coffee

jQuery ->
  alert productsURL

If we want to preload the page with an initial set of products instead of having fetch them in a separate request we could fetch, say, the first ten products as JSON and have the JavaScript display them straight away. We could do this by writing something like this:

/app/views/products/index.html.erb

<%= javascript_tag do %>
  window.productsURL = '<%= j products_url %>';
  window.products = <%= raw Product.limit(10).to_json %>
<% end %>

Rails will automatically try to HTML-escape the list of products and so we have to call raw on the JSON that’s returned.

This approach can become awkward fairly quickly and using data attributes on HTML can often be a better alternative. We can pass in the products URL to one like this:

/app/views/products/index.html.erb

<h1>Products</h1>

<div id="products" data-url="<%= products_url %>">
  Loading products...
</div>

We can easily fetch this information with some jQuery code.

/app/assets/javascripts/products.js.coffee

jQuery ->
  alert $('#products').data('url')

This technique has the same effect but feels a little cleaner, apart from having to nest Erb tags within HTML attributes. Using content_tag is generally a better approach for inserting dynamic data into an HTML tag.

/app/views/products/index.html.erb

<h1>Products</h1>

<%= content_tag "div", id: "products", data: {url: products_url} do %>
  Loading products...
<% end %>

Since Rails 3.1 we’ve been able to use a data hash to define data attributes which makes this approach even better. If we pass Ruby objects into this hash to_json is called so that the object or objects passed in are automatically converted to their JSON representation.

/app/views/products/index.html.erb

<h1>Products</h1>

<%= content_tag "div", id: "products", data: {url: Product.limit(10) } do %>
  Loading products...
<% end %>

When we fetch this data it will be automatically parsed into a JavaScript object.

/app/assets/javascripts/products.js.coffee

jQuery ->
  console.log $('#products').data('url')

If we reload the page now we’ll see the products listed in the console.

Gon

If we have a lot of data to pass to the JavaScript this technique can still become fairly cumbersome. Fortunately there’s one more solution we can use: the Gon gem. This allows us to set variables in our controllers and then access them from JavaScript. Gon is installed in the usual way, by adding it to the gemfile and running bundle.

/Gemfile

source 'https://rubygems.org'

gem 'rails', '3.2.1'
gem 'sqlite3'

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.2.3'
  gem 'coffee-rails', '~> 3.2.1'

  # See https://github.com/sstephenson/execjs#readme for more supported runtimes
  # gem 'therubyracer'

  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'
gem 'gon'

Next we’ll need to update our application’s layout file by adding include_gon somewhere inside the head section.

/app/views/layouts/application.html.erb

<head>
  <title>Store</title>
  <%= include_gon %>
  <%= stylesheet_link_tag    "application", media: "all" %>
  <%= javascript_include_tag "application" %>
  <%= csrf_meta_tag %>
</head>

If we do this before we load any other JavaScript files we’ll be able to access the variables we’ve set through Gon without waiting for the entire DOM to load.

We can now set variables on a gon object in a controller action.

/app/controllers/products_controller.rb

class ProductsController < ApplicationController
  def index
    gon.products = Product.limit(10)
  end
end

This list of products will now automatically be converted to JSON and be accessible by our application’s JavaScript. We can access this list of products like this:

/app/assets/javascripts/products.js.coffee

console.log gon.products

Note that we don’t have to wait for the DOM to load before we access this data. If we reload the page now we’ll see the list of products in the console again.

If we view the page’s source we’ll see how this all works.

html

<!DOCTYPE html>
<html>
  <head>
    <title>Store</title>
	<script>window.gon = {};gon.products=[{"created_at":"2012-02-18T20:24:45Z","id":1,"name":"Settlers of Catan","price":"29.95","updated_at":"2012-02-18T20:24:45Z"},{"created_at":"2012-02-18T20:24:45Z","id":2,"name":"DVD Player","price":"79.98999999999999","updated_at":"2012-02-18T20:24:45Z"},{"created_at":"2012-02-18T20:24:45Z","id":3,"name":"Red Shirt","price":"12.49","updated_at":"2012-02-18T20:24:45Z"}];</script>
    // Other products omitted.
    <link href="/assets/application.css?body=1" media="all" rel="stylesheet" type="text/css" />
<link href="/assets/products.css?body=1" media="all" rel="stylesheet" type="text/css" />
    <script src="/assets/jquery.js?body=1" type="text/javascript"></script>
<script src="/assets/jquery_ujs.js?body=1" type="text/javascript"></script>
<script src="/assets/products.js?body=1" type="text/javascript"></script>
<script src="/assets/application.js?body=1" type="text/javascript"></script>
    <meta content="authenticity_token" name="csrf-param" />
<meta content="KktOQAWKvaRho+IdWOiaBud0W7Vuv31rdn0LF38hBag=" name="csrf-token" />
  </head>
  <body>
    <!-- Body omitted -->
  </body>
</html>

Gon simply creates a script tag then fills a gon variable with the data that we set in the controller. If we want to customize the JSON that’s returned to the client Gon has support for both RABL and Jbuilder templates, both of which have been covered in recent episodes. To customize the data returned by the list of products we can create an index.json.rabl file and define the attributes we want to be returned there.

/app/views/products/index.json.rabl

collection Product.limit(10)

attributes :id, :name, :price

We can use gon.rabl to tell Gon to use this template.

/app/controllers/products_controller.rb

class ProductsController < ApplicationController
  def index
    gon.rabl "app/views/products/index.json.rabl", as: "products"
  end
end

This will store the response from the template in a products variable. When we reload the page now we’ll see the same list of products, but their attributes will have been defined by the RABL template.

There’s a small potential trap when using Gon. If we don’t define any gon variables in a controller action and we try to call gon in the JavaScript we’ll get an error as the gon object won’t have been set. It’s always best to ensure that this object exists before trying to call anything against it.

/app/assets/javascripts/products.js.coffee

console.log gon.products if gon

There’s more information about Gon in its documentation which is well worth reading if you’re thinking of using it in your Rails applications.

OmniAuth Identity

Sun, 29 Jan 2012 18:04:39 +0000

OmniAuth recently reached version 1.0 and has a number of nice additions. In this episode we’ll take a look at a new strategy called OmniAuth Identity which allows users to create an account by supplying a user name and password instead of logging in through an external provider.

How Our Application Currently Works

Below is a screenshot from the application we’ll be working with. We already have OmniAuth set up with three external providers.

If we sign in through one of these providers, say Twitter, we’ll be redirected to Twitter’s website and asked if we want to authorize the application to access our Twitter account details. If we agree the application will grab our profile information from Twitter and we’ll be signed in.

Once we’ve authorized this application we won’t need to do it again and we can log in to our application through Twitter by just clicking the icon on the home page.

This is a convenient way of allowing users to sign in to but we’re excluding those who don’t want to sign in through one of these services. We should give these users the option of creating an account with a password directly in the site and this is where OmniAuth Identity comes in.

Before we do this we’ll walk through some of the application’s code to give you an idea of how it works. The source code is based on the application from episode 241 and if you’re unfamiliar with OmniAuth it’s worth taking a look at that episode first.

Since episode 241 was written there have been some changes to OmniAuth and one of the most significant is in the gemfile. Each provider now has a separate gem for OmniAuth so it’s necessary to include the right gem for each provider we want to support.

/Gemfile

gem 'omniauth-twitter'
gem 'omniauth-facebook'
gem 'omniauth-google-oauth2'

OmniAuth’s initializer looks much the same as it did before. In it we add OmniAuth as middleware and add a provider for each provider we want to use.

/config/initializers/omniauth.rb

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
  provider :google_oauth2, ENV['GOOGLE_KEY'], ENV['GOOGLE_SECRET']
  provider :facebook, ENV['FACEBOOK_ID'], ENV['FACEBOOK_SECRET']
end

The application has a SessionsController whose create action is triggered as the OmniAuth callback. In it we create a user based on the OmniAuth hash and store that new user’s id in a session variable.

/app/controllers/sessions_controller.rb

class SessionsController < ApplicationController
  def new
  end

  def create
    user = User.from_omniauth(env["omniauth.auth"])
    session[:user_id] = user.id
    redirect_to root_url, notice: "Signed in!"
  end

  def destroy
    session[:user_id] = nil
    redirect_to root_url, notice: "Signed out!"
  end

  def failure
    redirect_to root_url, alert: "Authentication failed, please try again."
  end
end

The user is fetched from OmniAuth in a from_omniauth method in the User model.

/app/models/user.rb

class User < ActiveRecord::Base
  def self.from_omniauth(auth)
    find_by_provider_and_uid(auth["provider"], auth["uid"]) || create_with_omniauth(auth)
  end

  def self.create_with_omniauth(auth)
    create! do |user|
      user.provider = auth["provider"]
      user.uid = auth["uid"]
      user.name = auth["info"]["name"]
    end
  end
end

This method first checks to see if a user with the selected provider and user id exists. If so that user is returned, if not a create_with_omniauth method is called which creates that new user based on information from the OmniAuth hash that’s passed in. There’s one change to note in the hash. The info parameter was called user_info in earlier versions so if you’re upgrading an application to use OmniAuth 1.0 your code may break.

Adding OmniAuth Identity to an Application

That’s all the code that’s necessary to handle authentication through OmniAuth. Next we’ll add OmniAuth Identity so that users can create an account without having to use an external authentication service. As we mentioned earlier each OmniAuth provider requires a separate gem so the first thing we’ll need to do is add the omniauth-identity gem to the gemfile.

/Gemfile

# To use ActiveModel has_secure_password
gem 'bcrypt-ruby', '~> 3.0.0'

gem 'omniauth-twitter'
gem 'omniauth-facebook'
gem 'omniauth-google-oauth2'
gem 'omniauth-identity'

This gem relies on bcrypt-ruby for password hashing, but it’s not a dependency so it’s necessary to add bcrypt-ruby to the gemfile as well. There should be a comment in the gemfile that we can uncomment to add this gem. As ever we’ll need to run bundle to make sure all the gems are installed.

Next we’ll need to go to OmniAuth’s initializer and add the identity provider. We don’t need to add any parameters to this provider for now.

/config/initializers/omniauth.rb

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
  provider :google_oauth2, ENV['GOOGLE_KEY'], ENV['GOOGLE_SECRET']
  provider :facebook, ENV['FACEBOOK_ID'], ENV['FACEBOOK_SECRET']
  provider :identity
end

We’ll need a model to store login information. By default this model should be called identity, but we can customize this if we need to. We’ll need to give it name, email and password_digest fields.

$ rails g model identity name:string email:string password_digest:string

We’ll need to migrate the database to add the table.

$ rake db:migrate

OmniAuth Identity’s README shows us what we need to do to get the Identity model to work with various ORMs, including ActiveRecord. We’ll need to change the model so that it inherits from OmniAuth::Identity::Models::ActiveRecord instead of ActiveRecord::Base.

/app/models/identity.rb

class Identity < OmniAuth::Identity::Models::ActiveRecord
end

We’re almost done. All we need to do now is make a link to the new provider from the sign in page under the links for logging in through an external provider.

/app/views/sessions/new.html.erb

<p>
  <strong>Don&rsquo;t use these services?</strong>
  <%= link_to "Create an account", "/auth/identity/register" %> or
  <%= link_to "login", "/auth/identity" %> with a password.
</p>

We need to restart the server for the changes to OmniAuth to be picked up. Once we have when we visit the sign-in page we’ll see new links for registering or logging in. First we’ll register a new account.

OmniAuth Identity provides a simple registration form with a clean interface and once we’ve filled it in correctly we’ll be signed in and taken to our profile page.

The login page looks similar, but has just two fields. The login field expects the email address we entered when we registered, though this isn’t obvious.

Creating Custom Registration and Login Forms

Registration and logging-in pretty much just work and because Identity uses the same OmniAuth interface as the code for the other providers we don’t have to change much of our core application to add this functionality. That said, there are a few pitfalls we should be aware of. If we have validations on our Identity model the user won’t see any errors if they fill in the form incorrectly. To demonstrate this we’ll add some validations to the Identity model now.

/app/models/identity.rb

class Identity < OmniAuth::Identity::Models::ActiveRecord
  validates_presence_of :name
  validates_uniqueness_of :email
  validates_format_of :email, :with => /^[-a-z0-9_+\.]+\@([-a-z0-9]+\.)+[a-z0-9]{2,4}$/i
end

If we enter an invalid email address on the registration form now and try to register we’ll be taken back to the form with no indication of what we did wrong.

Similarly, the login form doesn’t make it clear that the “Login” field expects the user’s email address. There are options to customize the way this form looks but nothing particularly extensive. A better solution is to create our own custom forms in to the app itself to give us complete control over how they’re rendered and how they behave.

We’ll move the login form first. Instead of displaying a link to OmniAuth’s login form on the sign-in page we’ll show our custom login form.

/app/views/sessions/new.html.erb

<p>
  <strong>Don&rsquo;t use these services?</strong>
  <%= link_to "Create an account", "/auth/identity/register" %> or login below.
</p>
  
<%= form_tag "/auth/identity/callback" do %>
  <div class="field">
    <%= label_tag :auth_key, "Email" %><br>
    <%= text_field_tag :auth_key %>
  </div>
  <div class="field">
    <%= label_tag :password %><br>
    <%= password_field_tag :password %>
  </div>
  <div class="actions"><%= submit_tag "Login" %></div>
<% end %>

This form POSTs to /auth/identity/callback which is where OmniAuth’s own form submits its data. We also give the form fields the same names they have on OmniAuth’s form. When we reload the sign in page now we have a login form and we can use it to enter our details and log in to the site just as we did with the other form.

We can take a similar approach to replacing the registration form, although we’ll need to create a new controller to do this.

$ rails g controller identities

We’ll treat this controller as a resource so we’ll modify the routes file to add it as such there.

/config/routes.rb

Auth::Application.routes.draw do
  root to: "sessions#new"
  match "/auth/:provider/callback", to: "sessions#create"
  match "/auth/failure", to: "sessions#failure"
  match "/logout", to: "sessions#destroy", :as => "logout"
  resources :identities
end

We’ll give the controller a new action. There’s a chance that if the validation for the registration form fails the identity object will be stored in a Rack environment variable so we’ll fetch it from there so that we can show any error messages on it.

/app/controllers/identities_controller.rb

class IdentitiesController < ApplicationController
  def new
    @identity = env['omniauth.identity']
  end
end

The associated template is fairly large but there’s nothing unusual in it.

app/views/identities/new.html.erb

<h1>New Account</h1>

<%= form_tag "/auth/identity/register" do %>
  <% if @identity && @identity.errors.any? %>
    <div class="error_messages">
      <h2><%= pluralize(@identity.errors.count, "error") %> prohibited this account from being saved:</h2>
      <ul>
      <% @identity.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>
  <div class="field">
    <%= label_tag :name %><br>
    <%= text_field_tag :name, @identity.try(:name) %>
  </div>
  <div class="field">
    <%= label_tag :email %><br>
    <%= text_field_tag :email, @identity.try(:email) %>
  </div>
  <div class="field">
    <%= label_tag :password %><br>
    <%= password_field_tag :password %>
  </div>
  <div class="field">
    <%= label_tag :password_confirmation %><br>
    <%= password_field_tag :password_confirmation %>
  </div>
  <div class="actions"><%= submit_tag "Register" %></div>
<% end %>

The form in this template POSTs to /auth/identity/register. At the top of the form we display any errors; below it are the same fields that OmniAuth’s registration form has. We populate the name and email fields if they exist in the current identity object.

We’ll need to alter the “Create an account” link on the sign in page so that it points to our new form instead of OmniAuth’s default.

/app/views/sessions/new.html.erb

<p>
  <strong>Don&rsquo;t use these services?</strong>
  <%= link_to "Create an account", new_identity_path %> or login below.
</p>

When we click this link now we’ll be taken to our new form and we can use it to register a new account.

Our new form works well for creating new valid accounts but if we enter some invalid information then submit the form we’ll be redirected back to OmniAuth’s registration form. To fix this we’ll need to go to OmniAuth’s initializer file and modify the identity provider we added earlier.

/config/initializers/omniauth.rb

Rails.application.config.middleware.use OmniAuth::Builder do
  provider :twitter, ENV['TWITTER_KEY'], ENV['TWITTER_SECRET']
  provider :google_oauth2, ENV['GOOGLE_KEY'], ENV['GOOGLE_SECRET']
  provider :facebook, ENV['FACEBOOK_ID'], ENV['FACEBOOK_SECRET']
  provider :identity, on_failed_registration: lambda { |env|    
    IdentitiesController.action(:new).call(env)
  }
end

The option we’ve added, on_failed_registration, takes a Rack application as an argument. We’ve set it to point to the new action in the IdentitiesController so that our new form is shown again. There’s an issue with calling this action directly: in development mode the action won’t always be reloaded so we’ve wrapped the code in a lambda to stop the action being cached.

We’ll need to start the Rails server for these changes to be picked up, but once we have the form will behave as we expect it to when we enter invalid information.

We now have OmniAuth identity working smoothly. Creating the custom forms took quite a bit of work but this is a still a nice solution if you’re already using OmniAuth and just need to add account registration.

In-place Editing

Sun, 29 Jan 2012 17:53:45 +0000

Above is a user profile page from a Rails application. There’s an “Edit Profile” link at the bottom of the page and clicking this link will take us to a page where we can edit our details.

Instead of using a separate editing page we want to give users the ability to edit the fields directly inline on the profile page by clicking on any field. Doing this should make the field editable and hitting Enter or tabbing out of the field should save any changes made to the database.

Best In Place

There are a number of Rails plugins that can help us to add in-place editing to our application and there’s a comprehensive list of them at The Ruby Toolbox. The one we’ll be using is called Best In Place, although the others are worth taking a look at. Best In Place is a fork of another project called Rest in Place and what makes it worth using is the best_in_place helper method it offers. This makes it easy to add in-place editing fields in our Rails applications.

Best In Place has a demo page and if we try it we’ll see that we can edit any field by clicking it. Doing this replaces the static text with a form field appropriate for that type of data that’s being edited. When we hit enter for click out of the field the changes are sent back to the server and the database is updated. Best in place supports validations so if we enter, say, an invalid email address we’ll see an error message and the entered value will revert back to the last valid value. It also supports different data types and so can show a dropdown menu for editing an association or toggle between two values for a boolean field. Let’s see what’s involved in adding it to our profile page.

Adding Best In Place to Our Application

To add Best in Place to our app we first need to add its gem to our application’s Gemfile and run bundle.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.3'

gem 'sqlite3'

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.1.5'
  gem 'coffee-rails', '~> 3.1.1'
  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'
gem 'best_in_place'

The gem includes two JavaScript files that we’ll need to include in our application, jquery.purr, a jQuery plugin, and best_in_place. Since this is a Rails 3.1 app we can add them to the JavaScript manifest file.

/app/assets/javascripts/application.js

//= require jquery
//= require jquery_ujs
//= require jquery.purr
//= require best_in_place
//= require_tree .

We need to define the fields that will be editable and we’ll do this in the users CoffeeScript file. All we have to do is call best_in_place() on any elements we want to be editable. We’ll apply it to elements with the class best_in_place which is what Best In Place uses internally.

/app/assets/javascripts/users.js.coffee

jQuery ->
  $('.best_in_place').best_in_place()

Now that we have Best In Place set up we can start to apply it to our User Profile page. Here’s how the page’s template currently looks:

/app/views/users/show.html.erb

<h1>User Profile</h1>

<p>
  <b>Name:</b>
  <%= @user.name %>
</p>
<p>
  <b>Email:</b>
  <%= @user.email %>
</p>
<p>
  <b>Gender:</b>
  <%= @user.gender %>
</p>
<p>
  <b>Public profile:</b>
  <%= @user.public_profile %>
</p>
<p>
  <%= @user.bio %>
</p>

<%= link_to 'Edit Profile', edit_user_path(@user) %>

The template simply outputs the value for each field. We’ll add Best In Place’s helper method to the name and email fields. This method takes two arguments, the object we’re viewing and a symbol for the field we want to edit.

/app/views/users/show.html.erb

<p>
  <b>Name:</b>
  <%= best_in_place @user, :name %>
</p>
<p>
  <b>Email:</b>
  <%= best_in_place @user, :email %>
</p>

When we load the user profile page now and click on either the name or email field that field becomes editable.

Storing Changes

When we make a change a field then click away from it the field reverts to its previous value, which isn’t what we want to happen. If we then reload the page, though, we’ll see a message telling us that the user has been updated and the page shows the changed value.

This is happening because Best In Place uses JSON to send updates back to the server but our UsersController isn’t set to respond to JSON requests correctly. This controller uses the usual seven RESTful action, which Best In Place expects, and when we change value in the name field the update action is triggered. The correct parameters are sent to the action but it doesn’t respond to JSON requests as it should.

To fix this we could add a respond_to block in update or, as this is a Rails 3 application, use respond_with which will handle everything for us. This expects a respond_to call at the top of the controller so we’ll need to add that as well.

/app/controllers/users_controller.rb

class UsersController < ApplicationController
  respond_to :html, :json
 
  # Other actions omitted.
 
  def update
    @user = User.find(params[:id])
    @user.update_attributes(params[:user])
    respond_with @user
  end

end

If we need to customize this behaviour further we can use a full respond_to block in the update action and there’s an example of how to do this in Best in Place’s README.

Now that our controller responds to JSON the in-place functionality works correctly. Any changes we make are added to the database and the UI updates as we expect.

Validations also work, too. If we enter an invalid email address an error message will show, although by default it isn’t particularly visible.

We can pretty this error message up with some CSS.

/app/assets/stylesheets/users.css.scss

.purr {
  position: fixed;
  top: 30px;
  right: 100px;
  width: 250px;
  padding: 20px;
  background-color: #FCC;
  border: solid 2px #666;
  &:first-letter { text-transform: uppercase };
}

All of the styles are in a purr class which is what Best in Place uses. When we reload the page now and enter a bad email address again we get a prettier error message.

Handling Other Types of Data

We’ve only made the name and email fields editable so far, now we’ll look at the other attributes on the user page. The bio field contains a long piece of text but by default best_in_place will only show a single line text box. We can change this behaviour by specifying the type attribute.

/app/views/users/show.html.erb

<%= best_in_place @user, :bio, type: :textarea %>

The public_profile field is boolean so we should use the checkbox type and pass in the values that should be displayed in a :collection option.

/app/views/users/show.html.erb

<%= best_in_place @user, :public_profile, type: :checkbox, collection: %w[No Yes] %>

Clicking on the current public profile option now will toggle between these two options. The gender option can be treated in a similar way, but here we use :select instead of :checkbox and pass in a two-dimensional array of options.

/app/views/users/show.html.erb

<%= best_in_place @user, :gender, type: :select, :collection [["Male", "Male"], ["Female", "Female"], ["", "Unspecified"]] %>

This option will show a dropdown menu when we click the current gender.

That’s is for this episode. We now have a fully-featured in-place editing option for each field in our User Profile page. There may be times when we want to do something a little more complicated, for instance displaying options for an association or maybe a formatted price field where the value displayed may be different from the one in the edit field. Unfortunately this is a little difficult to do with the current version of Best In Place. For these situations it’s still best to fall back to a ‘traditional’ edit form or write your own solution from scratch.

Contributing to Open Source

Sun, 29 Jan 2012 17:41:57 +0000

Github makes it incredibly easy to contribute to open source projects. In this episode we’ll show you how to do so by submitting a pull request to the VCR project. We covered this gem, which provides a way to record HTTP interactions and play them back in order to speed up tests, back in episode 291. Myron Marston, the gem’s author, is very good at keeping up with contributions from other people.

Let’s say that we’ve found an issue with this gem that we’d like to contribute a patch for. The first thing we should do is look at the gem’s issue tracker and make sure that it hasn’t already been addressed. If the project has a mailing list then it’s also a good idea to search this for any items related to the issue we’ve found. For large changes it’s a good idea to discuss it first to see if the change is needed.

Fork It!

Once we’re ready to start on our fix the first step is to fork the project. To do this we need to visit the project’s home page and click the ‘fork’ button. This will give us our own copy of the repository and will take a few seconds to complete but once it has we can visit our new fork and get its URL so that we can clone it.

$ git clone git@github.com:eifion/vcr.git
$ cd vcr

When we’ve cloned the repository we should see what branches it has.

$ git branch -r
  origin/1-x-stable
  origin/HEAD -> origin/master
  origin/jruby_nailgun
  origin/master

One thing to notice here is that there’s a branch for the stable release of version 1 which is the current version of the gem. The master branch points to version 2 which is currently in pre-release. This is something to keep in mind: the version of the gem that you’re using may different from the one you’re working on in the code.

When setting up the development environment for a project it’s a good idea to check the documentation. In this case there’s a development section in the README file that tells us that pull requests are welcome, but that any changes we made need to be fully covered by tests. The README doesn’t have any instructions on running the gem’s test suite but it’s encouraging to see that Travis CI says that the tests are all currently passing.

The project has a Gemfile so it uses Bundler to manage its dependencies. We should be able to install these by running bundle install but when we try this we see an error. This is to be expected as every system is set up differently so we should expect to run into a couple of hiccups when we try to set up a project in our environment.

The error we see is related to the rb-fsevent gem and a quick search tells us that this problem is related to our set up. We’re using the GCC Installer rather than the full Xcode install on OS X and the current version of won’t install this way. This problem has now been fixed in rb-fsevent but the fix isn’t yet in a stable release. We can solve this problem by setting the version of rb-fsevent in the Gemfile to the current pre-release version.

```*/Gemfile # Additional gems that are useful, but not required for development. group :extras do gem 'guard-rspec' gem 'growl' gem 'relish', '~> 0.5.0' gem 'fuubar' gem 'fuubar-cucumber' platforms :mri do gem 'rcov' gem 'rb-fsevent', '0.9.0.pre4' end platforms :mri_18, :jruby do gem 'ruby-debug' end platforms :mri_19 do gem 'ruby-debug19' end unless RUBY_VERSION == '1.9.3' end ```

When we run bundle now everything installs correctly.

Running The Tests

Next we’ll try to run the gem’s tests. This is often set as the default Rake task so we should be able to run them by running rake. It’s better, though, to run bundle exec rake though so we know that it’s using Bundler.

$ bundle exec rake
  1504/1504:   100% |==========================================| ETA:  00:00:00

The tests pass with a few pending issues which is fine. After the tests have run the Cucumber scenarios are executed. We get one failure here with a long error message, the nub of which says “no such file to load -- spec”. It looks like we’re missing a dependency that Bundler hasn’t set up.

After some investigation it turns out that this project uses Git submodules so to get it working we need to run these two commands.

$ git submodule init
$ git submodule update

These will copy over the submodule repository for us. We can try running the tests again now and see if they pass and this time they do.

Making The Changes

We ran into a couple of problems getting the tests to pass but we’ve finally made it. This is to be expected as everyone’s development environment is different. We could have saved some time if the documentation has been better on getting the project set up. So, our first pull request will be to add some better documentation to the README file for setting up the development environment.

It turns out that there’s already a wiki page dedicated to contributing to the VCR project, but it only contains the basics on getting set up. We’ll edit this page to add some more information based on the problems we’ve had. Once we’ve made our changes we can submit a pull request which adds a link to the README for this contributing guide.

Before we make any changes to the code we’ll make sure we have a clean working directory.

$ git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   Gemfile
#
no changes added to commit (use "git add" and/or "git commit -a")

As we’ve modified the Gemfile we’ll revert this change before we go any further.

$ git checkout .
noonoo:vcr eifion$ git status
# On branch master
nothing to commit (working directory clean)

It’s a good idea to setup a separate Git branch for each pull request we want to make so we’ll do that now.

$ git checkout -b readme-contributing-link

Now we can make our change. In the development section of README.md we’ll add a link to the wiki page we just changed.

/README.md

## Development

* Source hosted on [GitHub](http://github.com/myronmarston/vcr).
* Direct questions and discussions to the [mailing list](http://groups.google.com/group/vcr-ruby).
* Report issues on [GitHub Issues](http://github.com/myronmarston/vcr/issues).
* Pull requests are very welcome! Please include spec and/or feature coverage for every patch,
  and create a topic branch for every separate change you make.
* See the [Contributing](https://github.com/myronmarston/vcr/blob/master/CONTRIBUTING.md)
  guide for instructions on running the specs and features.

Once we’ve made our changes we can run git diff to see the changes we’ve made. If we’re happy with them we can commit them by running

$ git commit -a -m "adding contributing link to readme."Next we need to push our branch to our remote repository.
$ git push origin readme-contributing-link
Counting objects: 5, done.
Delta compression using up to 2 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 328 bytes, done.
Total 3 (delta 2), reused 0 (delta 0)
To git@github.com:eifion/vcr.git
 * [new branch]      readme-contributing-link -> readme-contributing-link

This will add the branch to our Github repository.

When we visit our forked repository on Github now we can change the current branch to the one we just added.

We can then click “Pull Request” to submit our pull request to the original owner. We’ll need to fill in a form explaining the changes we’ve made and then we can send off our request.

That’s all we need to do to submit a pull request to an open source project on Github. If it’s accepted our change will make it easier for the next person who want to contribute. Now it’s your turn.

Getting Started With Spree

Sun, 29 Jan 2012 17:27:56 +0000

Spree is a fully-featured e-commerce solution that can be easily integrated into a Rails application. If you need to turn a Rails app into a store that sells products then Spree is one of the quickest ways to do this. In this episode we’ll set up Spree in a new Rails application and customize some of its functionality so that you can get an idea as to how it works and see if it fits the needs of your application.

Installing Spree

Spree depends on ImageMagick to handle the image processing it does so we’ll need to install it before we can install Spree. The easiest way to do this is to use HomeBrew.

$ brew install imagemagick

Once ImageMagick has installed we’ll create a new Rails 3.1 application that we’ll call store. Spree can be integrated into an existing Rails application but it’s a good idea to try it out in a new app first so that you can see what it adds.

$ rails new store

To install Spree and its many dependencies we need to add it to the application’s Gemfile and then run bundle. Spree is updated pretty regularly so we’ve specified the version number. Version 0.70.1 is the current version at the time of writing.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.1'

gem 'sqlite3'

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.1.4'
  gem 'coffee-rails', '~> 3.1.1'
  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'

group :test do
  # Pretty printed test output
  gem 'turn', :require => false
end

gem 'spree', '0.70.1'

Once the gems have installed we need to run a generator to add Spree to our site.

$ rails g spree:site

This command does a number of things. It copies over the migration files that create the database tables that Spree needs and it customizes several of our application’s files, mostly ones under app/assets. The generator will also remove the application.js and application.css files, so if you’ve customized these you’ll need to integrate your changes with the way that Spree organizes the application’s assets.

If we look at the application’s /app/assets directory now we’ll see that each directory in there, images, javascripts and stylesheets, now has admin and store subdirectories. This is done so that we can keep the assets for the public-facing store and the private admin pages separate. If we look at the store’s all.css file (or application.js file) we’ll see that it requires several files that are inside Spree and automatically loads them.

/app/assets/stylesheests/store/all.css

/*
 * 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 store/spree_core
 *= require store/spree_auth
 *= require store/spree_api
 *= require store/spree_promo
 *= require store/spree_dash

 *= require_self
 *= require_tree .
*/

There’s one more command we need to run to finish setting everything up. This will run the migrations that were copied over earlier. Note that it will ask if we want to destroy any existing data in the database.

$ rake db:bootstrap
This task will destroy any data in the database. Are you sure you want to 
continue? [y/n] y
db/development.sqlite3 already exists
...

This command also asks us for an email address and a password for the admin user; we’ll use the defaults that are provided. Finally we’ll be asked it we want to load some sample data and we’ll do this so that we have something to see in the store.

Email [spree@example.com]: 
Password [spree123]: 
Load Sample Data? [y/n]: y

Now we can start up our application’s server and take a look.

A First Look At Spree

This is what our store looks like. By default there’s no theme applied so it looks fairly plain, but we do have a full e-commerce store on our site containing the sample products that we loaded when we ran the generator, including a shopping cart and a checkout process.

There’s also an administration section available at http://localhost:3000/admin and once we’ve logged in using the email address and password we supplied when we ran the generator we can view it. This is also pretty fully featured and allows us to see orders that were placed and various charts to see what the best selling products are. There are also pages that let us view and edit the products and orders.

The administration section also has a number of configuration options including the ability to change the payment methods your store supports. There are different payment methods for the different environments and when we edit one of these we can change the payment gateway that it uses. When we do so Spree will give us the option to enter credentials for that gateway so that we can configure it for any payment gateways we have.

Customizing Spree

We have a fairly comprehensive e-commerce solution in our Rails application now but what if we want more control over exactly how the store looks to the customer? The default look is fairly bland and this is because no theme is applied. We’ll spend the rest of this episode showing various ways that we can customize the look and behaviour of the store.

Spree supports themes and extensions and the Blue Theme serves as a good example of how we can customize Spree. This theme, like most things in Spree, is a Rails engine, and we can use it to override various things in the app/assets and app/overrides directories. To install the theme we add the following line to the Gemfile and run bundle.

/Gemfile

gem 'spree_blue_theme', :git => 'git://github.com/spree/spree_blue_theme.git'

To get the theme to work we found it necessary to change a stylesheet file and replace the default styles (the ones that begin with require store/) with the one provided by the theme.

/app/assets/stylesheets/store/all.css

/*
 * 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 store/screen
 *= require_self
 *= require_tree .
*/

The store now looks quite different and whether we choose to use themes or not it serves as a good example of we can customize the look of a Spree application.

Customizing Individual Parts of The Site

Next we’ll look at customizing parts of the site individually. If, for example, we want to change the logo at the top left of the page with one of our own we can do so. The default image is stored at /assets/admin/bg/spree_50.png and is provided by the Spree engine but we can override this in our application.

There are two ways we can do this. One way is to create a /app/assets/images/admin/bg directory in our application and copy another image, say the default rails.png image, there, renaming it to spree_50.png. This image will override the default one and we’ll see it when we reload the page (although we may have to restart the server for the change to be picked up).

Another way we can change the logo is to override part of Spree’s configuration. The default configuration is set in a file that has a large number of configuration options. These includie a logo option that points to the location of the default logo file. Spree provides an entire preferences system that allows us to configure these options in various ways. We can do it through the database, through an admin panel or we can create an initializer and make the changes through Ruby. We’ll take the latter option and create a new spree.rb configuration file.

/config/initializers/spree.rb

Spree::Config.set(logo: "store/rails.png")

We call Spree::Config.set to set configuration options and having set the logo option we can move our image to /app/assets/images/store/ and rename it to rails.png. When we reload the page now the image is at http://localhost:3000/assets/store/rails.png.

We can also customize Spree by overriding parts of a a template. To do this we first have to find the template in the Spree source code. This isn’t difficult to do but we’ll need to be aware that we browse the source code of the same version of Spree that we’ve included. In our case we’ll need to browse version 0.70.1. Once we’re sure we’re looking at the right version can navigate to core/app/views/layouts where we’ll find a spree_application.html.erb file. This is the template that we want to override as it contains the code that renders the logo.

/app/views/layouts/spree_application.html.erb

<div id="logo" data-hook>
  <%= logo %>
</div>

There are a couple of ways that we can override this to change the way it looks. We could copy the entire layout file into the same location in our application. Spree will then use this template over its default one and any changes we make to it will be reflected in our application.

Another way is to use a gem called Deface. We don’t have to install this gem as it’s already a dependency of Spree and we can use it in the /app/overrides directory that Spree generated to override parts of Spree’s templates. The README information on the project’s homepage contains various examples showing how it works. We’ll copy the first example listed into a new file in this directory called logo.rb and modify it for the part of the page we want to change.

/app/overrides/logo.rb

Deface::Override.new(:virtual_path => "layouts/spree_application", 
                     :name => "logo", 
                     :replace_contents => "#logo", 
                     :text => "Store")

There are four options we need to specify here. The virtual_path is the path to the erb template we want to modify, while the name can be anything we want. We want to replace the contents of a div with an id of logo so we’ll use the replace_contents option and pass it a CSS selector that matches that div. The final option specifies what we want to replace the contents with; for now we’ll replace the logo with the text “Store”.

When we reload the page now the logo has gone and the text appears in its place.

We’ve replaced the image with the text but we need to style it a little. We can add the styling under the stylesheets/store directory and it’s good practice to do this in a new file. We’ll make the text larger and colour it white.

/app/assets/stylesheets/store/layout.css.scss

#logo {
  font-size: 32px;
  color: #FFF;
}

When we visit the application now we’ll see the customized styling.

That’s it for this episode. There’s a lot more to Spree than we’ve covered here and you’re encouraged to read the Spree Guides for more information. There’s a topic there for pretty much everything you could need to know about Spree.

Mercury Editor

Thu, 10 Nov 2011 23:21:33 +0000

Mercury is a project by Jeremy Jackson that allows you to edit sections of an HTML page directly in the browser. You can see it in action by clicking “Test it Out” on the project’s home page. Doing so adds a toolbar to the top of the page and highlights certain sections of it. You can then edit these sections directly and save the changes back to the server. In this episode we’ll add Mercury to a Rails application.

Below is a page from a simple Content Management System. This application has a Page model and three page records each with a name and some content. Currently there’s no way to edit the pages so we’ll add Mercury to the app so that we can edit them directly.

Installing Mercury

The first step to installing Mercury is to go into the /Gemfile and add the mercury-rails gem. This gem is being developed fairly rapidly so we’ll grab a recent version directly from Github.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.1'
gem 'sqlite3'

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.1.4'
  gem 'coffee-rails', '~> 3.1.1'
  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'
gem 'mercury-rails', git: 'https://github.com/jejacks0n/mercury.git', ref: 'a2b16bcdc9'

The commit SHA of the version we’re using is included above so that you know which version we’ve used. As ever once we’ve changed the Gemfile we’ll need to run bundle to install the new gem.

Once the gem has installed we need to run Mercury’s installation generator. This will ask us if we want to install the layout and CSS overrides files and we do.

$ rails g mercury:install
      create  app/assets/javascripts/mercury.js
       route  Mercury::Engine.routes
Install the layout and CSS overrides files? [yN] y
      create  app/views/layouts/mercury.html.erb
      create  app/assets/stylesheets/mercury_overrides.css

The output from this command tells us that we need to run another command to install Mercury’s migrations so we’ll run that next and then migrate the database.

$ rake mercury_engine:install:migrations
Copied migration 20111108202946_create_images.rb from mercury_engine
noonoo:cms eifion$ rake db:migrate
==  CreateImages: migrating ===================================================
-- create_table(:images)
   -> 0.0017s
==  CreateImages: migrated (0.0018s) ==========================================

Our application now has a mercury.js file in its app/assets directory. This file contains all of the configuration options for Mercury and comments explaining them. We’ll come back to this file later; first we’ll address how this file is loaded. In a Rails 3.1 application this file will be loaded by default on every page as the application.js manifest file includes every file under app/assets/javascripts. Mercury is quite JavaScript-heavy so we only want it to load on the Mercury-editable pages. We’ll modify the manifest so that is only loads the files we specify. (As an alternative we could move the mercury.js file out to /vendor/assets instead.) When we’re editing a page Mercury will use its own layout file that includes this JavaScript file so though it appears that we’ve removed this file completely it will still be loaded when necessary.

/app/assets/javascripts/application.js

// This is a manifest file that'll be compiled into including all the files listed below.
// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
// be included in the compiled file accessible from http://example.com/assets/application.js
// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
// the compiled file.
//
//= require jquery
//= require jquery_ujs
//= require pages

We can do something similar for Mercury’s stylesheet but we won’t do that here.

Making Pages Editable

With Mercury installed we now have access to the Mercury editor from any page in our application. To put any page into edit mode we just need to add /editor between the URL’s host and path.

Now that we know the URL to edit a page we can add the “Edit Page” link.

/app/views/pages/show.html.erb

<div id="header">
  <h1><%= raw @page.name %></h1>
  <ul id="navigation">
  <% Page.all.each do |page| %>
    <li><%= link_to_unless_current page.name, page %></li>
  <% end %>
  </ul>
</div>

<div class="content">
  <%= raw @page.content %>

  <p><%= link_to "Edit Page", "/editor" + request.path %></p>
</div>

Adding Editable Areas

We now have a link to edit any page but we haven’t yet defined any editable areas on the page. There are two sections we want to be editable: the page’s title and its content and each of these map to attributes in the Page model. To make part of a page editable we need to wrap it in an element that has a class of mercury-region and a data-type of editable. We also need to give each wrapper element an id so that we can identify it when the updated page is sent back to the server. We’ll call our two regions page_name and page_content.

/app/views/pages/show.html.erb

<div id="header">
  <h1><span id="page_name" class="mercury-region" data-type="editable"><%= raw @page.name %></span></h1>
  <ul id="navigation">
  <% Page.all.each do |page| %>
    <li><%= link_to_unless_current page.name, page %></li>
  <% end %>
  </ul>
</div>

<div class="content">
  <div id="page_content" class="mercury-region" data-type="editable">
    <%= raw @page.content %>
  </div>

  <p><%= link_to "Edit Page", "/editor" + request.path %></p>
</div>

When we reload the page now we’l see the two editable regions outlined in blue.

Saving Changes

We can edit the two regions as much as we like now and preview our changes but we can’t save any changes we make as we haven’t yet set up our application to be able to do that. When we click the “Save” icon Mercury will pop up an alert showing where it was trying to save the changes to.

The URL that Mercury tries to save to is the page’s URL. Mercury sends a POST request to this URL containing the changes. We’ll change this so that the updated content is sent to a new mercury_update action on the PagesController. We’ll need to modify the routes file so that it knows how to handle this new action.

/config/routes.rb

Cms::Application.routes.draw do
  Mercury::Engine.routes

  root to: 'pages#index'
  resources :pages do
    member { post :mercury_update }
  end
end

Note that Mercury has added its own line to the routes file to enable the editor URL for each page.

Next we’ll write the new mercury_update action. This will need to find a page by its id then update it and return a response. For now we’ll just put a placeholder comment where the update code will go.

/app/controllers/pages_controller.rb

def mercury_update
  page = Page.find(params[:id])
  # Update page
  render text: ""
end

Now we need to tell Mercury that we’re not using its default URL for updating edited pages. Rather than hard-code this in JavaScript we’ll define it in a data attribute it the “Edit Page” link. We’ll also give the link an id now so that we can access it from JavaScript.

/app/views/pages/show.html.erb

<p><%= link_to "Edit Page", "/editor" + request.path, id: "edit_link", data: { save_url: mercury_update_page_path(@page) } %></p>

We can tell Mercury about this URL at the bottom of the mercury.js configuration file by adding the following code.

/app/assets/javascripts/mercury.js

$(window).bind('mercury:ready', function() {
  var link = $('#mercury_iframe').contents().find('#edit_link');
  Mercury.saveURL = link.data('save-url');
  link.hide();
});

This code binds to the mercury:ready event and when that event fires it finds the “Edit Page” link and sets Mercury’s saveURL to the value in the data-save-url attribute we added to it. Mercury loads the content of the current page into an iframe so we have to fetch its contents and find the link through there. As this code is triggered when the page is put into edit mode we’ll add a line to hide the “Edit Page” link here, too.

When we make some changes to the page now and try to save them the error message no longer shows which means that Mercury has submitted them to the server. If we look in the development log we’ll see that saving the page triggers the mercury_update action and that it has submitted a JSON string containing all the attributes necessary to update our Page model.

Started POST "/pages/1/mercury_update" for 127.0.0.1 at 2011-11-10 18:31:59 +0000
  Processing by PagesController#mercury_update as JSON
  Parameters: {"content"=>"{\"page_name\":{\"type\":\"editable\",\"value\":\"Welcome!!\",\"snippets\":{}},\"page_content\":{\"type\":\"editable\",\"value\":\"<p>In this ASCIIcasts&nbsp;episode we are going to look at the <a href=\\\"http://jejacks0n.github.com/mercury/\\\">Mercury Editor</a>. It allows you to edit a document in-place, right in the HTML. It works in the following browsers.</p>\\n<ul>\\n  <li>Firefox 4+</li>\\n  <li>Chrome 10+</li>\\n  <li>Safari 5+</li>\\n</ul>\\n<p>Try it out here by clicking on the <strong><em>Edit Page</em></strong> link below. There you will be able to change this page content and even the title above.</p>\",\"snippets\":{}}}", "id"=>"1"}

Mercury has the option to save the data as nested form parameters instead of by using JSON. To set this option we need to modify the mercury.html.erb file that was generated when we ran the Mercury generator. This file contains an options object with a saveStyle property. By default this property has a value of null which means that JSON will be used when a page update is sent back to the server. We’ll change this to 'form'.

/app/views/layouts/mercury.html.erb

<script type="text/javascript">
  var saveUrl = null;
  var options = {
    saveStyle: 'form',  // 'form', or 'json' (default json)
    saveMethod: null, // 'POST', or 'PUT', (create, vs. update -- default POST)
    visible: null     // if the interface should start visible or not (default true)
  };
  new Mercury.PageEditor(saveUrl, options);
</script>

When we save the changes to a page now they’re sent as nested parameters rather than as JSON data and we can use this data to save the changes to the database. The page’s name and content are both nested under the content parameter and each of these has a value property. We need these to save the page’s new content back to the database.

/app/controllers/pages_controller.rb

def mercury_update
  page = Page.find(params[:id])
  page.name = params[:content][:page_name][:value]
  page.content = params[:content][:page_content][:value]
  page.save!
  render text: ""
end

When we change the page now and save the changes nothing appears to happen but when we go back to the page we’ll see that the changes have been saved.

We want our application to redirect back to the page once we’ve saved the changes and we can do that by listening for the mercury:saved event and redirecting when it fires.

/app/assets/javascripts/mercury.js

$(window).bind('mercury:saved', function() {
  window.location = window.location.href.replace(/\/editor\//i, '/');
});

Now when we save changes we’re redirected back to the page itself.

Going Further

There’s much more to Mercury than we can cover here. Reading through the comments in the mercury.js file will give you a good idea as to what is possible. For example we can customize exactly what appears in the toolbar; there are various features like snippets, history and notes that we can enable and a whole lot more. All of these are documented in mercury.js.

That’s it for our look at Mercury. It’s a great project and a lot of fun to use. If you want to add it to one of your Rails projects, though, bear in mind that you’ll need a modern version of Firefox, Chrome or Safari to use it.

Playing With PJAX

Thu, 10 Nov 2011 23:04:12 +0000

Pjax is a jQuery plugin, written by Chris Wanstrath, that allows you to easily update a section of a page with an AJAX request instead of having to do a full HTTP request. The demo page1 shows how this works. By default, clicking on any of the links on this page will cause the page to fully reload and we can tell that this has happened as the time on the page changes. When we enable pjax by clicking the checkbox clicking the links no longer reload a full page and the time no longer updates, although the main section of the page still changes.

Pjax uses pushState so the user won’t notice that AJAX requests are being made in the background. Each time pjax updates the page the URL in the address bar updates, the page’s title changes and the previous page is added to the browser’s history so that the back button works correctly. Pjax degrades gracefully too: if the user’s browser doesn’t support pushState or they’ve disabled JavaScript it will fall back to making a traditional HTTP request.

Integrating Pjax into a Rails Application

There are several ways we can integrate pjax into a Rails application and we’ll try two of them in this episode. The application we’ll be working with is shown below. It shows a list of products and clicking on a product reveals a sidebar showing some information about that product.

Currently when we click on the link the entire page reloads. To show how much of the page has changed the layout file and the page’s template both generate random numbers when they’re loaded. When both numbers change this shows that the entire page has been reloaded and this is what we currently see. We’ll use pjax now so that only the areas of the page that need to change are updated.

There’s a gem called pjax_rails by David Heinemeier Hansson that makes it easy to add pjax to a Rails 3.1 application and though it doesn’t quite fit the needs of our application we’ll try it anyway to show how it works. To install it we just add the pjax_rails gem to our /Gemfile and run bundle.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.1'
gem 'sqlite3'

# Gems used only for assets and not required
# in production environments by default.
group :assets do
  gem 'sass-rails',   '~> 3.1.4'
  gem 'coffee-rails', '~> 3.1.1'
  gem 'uglifier', '>= 1.0.3'
end

gem 'jquery-rails'
gem 'pjax_rails'

Once Bundler has finished we need to modify our application.js manifest file so that it loads pjax’s JavaScript.

/assets/javascripts/application.js

// This is a manifest file that'll be compiled into including all the files listed below.
// Add new JavaScript/Coffee code in separate files in this directory and they'll automatically
// be included in the compiled file accessible from http://example.com/assets/application.js
// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
// the compiled file.
//
//= require jquery
//= require jquery_ujs
//= require pjax
//= require_tree .

Finally we need to wrap the yield call in the layout file in a div with a data-pjax-container attribute.

/app/views/layouts/application.html.erb

<!DOCTYPE html>
<html>
  <head>
    <title><%= content_for?(:title) ? content_for(:title) : "Store" %></title>
    <%= stylesheet_link_tag    "application" %>
    <%= javascript_include_tag "application" %>
    <%= csrf_meta_tag %>
  </head>
  <body>
    <div id="container">
      <div class="layout_time">Layout random: <strong><%= rand(900)+100 %></strong></div>
      <% flash.each do |name, msg| %>
        <%= content_tag :div, msg, :id => "flash_#{name}" %>
      <% end %>
      <div data-pjax-container>
      <%= yield %>
      </div>
    </div>
  </body>
</html>

When we restart the server and reload our page now every link on the page will be pjax-enabled. When we click a link now the page doesn’t reload fully and we can see this as only the template’s random number changes. This is almost what we want but if we look closely we’ll see that the page’s title doesn’t change when we click on one of the links.

We can fix this by adding a title tag in the template. This is a little hacky and makes the page’s HTML invalid, but it does work.

/app/views/index.html.erb

<% content_for :title, @product ? @product.name : "Products" %>
<title><%= yield (:title) %></title>
<!-- Rest of page omitted -->

When we reload the page now the title changes when we click one of the links and we also have a fully-working back button and history. From the user’s perspective everything works as it did before but it feels a little faster. This is good but the pjax_rails gem is a little aggressive. Every link on the page is pjax-enabled by default but this isn’t really what we want in our application. Likewise the whole template is always updated when we click a link and there’s no way of restricting which parts of the page are updated. There is a way of disabling pjax for certain links but having to keep track of these can be awkward. If you have a simple application whose layout file always stays the same, though, then pjax-rails may well suit you, though.

It should be possible to use Rack middleware to make a more flexible solution and this is how Gert Goet’s rack-pjax gem works so we’ll replace pjax_rails with rack-pjax in our application. First we’ll replace the pjax_rails gem with rack-pjax in the Gemfile and run bundle again.

/Gemfile

# gem 'pjax_rails'
gem 'rack-pjax

Next we need to add the included Rack middleware to the application’s config file.

/config/application.rb

module Store
  class Application < Rails::Application 
    config.middleware.use Rack::Pjax
    # Other config commands omitted
  end
end

Rack-pjax doesn’t come with a jQuery plugin embedded so we’ll need to install this separately. We’ll create a vendor/assets/javascripts directory in our application and download the jquery.pjax.js file to it using curl.

terminal

$ mkdir -p vendor/assets/javascripts
$ curl https://raw.github.com/defunkt/jquery-pjax/master/jquery.pjax.js > vendor/assets/javascripts/jquery.pjax.js

We’ll need to include this file in our application’s JavaScript manifest file so we’ll replace pjax_rails’s JavaScript file with this one.

/assets/javascripts/application.js

//= require jquery
//= require jquery_ujs
//= require jquery.pjax
//= require_tree .

Unlike pjax_rails, rack-pjax doesn’t pjax-enable all links by default so we need to specify the ones to enable. These are all in pages in the ProductsController so we’ll do this in the products CoffeeScript file.

/app/assets/javascripts/products.js.coffee

jQuery ->
  $('.product a').pjax('[data-pjax-container]')

In this code we first make sure that the DOM has loaded then fetch the links that we want to enable. In our case this is any link inside a parent element with a product class. We then call pjax on them and specify what we want to update when the link is clicked.

With rack-pjax we no longer need to override the title element and so we can remove this from the index template. When we reload the page now it works as it did before; the template is updated when we click a link but not the layout and only the template’s random number is updated. The title is updated now, too, even though it’s not specified in the template because this is detected from the layout.

What’s really useful is that we can now move our data-pjax-container element anywhere we want. It no longer has to be placed around the yield call in the layout file. We’ll move it into the index template and wrap it around the product details section, i.e. the section that displays the details for a product.

/app/views/products/index.html.erb

<% content_for :title, @product ? @product.name : "Products" %>

<div class="template_time">Template random: <strong><%= rand(900)+100 %></strong></div>

<h1>Products</h1>

<% for product in @products %>
  <div class="product">
    <h2>
      <%= link_to product.name, :product_id => product %>
      <span class="price"><%= number_to_currency(product.price) %></span>
    </h2>
  </div>
<% end %>

<p><%= link_to "New Product", new_product_path %></p>

<div data-pjax-container>
  <% if @product %>
  <div id="product_details">
    <h3><%= @product.name %></h3>
    <dl>
      <dt>Price:</dt>
      <dd><%= number_to_currency(@product.price) %></dd>
      <dt>Released:</dt>
      <dd><%= @product.released_at.strftime("%B %e, %Y") %></dd>
      <dt>Category:</dt>
      <dd><%= @product.category %></dd>
    </dl>
    <p class="actions">
      <%= link_to "Edit", edit_product_path(@product) %> |
      <%= link_to "Destroy", @product, method: :delete, confirm: "Are you sure?" %>
    </p>
  </div>
  <% end %>
</div>

Now when we click a link only the side panel changes and neither of the random numbers changes.

If you’re curious about how this gem works then you should take a look at its source code. It’s really simple, being just one Ruby file of about fifty lines of code. Bear in mind though that the entire layout and template are still rendered by the server before rack-pjax decides which parts to send back to the client. If rendering the template is a big performance problem then you might be better off looking at an alternative solution, but for most application this should work perfectly.

That’s it for our episode on pjax. It’s a simple solution and well worth taking a look at if you think it might fit your application’s needs.