Update: This tutorial is way out of date. If you want to create a modern (ie. 2015) app, please use a generator like RailsBricks.

With the recent release of web-app-theme providing Rails 3.1 support, it’s time once again for me to write a tutorial on how to earn money from cheap clients who can’t afford designers.

For reference, the previous tutorial can be read here.

crud screen

Every Rails developer knows how to create a Rails app. It’s easy as

rails new APP-NAME-HERE

But how many know how to create an app from scratch that looks good enough to sell to clients i.e. with slick design, authentication, authorization, and all that? Sure, there are tutorials out there that cover those components, but most of them cover them only in isolation from each other. A quick tutorial containing multiple components at a time would be a valuable resource to anyone planning to start a new app.

As the resident dilettante in these parts, I’ve decided to create such a tutorial based on a recent demo I made for a prospective client.

This post will discuss how to create a Rails 3.1 application that looks good enough to sell to clients (of course, YMMV) while still having components found in “professional” apps. This tutorial will cover the following:

  • Andrea Franz’s web-app-theme gem – this gem generates themes for your web app (hence the name). The demo and the list of available themes can be found on this page.
  • Devise – our authentication module. Authlogic‘s fine, but I find Devise’s approach less obtrusive.
  • Haml – replaces Erb. Not perfect (e.g. screws up with inline a tags) but the drastic decrease in code makes passing it up difficult.
  • Rspec – replaces Test::Unit. Only setup will be covered in this post, actual usage is left to the reader.
  • Kaminari – gem for pagination. We’re going to use it in place of the previous gem will_paginate

Rest of the tutorial is below the cut.

Let’s start by creating our new app with no testing framework and with MySQL as the database:

$ rails new pro-template-app-31 -d mysql -T

Now would be a good time to edit the .gitignore file to exclude files you don’t want to add to Git. Rails 3 already provides some good defaults, but if you want more possible entries there are samples available over at Github.

Once done, it’s time to make the initial commit.

$ git init
$ git add .
$ git commit -am "initial commit"

Setup Gemfile

Now is time to add the needed gems to Gemfile.

source 'http://rubygems.org'

gem 'rails', '3.1.0'
gem 'mysql2'
gem 'haml'
gem 'devise'
gem 'kaminari'

group :development, :test do
  gem 'capybara'
  gem 'rspec-rails'
  gem 'haml-rails'
  gem 'hpricot'
  gem 'ruby_parser'
  gem 'web-app-theme', '~> 0.8.0'

I’ve already explained most of the gems above at the beginning of this post. The only thing worth noting would be the addition of hpricot and ruby_parser, both of which are needed by web-app-theme to generate haml files.

Run “bundle install” to install the gems. After the gems are installed, all of our generators will now use Rspec instead of Test::Unit, and it can now generate Haml instead of Erb.

Generate home page

Let’s try out our app first by creating a new root page to replace the default.

$ rails g controller home index
$ rm public/index.html

Then edit the config/routes.rb:

ProTemplateApp31::Application.routes.draw do
  root :to => "home#index"

Before starting the app, don’t forget to create the database:

$ rake db:create

Start the server.

initial root page

all pictures are clickable BTW

Generate theme with web-app-theme

Here comes the fun part.

$ rails g web_app_theme:theme --engine=haml --app-name="My Latest Web App"

This will generate the layout files using the default theme in haml whose title would be “My Latest Web App”.

(In case you want to use a different theme, add --theme="THEME-NAME" to this and some of the later commands.)

Delete the default layout generated for the rails app:

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

then refresh the page.

themed root page

It looks good, but I think we’re better off using the sample text page from the demo site.

$ rails g web_app_theme:themed home --themed-type=text --engine=haml
$ mv app/views/home/show.html.haml app/views/home/index.html.haml

fixed home page

Tweaking web-app-theme v0.8.0

Before we continue, let’s first fix some problems with web-app-theme 0.8.0 when used with Rails 3.1.

First, generate a copy of the current theme to your app so that you could modify them.

$ rails g web_app_theme:assets

Now for the tweaks:

  • JavaScript tag doesn’t point to the one generated by the asset pipeline. This is the reason why the sign-out links won’t work if you followed the previous tutorial. Fix here.
  • The stylesheet for alert messages are still defined under “error” class. Fix here.
  • For some odd reason, the images for buttons were moved to the spec folder. You can bring them back by manually copying them to your project’s web-app-theme asset folder. Here’s one way of doing it:

