ASCIIcasts - Full Episode Feed

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.

Virtual Machines with Vagrant

Sun, 30 Oct 2011 10:54:48 +0000

As a Rails developer you’ll often find that your development environment is quite different from the production environment. Indeed it’s not unusual to develop an application on a different operating system from the one it will run on in production. Rails applications can also have a heavy set of dependencies that can be difficult to replicate across different machines.

Vagrant can help with this. It allows us to set up and manage virtual environments so we can set up a small Linux distribution inside our OS and run our application and all of its dependencies on a virtual machine that we can save to a portable package that we be easily shared with others.

Every Rails developer give Vagrant a try. At the least it will give you a better understanding of how to set up a production environment for your Rails apps. It’s also useful to use to set up a staging environment or even while developing an app.

Installing Virtual Box and Vagrant

Vagrant uses Oracle’s VirtualBox. If you don’t have it installed on your machine you’ll need to install it first. VirtualBox is available for Windows, OS X and Linux so whatever OS you’re running you should be able to find a suitable version. Once we’ve installed VirtualBox we can install Vagrant. This is a Ruby gem and we install it by running this command.

$ gem install vagrant

Adding a Box

The next step is to add a virtual machine, known as a box to Vagrant. There’s a long list of publicly available boxes at Vagrantbox.es and we can download one from there. We’ll use, ubuntu lucid 32, which is provided by the Vagrant site and which is based on Ubuntu Linux 10.04. To install the box we run vagrant box add, passing in a name and the URL of the box.

$ vagrant box add lucid32 http://files.vagrantup.com/lucid32.box
[vagrant] Downloading with Vagrant::Downloaders::HTTP...
[vagrant] Downloading box: http://files.vagrantup.com/lucid32.box
[vagrant] Extracting box...
[vagrant] Verifying box...
[vagrant] Cleaning up downloaded box...

Boxes can be fairly large (in the order of a few hundred megabytes) so they can take a while to download. If you’ve already downloaded one you can pass in a file URL instead to install from a local box file.

Once the box has downloaded and installed we can use it to set up our virtual environment. In Vagrant this is usually done for a specific project. We don’t have one so we’ll create a new one to work with, then move into its directory.

$ rails new todo
$ cd todo

We can create a virtual machine just for this application and its dependencies by running vagrant init and passing in the name of the box we want to use.

$ vagrant init lucid32
      create  Vagrantfile

All this command does is create a file called Vagrantfile. This file contains the configuration information for this application’s Vagrant box. By default all of the information is commented out, apart from the line that specifies which box to use.

/Vagrantfile

Vagrant::Config.run do |config|
  # All Vagrant configuration is done here. The most common configuration
  # options are documented and commented below. For a complete reference,
  # please see the online documentation at vagrantup.com.

  # Every Vagrant virtual environment requires a box to build off of.
  config.vm.box = "lucid32"

  # Rest of file omitted.
end

There are many other configuration options that we can specify here and its worth taking a minute to look through them all.

Starting up The Vagrant VM

Now it’s time for the magic. Running vagrant up will set up our virtual machine. This can take a few minutes but once it’s booted up we can SSH into it with

$ vagrant ssh

We’re now inside our Ubuntu virtual machine. This is a fairly barebones setup with very little installed on it, but there are a couple of things worthy of note. One is that it has a user called vagrant set up (and which we’re logged in as), the other is that we have sudo privileges that don’t require a password which is fine for our local development machine. Vagrant has also set up a shared directory at /vagrant that points to the directory where we have our Rails application.

Installing Our Application’s Dependencies

Our objective is to get our Rails application up and running on our virtual machine so we’re doing to have to set up its dependencies. First we’ll make sure we have Ruby and Sqlite installed. Our virtual machine already has Ruby 1.8.7 installed which has been done so that it can run Chef recipes.

Chef provides a way to automate server setup. To install Ruby 1.9 and Sqlite we could apply the necessary Chef recipes and they will be installed for us. Chef integrates nicely with Vagrant but it’s a big topic in itself and is something we’ll cover in a future episode. Instead we’ll set up our server without using Chef which will give us a better idea of how everything works together.

First we’ll use apt-get to make sure that all of our installed software is up to date.

$ sudo apt-get update

Once that has finished we’ll install some of the software we need: the build essentials, ZLib, Git and Sqlite3.

$ sudo apt-get install build-essential zlib1g-dev git-core sqlite3 libsqlite3-dev

All have left to install now is Ruby 1.9. We could install this from scratch or by using RVM but we’ll use something newer called rbenv. Using Vagrant means that we can experiment with tools such as this that we haven’t used before in a safe environment and, if we mess up, delete the virtual machine and start again.

To install rbenv in our virtual machine we just run the commands listed in section 2.1 of rbenv’s README. First we clone the repository into ~/.rbenv.

$ cd
$ git clone git://github.com/sstephenson/rbenv.git .rbenv

Next we add rbenv’s bin directory to our PATH and add the init command to our bash profile.

$ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile
$ echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

We’ll have to reload the bash profile for these changes to take effect.

$ source .bash_profile

We now have an rbenv command that we can use to manage our Ruby versions but still no way to install Ruby. We’ll use Ruby Build to do this. All we need to do is clone its Git repository, then move into its directory and run its install script.

$ git clone https://github.com/sstephenson/ruby-build.git
$ cd ruby-build
$ sudo ./install.sh

We can now use rbenv to install the current version of Ruby 1.9.2.

$ rbenv install 1.9.2-p290

This will take a while to run but when it finishes it will have successfully compiled Ruby 1.9.2. We’ll need to run rbenv rehash when ever we change the binaries like this and then we’ll run this command to make 1.9.2 the default version of Ruby on our virtual machine.

$ rbenv global 1.9.2-p290

When we check our version of Ruby now it’s 1.9.2 just like we want.

$ ruby -v
ruby 1.9.2p290 (2011-07-09 revision 32553) [i686-linux]

Installing Our Rails Application

Now that we have the correct version of Ruby installed we can work on getting our Rails application working. If we move to the shared directory our application is in and run bundle to install its dependencies we’ll hit a problem.

vagrant@lucid32:~$ cd /vagrant/
vagrant@lucid32:/vagrant$ bundle
bundle: command not found

All we need to do to fix this is install the Bundler gem.

$ gem install bundler

Once this gem has installed we’ll need to run rbenv rehash again to set up the bundle executable. We can now run bundle to install our application’s gems.