$ cp $(bundle show web-app-theme)/spec/dummy/public/images/* app/assets/images/web-app-theme/ -r

Add Devise authentication

Let’s install Devise and create our User model in the process.

$ rails g devise:install
$ rails g devise user

We also need to customize the login screen. To do this, we must first enable scoped views for Devise.

Then let’s generate the sign-in/sign-out layout:

$ rails g web_app_theme:theme sign --layout-type=sign --engine=haml --app-name="My Latest Web App"

Then let’s add the following files to the config/application.rb file to change the layout for sign-in/sign-up:

    config.to_prepare do
      Devise::SessionsController.layout "sign"
      Devise::RegistrationsController.layout "sign"

At this point, you could generate the Devise views via

$ rails g devise:views

but the generated files are in ERb, not to mention that the layout for the sign-in/sign-up pages are different from what web-app-theme expects.

To save you from the hassle of copying the layout of those two pages, you could just copy-paste what I did here and here.

Restart the server, run rake db:migrate, and try going to the login site (/users/sign_in).

login page

Clicking “Sign up”:

sign up page

Finishing touches to Devise

Let’s do some finishing touches to the UI.

First, modify the layout such that the logout button actually works.

Now to test if Devise really works. Add the before_filter :authenticate_user! to home_controller.rb to kick us out to the login screen if we’re not logged in. While we’re at it, modify the said controller to set tell sign-out to redirect to the sign-in page.

login error

Create a test user via the rails console.

$ rails c

User.create :email => "test@example.com", :password => "123456", :password_confirmation => "123456"

You should now be able to login and logout.

login success

logout success

Theming a CRUD module

Now let’s show how to add the web-app-theme to a new CRUD module. To simplify things, we’ll use the ultra-stupidsimple blog demo.

$ rails g scaffold blog_entry subject:string content:text publish_at:datetime
$ rake db:migrate

Overwrite the generated files by running web-app-theme’s generator:

$ rails g web_app_theme:themed blog_entries --will-paginate --engine=haml

Since we’re using kaminari, we need to modify the controller and index page accordingly.

We will also have to modify the kaminari template to match the CSS. First generate the view files via

$ rails g kaminari:views default -e haml

then modify the files to match the layout with the demo page. Here’s one way of doing it.

We also need to modify the layout to take into account the new module.

crud screen

After that, you can still do a couple of minor tweaks to the pages to deal with their “auto-generated” jagged edges. Then you can also apply the error message fix (don’t forget to restart the server) and test it with the screens.

fixed crud

And that’s it. The complete code generated above can be found at Github.

UPDATE 5/3/12: Changes to make things work in production

Looks like this thing doesn’t work in production. Please see the latest commit in Github (1, 2) for my fixes.

I’ve changed the layout stylesheets to use application instead of web_app_theme and also changed app/assets/stylesheets/web-app-theme/themes/default/style.css to an ERb file using asset_path to point to the precompiled assets.

There’s also a bug in Rails 3.1.0 which requires a change in the production settings. You can choose to either apply that fix, or simply upgrade to a more recent version of Rails 3.1.

Tagged with →  
Share →

35 Responses to Starting a “professional” Rails 3.1 app with Web App Theme, Devise, and Kaminari

  1. […] Starting a “professional” Rails app with Haml, Rspec, Devise, and Web App Theme Jan 3 Brain Dumps, Software Engineering Update: Tutorial for Rails 3.1 here! […]

  2. Maily says:

    Nice article. It’s a shame you have to go through so much effort to “fix” everything…would be much nicer if web-app-theme didn’t require so much handholding. Regardless, well done. Thanks!

  3. […] Starting a “professional” Rails 3.1 app with Web App Theme, Devise, and Kaminari (tags: ruby rails via:zite) […]

  4. Sam Vincent says:

    You may also be interested in building apps with ActiveAdmin (http://activeadmin.info/). It uses the same gems mentioned here minus the themes.

    You can quickly build up an application that’s designed to be shippable to customers.

  5. Dinooz says:

    Great post… really enjoy it but have a problem with the web_app_theme generator =(

    C:\dino\rails3\pro-template-app-31>rails g web_app_theme:theme –engine=haml –a
    pp-name=”My Latest Web App”
    Could not find generator web_app_theme:theme.