If we try to start our application’s server now, it will throw a error complaining that it couldn’t find a JavaScript runtime. This makes sense as Rails 3.1 requires a JavaScript runtime and Ubuntu doesn’t have one by default. The quick solution to this is to add a gem called therubyracer to our application’s Gemfile and run bundle on our virtual machine. This will install the V8 JavaScript engine.

/Gemfile

gem 'therubyracer'

Once the gem has installed we can try running our server again.

$ bundle exec rails s

This time it starts successfully and our application is up and running on port 3000. We can’t view it in a browser, though, as it’s running on the virtual machine. We have to tell Vagrant to forward the port to our machine and we do this by modifying our project’s Vagrantfile. We need to uncomment the line below, change the name to something more suitable tell it to forward port 3000 on the virtual machine to the same port on our local machine.

/Vagrantfile

config.vm.forward_port "rails", 3000, 3000

Having changed the configuration we’ll need to exit out of our Vagrant shell by running exit in the VM and then reload the virtual machine by running vagrant reload. This will shutdown our virtual machine and then reload it. Once it’s reloaded we can SSH into it again.

$ vagrant ssh

Then on the virtual machine we can move to our application’s directory and start up the server again.

vagrant@lucid32:~$ cd /vagrant
vagrant@lucid32:/vagrant$ bundle exec rails s

This boots up the server again but we can now access it from our local machine.

As our Rails application is shared with Vagrant any changes we make to it will be reflected in our virtual machine. If we modify the default page at /public/index.html and reload the page the changes will be shown immediately.

/public/index.html

<h2>You&rsquo;re riding Ruby on Rails on Vagrant!</h2>

Other Vagrant Commands

Vagrant provides a number of commands to help us manage our virtual machine. To get the current status of our VM we can run vagrant status.

$ vagrant status
Current VM states:

default                  running

The VM is running. To stop this VM, you can run `vagrant halt` to
shut it down forcefully, or you can run `vagrant suspend` to simply
suspend the virtual machine. In either case, to restart it again,
simply run `vagrant up`.

To temporarily stop and restart the machine we can use suspend and resume.

$ vagrant suspend
[default] Saving VM state and suspending execution...

$ vagrant resume
[default] Resuming suspended VM...
[default] Booting VM...
[default] Waiting for VM to boot. This can take a few minutes.
[default] VM booted and ready for use!

To complete shut down the VM we can use vagrant halt. We’ll then need to use vagrant up again to bring that machine back up.

One of the most useful commands is vagrant package. This will package up the virtual machine in its current state into a file called package.box. We can then share and distribute this file or use it to quickly recreate our virtual machine. If we use vagrant destroy to delete our virtual machine we can then restore it with the same vagrant box add command we used to set up our virtual machine in the first place.

That’s it for our episode on Vagrant. It’s a great solution for taking your Rails apps’ runtime dependencies and isolating them in a virtualized environment that can be packaged up and distributed among other developers, used to simulate the production server or used as a staging server. Vagrant becomes even more useful when used in combination with Chef and we’ll be covering that in a future episode.

SOAP With Savon

Sun, 30 Oct 2011 10:33:51 +0000

There comes a time in every web developer’s life when they have to communicate with a SOAP API; when simple Ruby code needs to talk with complex .Net and Java applications. Thankfully there’s help for this potentially unpleasant task. Savon is a Ruby gem written by Daniel Harrington that provides a nice Ruby interface for communicating with SOAP APIs. In this episode we’ll show you how it works.

ZipCode Lookups

Below is a page from an application with a simple form that takes a Zip code. We want users to be able to enter a Zip code and have information it returned.

As you can see our application doesn’t work yet. We have placeholders for the information but nothing is shown as we need to communicate with an external Web Service to get this information. We’ll get this information from the WebserviceX.NET website. This site has a SOAP API that can provide a lot of useful information such as stock market quotes, currency conversion, weather information and a whole lot more and we’ll use it to fetch information about a Zip code. The site has a page with a form we can use to test the web service. If we enter a valid zip code in the form we’ll set some XML returned containing data about that Zip code. If, for example, we enter 90210 we’ll get this response.

<NewDataSet>
  <Table>
    <CITY>Beverly Hills</CITY>
    <STATE>CA</STATE>
    <ZIP>90210</ZIP>
    <AREA_CODE>310</AREA_CODE>
    <TIME_ZONE>P</TIME_ZONE>
  </Table>
</NewDataSet>

Using soapUI To Test SOAP calls

Before we jump right in and use a SOAP API in an application it’s a good idea to experiment with it a little to make sure that it works the way we expect it to. To help with this we’ll use a Java application called soapUI that we can use to test Web Services. Once we’ve installed it we can run it and create a new project. When we do we’ll be shown a dialog box that asks for a WSDL URL, among other things. The page we viewed before has this information and the URL we need to enter is http://www.webservicex.net/uszip.asmx?WSDL.

A WSDL is like a blueprint and it tells us they actions that are available at that URL. Once we’ve entered the WSDL URL into soapUI we’ll see a list of the actions. If we expand the GetInfoByZip action and click the “Request 1” field that’s revealed we’ll see the XML that’s required for making a request.

This is the information we need to get from soapUI so that we can compare it to Savon as we use it in our Rails application. If we replace the question mark in the <web:USZip> element with a real Zip code and click the green arrow we see the XML response.

Getting Started With Savon

Now that we have a way of testing SOAP requests we can start using Savon in our application. As is usual when installing a gem we do this by adding the gem to the Gemfile and then running 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 'savon'

To get a feel for how Savon works we’ll experiment with it in the console. The first thing we need to do is create a new Savon::Client, passing it the URL we want to to communicate with.

> client = Savon::Client.new("http://www.webservicex.net/uszip.asmx?WSDL")

We can provide a block here if we want to provide additional configuration, but for our purposes this is enough. Next we’ll get a list of the actions.

> client.wsdl.soap_actions
HTTPI executes HTTP GET using the net_http adapter => [:get_info_by_zip, :get_info_by_city, :get_info_by_state, :get_info_by_area_code]

One of the actions that is returned is just the one we’re looking for. (Note that Savon has changed the name from GetInfoByZip to the more Ruby-like get_info_by_zip).

We make a request by calling client.request and passing in the action we want to call. We can also pass in a namespace as an optional first argument. If we look at the XML that was generated by soapUI we’ll see that a web namespace is used so we’ll need to pass that in. Finally we’ll need to add some options. Again, we could use a block here, but instead we’ll pass in a body option. This option takes a hash and it’s here where we pass the parameters in that we saw in the XML request. In soapUI the Zip code was passed in in a <web:USZip> element. We’ve already specified the namespace so we just need to pass in the Zip code as us_zip. (Again, Savon changes the capitalization of the parameter.

> client.request :web, :get_info_by_zip, body: { us_zip: "90210" }

We’ll see a large response from this request. This usually goes to the development log file so if we need to debug SOAP calls we can look there to see what the request and response were. The important parts of the response are the request XML and response XML and if we look at the response we’ll see that it doesn’t contain the information we were expecting.

<?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetInfoByZIPResponse xmlns="http://www.webserviceX.NET" />
  </soap:Body>
</soap:Envelope>

It looks like something’s wrong with our request. The problem in this case is that the casr of the us_zip code parameter is incorrect. Parameters are case sensitive and if we look at the relevant part of the request XML we’ll see that the USZip parameter was sent as usZip instead.

<web:usZip>90210</web:usZip>

By default Savon uses lowerCamelCase for parameters, but if we pass the name in as a string instead of as a symbol the capitalization will be preserved.

> client.request :web, :get_info_by_zip, body: { "USZip" => "90210" }

When we send the request this time the response contains the information we need.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetInfoByZIPResponse xmlns="http://www.webserviceX.NET">
      <GetInfoByZIPResult>
        <NewDataSet xmlns="">
          <Table>
            <CITY>Beverly Hills</CITY>
            <STATE>CA</STATE>
            <ZIP>90210</ZIP>
            <AREA_CODE>310</AREA_CODE>
            <TIME_ZONE>P</TIME_ZONE>
          </Table>
        </NewDataSet>
      </GetInfoByZIPResult>
    </GetInfoByZIPResponse>
  </soap:Body>
</soap:Envelope>

The last command we sent returns a response object and we can assign this to a variable in the console by using an underscore to get the last thing returned.

> response = _

Calling to_hash on this object gives us a Ruby hash that’s easy to parse.

> response.to_hash
 => {:get_info_by_zip_response=> {:get_info_by_zip_result=> {:new_data_set=>{:table=> {:city=>"Beverly Hills", :state=>"CA", :zip=>"90210", :area_code=>"310", :time_zone=>"P"}, :@xmlns=>""}}, :@xmlns=>"http://www.webserviceX.NET"}}

The information we need is fairly deeply nested in the hash but we can still get at it fairly easily. Now that we know how Savon works we can start to use it in our Rails application.

Using Savon in a Rails Application

Our application has a ZipCode model class. This isn’t an ActiveRecord model just a Ruby class with some attributes and an initializer that takes a Zip code.

/app/models/zip_code.rb

class ZipCode
  attr_reader :state, :city, :area_code, :time_zone

  def initialize(zip)
  end
end

When a new ZipCode object is instantiated we want to set the attributes with values from the SOAP call. The code we’ll need to add to the class is similar to that we ran in the console.

/app/models/zip_code.rb

class ZipCode
  attr_reader :state, :city, :area_code, :time_zone

  def initialize(zip)
    client = Savon::Client.new("http://www.webservicex.net/uszip.asmx?WSDL")
    response = client.request :web, :get_info_by_zip, body: { "USZip" => zip }
    data = data = response.to_hash[:get_info_by_zip_response][:get_info_by_zip_result][:new_data_set][:table]
    @state = data[:state]
    @city = data[:city]
    @area_code = data[:area_code]
    @time_zone = data[:time_zone]
  end
end

This code makes a request and calls to_hash on the response. We then go into that deeply-nested hash and set the class’s attributes to the relevant parts of it. We can try this out now. When we enter a Zip code and click “Lookup” the SOAP call is made and we’ll see the information on the page so our code is working.

Handling Errors

We’ll need to modify out code so that it handles errors. As it stands if we enter an invalid Zip code and try to look it up the application raises an exception as the response doesn’t have the deeply-nested hash we’re expecting.

One way to handle these cases is to check that the response is successful before trying to set the attributes. We could use response.success? to check this and while this is useful, it won’t help in this case as the response is successful when an invalid Zip code is entered, the problem is that the response is empty.

To help us here we can use Savon’s to_array method here instead of to_hash. We can pass this a list of hash keys and rather than throwing an exception if the nesting we’re looking for doesn’t exist it will return an empty array. As an array is returned we need to call first to get the results we want. If there are no results we’ll get nil so we can check for that before setting the attributes.

/app/models/zip_code.rb

def initialize(zip)
  client = Savon::Client.new("http://www.webservicex.net/uszip.asmx?WSDL")
  response = client.request :web, :get_info_by_zip, body: { "USZip" => zip }
  if response.success?
    data = response.to_array(:get_info_by_zip_response, :get_info_by_zip_result, :new_data_set, :table).first
    if data
      @state = data[:state]
      @city = data[:city]
      @area_code = data[:area_code]
      @time_zone = data[:time_zone]
    end
  end
end

If we reload the page now we’ll see an empty result rather than an exception.

There’s more work we can do here to show an error message when an invalid Zip code is entered but we won’t do that here.

Some Final Tips

We’ll finish this episode with a couple of tips. If you find yourself having to use strings a lot because the first part of a tag name is capitalized you can add this line of code to our application to make the tags use UpperCamelCase rather than the default lowerCamelCase. If the API you’re talking to uses this kind of casing this means that you can use symbols instead of strings in the arguments.

Gyoku.convert_symbols_to :camelcase

A WSDL file shouldn’t change often so so it’s a good idea to cache it rather than downloading it every time. We can download the WSDL file, store it locally and then use a file reference when we create a new Savon::Client rather than a web reference.

That’s it for our episode on Savon. Savon makes it much easier to communicate with a SOAP API. If you use it in your applications there are a couple of related projects that you might find useful. The first of these is Savon Model. This provides a nice DSL for setting up the client inside a class and it would probably work well inside our ZipCode class and allow us to clean up the code there.

The other project is Savon Spec. This can help in testing by mocking the SOAP requests. This is fine for lower-level tests but to test thoroughly you should also have some higher level integration tests that test hitting that actual API. This way if the API changes the tests will break. The VCR gem can help greatly with this and there’s more information about VCR in this week’s pro episode.

Billing With Stripe

Fri, 14 Oct 2011 12:59:53 +0000

If you ever need to process credit card payments through your Rails applications you should take a look at Stripe. Stripe is a payment gateway that is easy to set up and which is very developer friendly. It only charges fees on a per-transaction basis and these are very reasonable. There are no monthly fees or other hidden costs. (By the way we’re not being paid to say this).

Stripe is currently only available in the United States so you’ll need an account at a U.S. bank if you want to use it in your applications. International support is being worked on, however, and should be available soon. This doesn’t mean that you can’t bill international customers, the only restriction is that the seller must be in the U.S.

Adding Stripe to a Rails Application

In this episode we’ll use Stripe to add recurring payments to a Rails application. The application we’ll use is a site that sells Llama Kisses. Why? Well Ryan Bates grew up on a llama ranch and missed out on the opportunity to sell llama kisses then so he’s making up for lost time now.

Most of the application is already written. There are four different plans and users can sign up for any one of them to create a subscription. There’s only an email field on the sign-up page right now and when we fill that field in and submit the form a new subscription will be created. So that we can take payments through Stripe we’ll add some more fields for credit card details.

Getting started with Stripe is easy. It we visit stripe.com and click the “Get Started with Stripe” button we’ll be taken to a page where we can process test transactions. We can also do this from the command line with curl. If we copy the example code from the “Getting Started” page and run it in a terminal window we should see some JSON returned.

$ curl https://api.stripe.com/v1/charges \
>   -u zVyGPfdmfhSGpHAxhFiJT7kFnHeSi9ZN: \
>   -d amount=100 \
>   -d currency=usd \
>   -d 'card[number]=4242424242424242' \
>   -d 'card[exp_month]=5' \
>   -d 'card[exp_year]=2012' \
>   -d 'description=test charge IFnFXZgdZk'

{
  "amount": 100,
  "created": 1318355241,
  "currency": "usd",
  "description": "test charge IFnFXZgdZk",
  "fee": 0,
  "id": "ch_oVfzHImv8sN5TV",
  "livemode": false,
  "object": "charge",
  "paid": true,
  "refunded": false,
  "card": {
    "country": "US",
    "exp_month": 5,
    "exp_year": 2012,
    "last4": "4242",
    "object": "card",
    "type": "Visa"
  }
}

Whether we run a test transaction through the site or through the terminal window the recent payments are shown in the dashboard at the bottom of Stripe’s management page.

Creating an account is easy; all we need to is enter an email address and a password on the management page. Once we’ve done that we can visit the page for our account where we’ll see, amongst other things, the API keys we’ll need to communicate with Stripe’s REST API. Stripe also provide a Ruby gem that makes using this API in Rails applications much easier. We’ll install this gem in our application now. As with most Ruby gems we do this by adding a reference to it the Gemfile and then running 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 'stripe'

Stripe needs two API keys so that it knows which account it’s working with. We’ll store these in a new stripe.rb initializer file in the application’s /config/initializers directory. The keys we need to store here are the secret test key that’s shown in our account page and the public API key here. We’ll store the public key in a constant as it isn’t used by the Ruby gem, only in views and JavaScript. This key should hold the value from the publishable test key on our Stripe account page.

/config/initializers/stripe.rb

Stripe.api_key = "5J7dr36JmNpLrXXFwAXChdRzZZwLyCHV"
STRIPE_PUBLIC_KEY = "pk_B1SaM15nXXruDU3g2D6uns2kJeu9m"

As this file contains sensitive information it’s a good idea to add it to the application’s .gitignore file so that it isn’t included in the repository. Also, as we’ll use different keys on the production site we don’t want this file being accidentally copied over to the production codebase.

Adding Stripe’s JavaScript and The API Key

When a user submits their credit card information in a form the credit card information goes directly to Stripe’s server and not to our application at all. This makes it a lot easier to get PCI compliance. If we look at the example form on Stripe’s API page we’ll see that none of its fields have a name attribute. This means that when the form is submitted these fields aren’t passed to our application’s server. Instead they’ll read by some JavaScript code that is triggered when a user submits the form.

To use Stripe in our application we need to include a JavaScript file from Stripe’s server. Then we set our publishable key and add some JavaScript that will fire when the form containing the credit card fields is submitted. This JavaScript will generate a token based on the credit card information from the form.

We’ll add Stripe’s JavaScript file in our application’s layout file. It needs to be placed before the application’s own JavaScript file. We could add some code that checks if the current page is the checkout page and only adds the script when this is the case, but we won’t do that here. We also need to make our public key available to JavaScript and we’ll do this the same way that Rails adds its CSRF key, in a meta tag in the head of the page.

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

<!DOCTYPE html>
<html>
<head>
  <title>Llama Kisses</title>
  <%= stylesheet_link_tag    "application" %>
  <%= javascript_include_tag "https://js.stripe.com/v1/", "application" %>
  <%= csrf_meta_tags %>
  <%= tag :meta, :name => "stripe-key", ↵ 
    :content => STRIPE_PUBLIC_KEY %>
</head>
<body>
  <!-- Body omitted -->
</body>
</html>

Adding Credit Card Fields To The Subscription Form

Next we’ll add the credit card fields to the subscription form. The form currently contains a hidden field that holds the id of the selected plan and a text field for an email address. We’ll add more fields for a credit card number, security code and expiration date.

/app/views/subscriptions/new.html.erb

<%= form_for @subscription do |f| %>
  <% if @subscription.errors.any? %>
    <div class="error_messages">
      <h2><%= pluralize(@subscription.errors.count, "error") %> prohibited this subscription from being saved:</h2>
      <ul>
      <% @subscription.errors.full_messages.each do |msg| %>
        <li><%= msg %></li>
      <% end %>
      </ul>
    </div>
  <% end %>
  <%= f.hidden_field :plan_id %>
  <div class="field">
    <%= f.label :email %>
    <%= f.text_field :email %>
  </div>  
  <div class="field">
      <%= label_tag :card_number, "Credit Card Number " %>
      <%= text_field_tag :card_number, nil, name: nil %>
  </div>
  <div class="field">
      <%= label_tag :card_code, "Security Code on Card (CVV)" %>
      <%= text_field_tag :card_code, nil, name: nil %>
  </div>
  <div class="field">
    <%= label_tag :card_month, "Card Expiration" %>
    <%= select_month nil, {add_month_numbers_true: true}, {name: nil, id: "card_month"}%>
    <%= select_year nil, {start_year: Date.today.year, end_year: Date.today.year+15}, {name: nil, id: "card_year"}%>
  </div>
  <div class="actions"><%= f.submit "Subscribe" %></div>
<% end %>

We’ve added two text fields to the form, one for a credit card number, and one for the security code and also two dropdowns for the expiry date. There are a few things worth noting about the fields we’ve added. For the credit card name and security code we’ve used label_tag and text_field_tag instead of going through the form builder as these new fields aren’t attributes on our Subscription model. We don’t want them to be submitted back to the server at all so we’ve also specified a nil name for each field. Similarly for the expiry date fields we’re using select_month and select_year for the expiry date and specifying the id manually so that we don’t have to deal with the one that Rails generates.

When we reload the page the new fields are shown in the form.

Next we want to write the JavaScript that fires when the form is submitted. This script will submit the credit card information to Stripe and submit the token that it receives back from Stripe through the form. As our application is written in Rails 3.1 we’ll write this code in CoffeeScript in the subscriptions.js.coffee file.

/app/assets/javascripts/subscriptions.js.coffee

jQuery ->
  Stripe.setPublishableKey($('meta[name="stripe-key"]').attr('content'))
  subscription.setupForm()

subscription =
  setupForm: ->
    $('#new_subscription').submit ->
      $('input[type=submit]').attr('disabled', true)
      subscription.processCard()
  
  processCard: ->
    card =
      number: $('#card_number').val()
      cvc: $('#card_code').val()
      expMonth: $('#card_month').val()
      expYear: $('#card_year').val()
    Stripe.createToken(card, subscription.handleStripeResponse)
  
  handleStripeResponse: (status, response) ->
    if status == 200
      alert(response.id)
    else
	 alert(response.error.message)

This code should only run after the page’s DOM has loaded and so it’s all wrapped in the jQuery function. The first thing it does is set up Stripe by specifying the publishable key. The key’s value is read from the meta tag we added in the application’s layout file. We fetch it by looking for a meta tag with a name attribute that has a value of stripe and reading that tag’s content attribute. The rest of the logic is handled through a subscription object. This object has a function called setupForm that will do all of the work.

Next we create the subscription object and give it a setupForm function. In this function we get the subscription form by its id and add a callback that fires when the form’s submit event fires. When the form is submitted we disable the submit button to stop the it from being accidentally submitted again by setting the button’s disabled attribute to true. Then we call a processCard function and return false so that the form isn’t submitted.

The processCard function creates an object representing the credit card’s values in the format that Stripe expects and reads the appropriate values for each field from the form’s fields using val(). The next line is the important one. We call Stripe.createToken with two arguments. The first is the card object that we’ve just created (we can also pass in an optional amount here). The second is a function that will handle the response from Stripe, which happens asynchronously. We’ll pass in subscription.handleStripeResponse here.

The handleStripeResponse function takes two arguments: a status and a response. If the status has a value of 200 then the transaction succeeded and we’ll have a response token stored in response.id. For now we’ll just alert the response value so that we can see what it is. If the status isn’t 200 then an error has occurred so we’ll alert the error message.

We can give our new form a try out now. If we reload the new subscription form and submit valid card details we get a response token back.

If we enter an invalid card number we’ll get an error message returned instead.

Handling The Response

Now that we know that the calls to Stripe are being processed correctly we’ll improve the code that handles the error messages. Instead of showing an alert we’ll show the error message on the page in a div with and id of stripe_error and re-enable the submit button so that the user can enter their details again.

/app/assets/javascripts/subscriptions.js.coffee

handleStripeResponse: (status, response) ->
  if status == 200
    alert(response.id)
  else
    $('#stripe_error').text(response.error.message)
    $('input[type=submit]').attr('disabled', false)

Having done this we’ll need to add the div to the view.

/app/views/subscriptions/new.html.erb

<%= form_for @subscription do |f| %>
  <!-- Form fields omitted -->
  <div id="stripe_error">
    <noscript>JavaScript is not enabled and is required for this form. First enable it in your web browser settings.</noscript>
  </div>
  <div class="actions"><%= f.submit "Subscribe" %></div>
<% end %>

We’ve placed a noscript element in the div so that an error is shown if anyone tries to use the form in a browser that doesn’t have JavaScript enabled. When we reload the page and submit the form with an invalid credit card number again we’ll see the error message in the stripe_error div instead of an alert.

Next we’ll change the code that handles successful transactions. Instead of displaying the response token in an alert we’ll add it to a new hidden field in the form and then submit the form. We’ll add a new hidden field in the view and call it stripe_card_token.

/app/views/subscriptions/new.html.erb

<%= f.hidden_field :stripe_card_token %>

There’s no stripe_card_token field in the subscriptions table in the database so we’ll need to add this field as a virtual attribute in our Subscription model.

/app/models/subscription.rb

class Subscription < ActiveRecord::Base
  belongs_to :plan
  validates_presence_of :plan_id
  validates_presence_of :email
  
  attr_accessible :stripe_card_token
end

Back in our CoffeeScript file we’ll replace the alert with code that sets the value of our new hidden field to the value of the response token and then submits the form. We submit the form by calling submit directly on the form. Doing this bypasses the onsubmit callback so that the form is POSTed back to the server.

/app/assets/javascripts/subscriptions.js.coffee

handleStripeResponse: (status, response) ->
  if status == 200
    $('#subscription_stripe_card_token').val(response.id)
    $('#new_subscription')[0].submit()
  else
    $('#stripe_error').text(response.error.message)
    $('input[type=submit]').attr('disabled', false)

The form is submitted to the SubscriptionsController’s create action and the token will be passed in to a new Subscription. We could handle the payment through a before_create callback here but instead we’ll create a new method in the Subscription model called save_with_payment and do it there. Before we write this method we’ll replace the call to save with save_with_payment.

/app/controllers/subscription_controller.rb

def create
  @subscription = Subscription.new(params[:subscription])
  if @subscription.save_with_payment
    redirect_to @subscription, :notice => "Thank you for ↵ 
      subscribing!"
  else
    render :new
  end
end

The save_with_payment method will use the stripe gem to handle the payment. We could use the response token to make a payment using the Stripe::Charge.create method but we don’t want to do this as the response token can only be used once and we want to make a recurring payment. Instead we’ll use the token to create a new Stripe::Customer. We can then assign a plan to that customer with recurring payments. Stripe will then automatically handle recurring payments for us. All of this is covered in Stripe’s excellent API documentation.

Before we make any changes to our Subscription model we’ll go to our Stripe account and set up some plans so that it knows how to handle our recurring payments. We’ll add four plans with names and ids that match the plans in our Rails application.

Back in our Subscription model we can now write the save_with_payment method.

/app/models/subscription.rb

class Subscription < ActiveRecord::Base
  belongs_to :plan
  validates_presence_of :plan_id
  validates_presence_of :email
  
  attr_accessor :stripe_card_token
  
  def save_with_payment
    if valid?
      customer = Stripe::Customer.create(description:email, ↵ 
        plan: plan_id, card: stripe_card_token)
      self.stripe_customer_token = customer.id
      save!
    end
  end
end

This method checks that the model is valid and if it is it will create a new Stripe::Customer, passing it the customer’s email address as a description, the plan_id and the stripe_card_token. Stripe will create a new id for the customer which we’ll need to save to the database. We’ll save it in to a new stripe_customer_token field. We’ll create a migration for this field then run rake db:migrate to add it to the database.

$ rails g migration add_stripe_to_subscriptions stripe_customer_token:string

We’re ready now to test making a payment. If we go to the new subscription page, enter valid credit card details and click “Subscribe” the token and customer will be created in the background and the form will be submitted. If we visit the payments page for our Stripe account we’ll see the new payment listed for the price of the plan. This is a recurring payment and will be taken every month.

Handling Errors

The call to Stripe::Customer.create might raise an exception if some of the information passed isn’t valid. This can happen, for example, if a user submits the form without JavaScript enabled in their browser so that the stripe_card_token wasn’t generated. It’s a good idea to use rescue to handle these cases. Stripe will raise an InvalidRequestError in these cases and we can catch these, log them, add a validation error to the page and then show the form again.

/app/models/subscription.rb

def save_with_payment
  if valid?
    customer = Stripe::Customer.create(description:email, ↵
      plan: plan_id, card: stripe_card_token)
    self.stripe_customer_token = customer.id
    save!
  end
rescue Stripe::InvalidRequestError => e
  logger.error "Stripe error while creating customer: #{e.mesage}"
  errors.add :base, "There was a problem with your credit card."
end

We also need to handle errors on form fields unrelated to credit card information, such as the email field on our form, better. Currently if we try to submit a subscription with no email address but with valid credit card details we’ll receive a proper token from Stripe but instead of being redirected to the page that shows a successful login we’ll be shown the form again with an email validation error.

In these cases we should hide the credit card fields as we already have a valid token. We can do this by modifying the view so that it hides the fields if a stripe_card_token exists for the subscription and shows a message instead.

/app/views/subscriptions/new.html.erb

<div class="field">
  <%= f.label :email %>
  <%= f.text_field :email %>
</div>  
<% if @subscription.stripe_card_token %>
  Credit card has been provided
<% else %>
  <div class="field">
    <%= label_tag :card_number, "Credit Card Number " %>
    <%= text_field_tag :card_number, nil, name: nil %>
  </div>
  <div class="field">
    <%= label_tag :card_code, "Security Code on Card (CVV)" %>
    <%= text_field_tag :card_code, nil, name: nil %>
  </div>
  <div class="field">
    <%= label_tag :card_month, "Card Expiration" %>
    <%= select_month nil, {add_month_numbers_true: true}, ↵ 
      {name: nil, id: "card_month"}%>
    <%= select_year nil, {start_year: Date.today.year, ↵
      end_year: Date.today.year+15}, ↵
      {name: nil, id: "card_year"} %>
  </div>
</div>
<% end %>

We’ll also need to update the setupForm function in our subscriptions CoffeeScript file so that it doesn’t try to process the card again when a user submits the form in this case. We can do this by checking to see if the card number field exists on the form. If it doesn’t then it’s been hidden because the credit card information has already been processed. In this case we won’t process it again and we’ll return true so that the form is submitted.

/app/assets/javascripts/subscriptions.js.coffee

setupForm: ->
  $('#new_subscription').submit ->
    $('input[type=submit]').attr('disabled', true)
    if $('#card_number').length
      subscription.processCard()
      false
    else
      true

If we submit the form with valid credit card details but with a missing email address now the credit card fields will be hidden.

If we fill in the email field and submit the form again our subscription will be successful and the payment will be processed by Stripe.

WebHooks

One feature of Stripe that we haven’t covered is WebHooks. These allow us to provide a callback URL that Stripe will call when a given event fires. For example if a recurring payment fails we want to be told about this so that we can suspend that user’s account. We can then inform them so that they can update their credit card information. Speaking of which, our application still needs a way for users to update their card information, cancel their subscriptions and so on, but we won’t be covering that here.

Stripe has a number of features we haven’t covered in this episode, but hopefully we’ve given you enough to get started. Stripe is a great way to process credit card payments. Unfortunately it’s unavailable outside the U.S. for now, but international support is promised soon.

Draper

Wed, 05 Oct 2011 17:42:31 +0000

In this episode we’ll take a look a Draper, a gem that lets us add decorators to a Rails application’s views much like a presenter pattern. If you find that you have a lot of complex view logic in your templates and helper methods Draper can help to clean up this code by taking a more object-orientated approach. We’ll show you how it works in this episode.

The application we’ll be working with is shown below. It has a user profile page that shows various pieces of information about a given user including their avatar, full name, username, a short biography in Markdown and links to a website and Twitter feed. If a user has supplied a website the avatar and full name will link to that site.

The page seems fairly simple but we also have to handle those users who haven’t entered so much data such as “MrMystery”.

This user has only entered a username so we display that in place of their full name, show a default avatar and some placeholder text for the other fields. This makes the template for this page more complex, with many if conditions needed to handle users with different amounts of information. We could make this template much cleaner if we could move some of this logic out to somewhere else.

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

<div id="profile">
  <%= link_to_if @user.url.present?, ↵ 
  image_tag("avatars/#{avatar_name(@user)}", class: "avatar"), ↵
  @user.url %>
  <h1><%= link_to_if @user.url.present?, ↵
    (@user.full_name.present? ? @user.full_name : ↵
    @user.username), @user.url %></h1>
  <dl>
    <dt>Username:</dt>
    <dd><%= @user.username %></dd>
    <dt>Member Since:</dt>
    <dd><%= @user.member_since %></dd>
    <dt>Website:</dt>
    <dd>
    <% if @user.url.present? %>
      <%= link_to @user.url, @user.url %>
    <% else %>
      <span class="none">None given</span>
    <% end %>
    </dd>
    <dt>Twitter:</dt>
    <dd>
    <% if @user.twitter_name.present? %>
      <%= link_to @user.twitter_name, ↵
  "http://twitter.com/#{@user.twitter_name}" %>
    <% else %>
      <span class="none">None given</span>
    <% end %>
    </dd>
    <dt>Bio:</dt>
    <dd>
    <% if @user.bio.present? %>
      <%=raw Redcarpet.new(@user.bio, :hard_wrap, :filter_html, ↵
        :autolink).to_html %>
    <% else %>
      <span class="none">None given</span>
    <% end %>
    </dd>
  </dl>
</div>

As this logic is view-related we can’t really extract it out into the model. One solution for this would be to use helper methods. We already use one called image_tag in this template to render the avatar. Let’s take a look at it.

/app/helpers/users_helper.rb

module UsersHelper
  def avatar_name(user)
    if user.avatar_image_name.present?
      user.avatar_image_name
    else
      "default.png"
    end
  end
end

This helper method determines whether the current user has an avatar and returns the name of a default image if they don’t. We could extract more of the logic from the view into helper methods but the problem with is that they’re simple methods in a global namespace; there’s nothing object-orientated about them.

Installing Draper

This scenario is a good case for using a presenter, or a decorator as Draper refers to them, so let’s add it to our application. The Draper gem is installed in the usual way, by adding it to the Gemfile then running bundle.

/Gemfile

source 'http://rubygems.org'

gem 'rails', '3.1.0'
gem 'sqlite3'


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

gem 'jquery-rails'
gem 'redcarpet'

gem 'draper'

Once Draper has installed we’ll create a decorator for our User model by running the draper:decorator generator.

$ rails g draper:decorator user
      create  app/decorators
      create  app/decorators/application_decorator.rb
      create  app/decorators/user_decorator.rb

As this is our first decorator an application_decorator will also be generated. Any decorators we generate inherit from ApplicationDecorator so we can place any functionality that we want to share across decorators there.

The UserDecorator class is fairly straightforward, consisting mainly of comments that explain how it works. We’ll dive right in and start using it to clean up our templates.

Tidying Up The Profile Page

To use Draper in our profile page we first need to make a change to the show action in the UsersController. This action currently fetches a User in the usual way.

/app/controllers/users_controller.rb

class UsersController < ApplicationController
  def index
    @users = User.all
  end

  def show
    @user = User.find(params[:id])
  end
end

We need to wrap this user in our decorator which we do by replacing User.find with UserDecorator.find.

/app/controllers/users_controller.rb

def show
  @user = UserDecorator.find(params[:id])
end

This code will now return a UserDecorator instance that wraps the User record and delegates all methods to it by default (more on this later). The action will still work as it did before even though we’re working with a UserDecorator instead of a User. Now we can start to clean up our views and we’ll begin with the code that renders the user’s avatar.

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

<%= link_to_if @user.url.present?, image_tag( ↵ 
  "avatars/#{avatar_name(@user)}", class: "avatar"), @user.url %>

We’ll replace this in the view with this:

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

<%= @user.avatar %>

This code will look for an avatar method in the UserDecorator which we’ll write next. There are some things we’ll need to be aware of when writing this method. Whenever we call a helper method from a decorator, such as our link_to_if method, we need to call it through the h method (this stands for “helpers”). When we want to reference the model we call model instead of, in this case, @user.

The code we’ve copied from the the view into avatar calls the avatar_name helper method. As we’re calling avatar_name from our decorator we’ll move it there from the UsersHelper class. Now that we have the method in the same class we don’t need to pass it a User and we can replace its calls to user with model.

/app/decorators/user_decorator.rb

class UserDecorator < ApplicationDecorator
  decorates :user
  
  def avatar
    h.link_to_if model.url.present?, h.image_tag("avatars/#{avatar_name}", class: "avatar"), model.url
  end
  
  private
  def avatar_name
    if model.avatar_image_name.present?
      model.avatar_image_name
    else
      "default.png"
    end
  end
end

Next we’ll tidy up the code that render’s the user’s name. We’ll replace this code in the view:

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

<h1><%= link_to_if @user.url.present?, (@user.full_name.present? ? @user.full_name : @user.username), @user.url %></h1>

with this:

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

<h1><%= @user.linked_name %></h1>

We’ll need to write the linked_name method in the UserDecorator. There are similarities between the code we’ve taken from the template and the avatar method we wrote earlier; both of these render a link whose content is dependent on whether the user’s url if it’s present. As we’re in a class it’s easy to refactor this duplication out.

To handle the link creation we’ll create a new private method called site_link, which takes the content as a parameter. We can then call this method in both the avatar and linked_name methods to tidy them up. As before we replace any calls to @user in the linked_name with model. With all that done our decorator now looks like this.

app/decorators/user_decorator.rb

class UserDecorator < ApplicationDecorator
  decorates :user
  
  def avatar
    site_link h.image_tag("avatars/#{avatar_name}", ↵
      class: "avatar")
  end
  
  def linked_name
    site_link(model.full_name.present? ? model.full_name : ↵
      model.username)
  end
  
  private
  def site_link(content)
    h.link_to_if model.url.present?, content, model.url
  end
  
  def avatar_name
    if model.avatar_image_name.present?
      model.avatar_image_name
    else
      "default.png"
    end
  end
end

If we reload a user’s profile page now it should look just as it did before.

Our template is already looking a lot cleaner but there’s more we can do yet. Next we’ll refactor a larger chunk of the view code, the code that renders a link to the user’s website.

/app/views/user/show.html.erb

<dt>Website:</dt>
<dd>
  <% if @user.url.present? %>
    <%= link_to @user.url, @user.url %>
  <% else %>
    <span class="none">None given</span>
  <% end %>
</dd>

We’ll replace this with:

/app/views/user/show.html.erb

<dt>Website:</dt>
<dd><%= @user.website %></dd>

As before we’ll create a method in the decorator class. We can see from the code that we’ve removed from the view that if the user has no url then some HTML is rendered. We could just return this as a string but we don’t want to put raw HTML into a Ruby string. Another solution would be to move the code into a partial and to render that, but as we only to output a single HTML element it makes more sense to use the content_tag helper method.

/app/decorators/user_decorator.rb

def website
  if model.url.present?
    h.link_to model.url, model.url
  else
    h.content_tag :span, "None given", class: "none"
  end  
end

We can do a similar thing for the two parts of the template that render the Twitter information and the user’s biography. We won’t show the details of that here, but after we’ve made the changes our view code will looks a lot cleaner.

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

<div id="profile">
  <%= @user.avatar %>
  <h1><%= @user.linked_name %></h1>
  <dl>
    <dt>Username:</dt>
    <dd><%= @user.username %></dd>
    <dt>Member Since:</dt>
    <dd><%= @user.member_since %></dd>
    <dt>Website:</dt>
    <dd><%= @user.website %></dd>
    <dt>Twitter:</dt>
    <dd><%= @user.twitter %></dd>
    <dt>Bio:</dt>
    <dd><%= @user.bio %></dd>
  </dl>
</div>

The new twitter and bio methods in the decorator look like this:

/app/decorators/user_decorator.rb

def website
  if model.url.present?
    h.link_to model.url, model.url
  else
    h.content_tag :span, "None given", class: "none"
  end  
end

def twitter
  if model.twitter_name.present?
    h.link_to model.twitter_name, ↵  
      "http://twitter.com/#{model.twitter_name}"
  else
    h.content_tag :span, "None given", class: "none"
  end
end
  
def bio
  if model.bio.present?
    Redcarpet.new(model.bio, :hard_wrap, :filter_html, ↵
 		:autolink).to_html.html_safe
  else
    h.content_tag :span, "None given", class: "none"
  end
end

The two new methods look very similar to each other and also to the website method we wrote earlier. There’s a fair amount of duplication between the three methods, especially in each else clause, so it would be good if we could extract this part out into its own method.

We can use a block to help with this. We’ll extract the else clause out into its own method which we’ll call handle_none. We’ll pass the value we want to check the presence of to this method and also a block. If the value is present the code in the block will be executed, otherwise the span tag will be rendered. We can then use this handle_none to tidy up the website, twitter and bio methods.

/app/decorators/user_decorator.rb

def website
  handle_none model.url do
    h.link_to model.url, model.url
  end  
end
  
def twitter
  handle_none model.twitter_name do
    h.link_to model.twitter_name, ↵ 
      "http://twitter.com/#{model.twitter_name}"
  end
end
  
def bio
  handle_none model.bio do
    Redcarpet.new(model.bio, :hard_wrap, :filter_html, ↵
      :autolink).to_html.html_safe
  end
end
  
private
def handle_none(value)
  if value.present?
    yield
  else
    h.content_tag :span, "None given", class: "none"
  end
end

Another change we could make it to extract the Markdown rendering into the ApplicationDecorator so that we can call it from any other decorators we might make. We’ll create a new markdown method there now that will render any text we pass to it.

/app/decorators/application_decorator.rb

class ApplicationDecorator < Draper::Base
  def markdown(text)
    Redcarpet.new(text, :hard_wrap, :filter_html, ↵ 
      :autolink).to_html.html_safe
  end
end

Now in the UserDecorator we can now modify the bio method so that it calls markdown.

/app/decorators/user_decorator.rb

def bio
  handle_none model.bio do
    markdown(model.bio)
  end
end

Modifying The Model

Now that we have the decorator in place it’s a good idea to look through the model layer for any view-related code that we can move up to the relevant decorator. For example in our User model we have a member_since method that formats the user’s created_at time. This code can be considered view-related as all it does is return a formatted string so we’ll move it to the decorator.

/app/models/user.rb

class User < ActiveRecord::Base
  def member_since
    created_at.strftime("%B %e, %Y")
  end
end

All we need to do is move the method to the decorator and prepend model before created_at.

/app/decorators/user_decorator.rb

def member_since
  model.created_at.strftime("%B %e, %Y")
end

Restricting Access To The Model With The `allows` Method

While we’re modifying the UserDecorator there’s one more feature of Draper that we’ll demonstrate: the allows method. As it stands the UserDecorator will delegate all of its methods to the User object, but we can choose which methods are delegated to the User model by using allows and passing it the name of the methods we want to delegate.

/app/decorators/user_decorator.rb

class UserDecorator < ApplicationDecorator
  decorates :user
  allows :username

  # Other methods omitted
end

We’ll allow only username to be delegated and this way only the username method will be delegated down to the User model. This is the only method we need to delegate as it’s the only method that’s called in the view that doesn’t come from the decorator. This gives us more control over the decorator’s interface.

Now that we’re done with refactoring everything out to the decorator we’ll try loading a user’s profile page again to make sure that everything still looks the same.

It does. We can even check our other user and that still looks the same too but our view code is much cleaner.

By using a decorator our show template has been reduced from 1050 bytes in 34 lines to 382 bytes in 16 lines, a reduction in size of almost two thirds. It looks much cleaner too and we’ve made it much easier to edit should we want to change the layout of the page.

ASCIIcasts - Full Episode Feed

OmniAuth Identity

How Our Application Currently Works

Adding OmniAuth Identity to an Application

Creating Custom Registration and Login Forms

In-place Editing

Best In Place

Adding Best In Place to Our Application

Storing Changes

Handling Other Types of Data

Contributing to Open Source

Fork It!

Running The Tests

Making The Changes

Getting Started With Spree

Installing Spree

A First Look At Spree

Customizing Spree

Customizing Individual Parts of The Site

Mercury Editor

Installing Mercury

Making Pages Editable

Adding Editable Areas

Saving Changes

Going Further

Playing With PJAX

Integrating Pjax into a Rails Application

Virtual Machines with Vagrant

Installing Virtual Box and Vagrant

Adding a Box

Starting up The Vagrant VM

Installing Our Application’s Dependencies

Installing Our Rails Application

Other Vagrant Commands

SOAP With Savon

ZipCode Lookups

Using soapUI To Test SOAP calls

Getting Started With Savon

Using Savon in a Rails Application

Handling Errors

Some Final Tips

Billing With Stripe

Adding Stripe to a Rails Application

Adding Stripe’s JavaScript and The API Key

Adding Credit Card Fields To The Subscription Form

Handling The Response

Handling Errors

WebHooks

Draper

Installing Draper

Tidying Up The Profile Page

Modifying The Model

Restricting Access To The Model With The allows Method

Restricting Access To The Model With The `allows` Method