Tutorial of Twitter Bootstrap with ActiveAdmin and SpanishSlang gem

Environment

Rails 3.2.3. Ruby 1.9.2p320. RVM 1.13.6. MAC OSX Lion. Textmate. iTerm2

The app lives here

It takes some time to load because it is hosted on the free Heroku.

Slang App

Slang App Admin

References

Objective

Create an app that uses Twitter Bootstrap on the front end and ActiveAdmin on the backend.

This ActiveAdmin bootstrap tutorial shows how you can put together a small prototype and it can be customized to anything you want. It is good for demo purposes but it shouldn’t be used for a production application.

The app has 3 components:

Active Admin
Twitter Bootstrap
SpanishSlang gem

SpanishSlang is a gem I am building. The code is not here but the objective of the gem is to create a seed file with Spanish slang categorized by countries.

For this article we will just add the slang words from the front end after installing Twitter Bootstrap.

Spanish Slang Models

We will use scaffolding.

Although I don’t like to do this and I think it inhibits learning. I will use to speed up the presentation of my main objectives Twitter Bootstrap and ActiveAdmin.

Create a new app and then a scaffold called “palabra” (word) that has attributes “nombre” (name) and “puntaje” (score). This last attribute will be used to give a score to the word. I think the future of the app would allow anybody to come in and give a score to a word.

Another scaffold called “dedonde” (where from) has attributes “ciudad” (city) and “pais” (country)

$ rails new slang
$ cd slang
$ rails g scaffold palabra nombre puntaje:integer --skip-stylesheets
$ rails g scaffold dedonde ciudad pais --skip-stylesheets
$ rake db:migrate

Gemfile add Twitter Bootstrap gem

Add this gem inside the group :assets do

gem 'twitter-bootstrap-rails'

Then run:

$ bundle

Install Twitter Bootstrap

$ rails g bootstrap:install

Twitter bootstrap layouts

Fixed layout

It uses the default 940px-wide, centered layout provided by a single:

<div class="container">

Fluid layout

It gives flexible page structure and a left hand sidebar using:

<div class="container-fluid">

Using fixed layout

Contain the body of the application layout with a div class. Inside the body we can add this:

<div class="container">
    <div class="row">
        <div class="span9"><%= yield %></div>
        <div class="span3">
            <h2> About Slang </h2>
            This app is about Spanish Slang. It will teach the basics of Street Spanish in 
            every Spanish-speaking country
        </div>
    </div>
</div>

Adding a top navigation bar

Inside the application layout within the body. The following can be added before the previous container.

<div class="navbar navbar-fixed-top">
    <div class="navbar-inner">
      <div class="container">
        <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </a>
        <a class="brand" href="#">Spanish Slang</a>
        <div class="nav-collapse">
          <ul class="nav">
            <li><%= link_to "Busca Palabras", palabras_path %></li>
            <li><%= link_to "Busca Ciudad o Pais", dedondes_path %></li>
          </ul>
        </div>
      </div>
    </div>
  </div>

Add some padding after the top of the page

Go to app>assets>stylesheets>bootstrap_and_override.css.less

At the top of the file in between the 2 imports (bootstrap and responsive) add:

body { padding-top: 60px; }

Add some Palabras to the app

Add some words through the front end.

Add a theme to the app

$ rails g bootstrap:themed palabras -f
$ rails g bootstrap:themed dedondes -f

Installing ActiveAdmin

Go to the Gemfile and add

gem 'activeadmin'

Then run:

$ bundle
$ rails g active_admin:install
$ rake db:migrate

Login to Admin

localhost:3000/admin

user: admin@example.com

pwd: password

Add the resources

$ rails g active_admin:resource palabra
$ rails g active_admin:resource dedonde

Customize the Palabra view of the Admin

Installing Active Admin creates a folder called “admin” inside the app. I think all the defaults are hard coded inside the gem so when you open up a view it doesn’t have any code.

To customize anything you have to add new code into these files.

For example:

Open the file “palabras.rb” inside the “admin” folder, it shows only this:

ActiveAdmin.register Palabra do

end

To customize we have to add code in there. For example:

index do
    column :nombre
    column :puntaje
end

To show the edit/delete links add this before the end, after column :puntaje

default_actions

Customize the dashboard

Go to the “dashboards.rb” inside admin and update this code:

ActiveAdmin::Dashboards.build do
  section "Palabras Con Mayor Puntaje" do
    table_for Palabra.order("puntaje desc").limit(5) do
      column :nombre
      column :puntaje
    end
    strong {link_to "Ver todas las palabras", admin_palabras_path }
  end

end

Review the CSS file from the front end

Active Admin uses its CSS for all pages when it is installed. To change this go to the file

application.css

And rename it to

application.css.scss

Then go to the file and remove all this:

/*
 * This is a manifest file that'll be compiled into application.css, which will include all the files
 * listed below.
 *
 * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
 * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
 *
 * You're free to add application-wide styles to this file and they'll appear at the top of the
 * compiled file, but it's generally better to create a new file per style scope.
 *
 *= require_self
 *= require_tree .
*/

Then add this line:

@import "bootstrap_and_overrides";

Deploying the app to Heroku

Update the Gemfile

Place these 2 gems outside of any group.

gem 'twitter-bootstrap-rails'
gem 'sass-rails',   '~> 3.2.3'

Run Bundle

$ bundle

Initiate a git repository and first commit

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

Add the ‘pg’ PostgreSQL Gem to Gemfile, to deploy to Heroku

group :development, :test do gem 'sqlite3' end
group :production do gem 'pg' end

(Before adding the previous lines. Remove the line that says gem ‘sqlite3’. In other words sqlite3 should only appear on the line described above )

Install the gems added to Gemfile and Commit to Git

$ bundle install
$ git add .
$ git commit -am "Updated Gemfile"

Setup Heroku Gem

$ gem install heroku

Deploy to Heroku using Rails 3.2

For Cedar apps, use: heroku run rake db:migrate

$ heroku create --stack cedar
$ git push heroku master
$ heroku run rake db:migrate

Pushing local data from DB into Heroku

$ gem install taps
$ heroku db:push

Open Heroku app

$ heroku open

More ActiveAdmin customization

Adding AdminUsers

When you install ActiveAdmin, by default it creates a model called admin_user.

ActiveAdmin uses Resources which map models to administration panels. Run the following code:

$ rails generate active_admin:resource AdminUser

NOTE: Be careful with the original tutorial on ActiveAdmin. On the code shown on the tutorial it uses a font that is light gray and you don’t see when they put underscores

The previous code generates a file inside app/admin called admin_users.rb. If you go to the admin interface, a new link on the top bar shows up.

Customizing AdminUsers

The defaults that show up on the view are hard coded into the gem. To customize the view you have to add code.

Go here: app/admin/admin_users.rb

And add this code:

index do
    column :email
    column :current_sign_in_at
    column :last_sign_in_at
    column :sign_in_count
    default_actions
end

In the previous code “default_actions” shows the CRUD options. “Index” is a method that allows you to customize the view and you specify the columns that you want to show.

When you create a new Admin user it has a lot of fields that we don’t need. According to the documentation and by looking at the routes file it says that ActiveAdmin uses the gem Devise for authentication. The only field that we need is email while the rest should be done by the gem.

The routes file looks like this:

Slang::Application.routes.draw do

  ActiveAdmin.routes(self)

  devise_for :admin_users, ActiveAdmin::Devise.config

  root :to => 'palabras#index'

  resources :dedondes

  resources :palabras
end

Customizing the form to create new Admin Users

Go here: app/admin/admin_users.rb

And add this code:

form do |f|
    f.inputs "Admin Details" do
        f.input :email
    end
    f.buttons
end

This form uses a gem called Formtastic. In the previous code f.inputs creates a field set and to create a field you need to pass a symbol with the name of the model’s column. f.buttons creates the Submit and Cancel buttons.

So far the form does not allow you to create a password. The documentation says that the Devise gem is supposed to send you an email with a link. And this link allows you to set a password.

Setting up mail server

Go here config/environments/development.rb

Add this line and then restart the server:

config.action_mailer.default_url_options = { :host => 'localhost:3000' }

Sending email on local development after creating an Admin user

When we updated the form, there is only one field for email. The gem Devise is not going to let us create a record without a password.

We need to go to the AdminUser model and add some code:

after_create { |admin| admin.send_reset_password_instructions }

def password_required?
    new_record? ? false : super
end

Although I don’t understand this code too well. The documentation says that:

after_create is a callback that makes sure Devise sends the user a link to create a new password.

password_required? allows you to create a user without creating a password.

Adding a new Admin user

Start the server and add a new admin user. Enter an email and look at the server log. It should have something that looks like it sent an email. This contains a link that can be pasted in another browser so you can set the password for that user.

Sending email on production Heroku with SendGrid

This section is out of the scope of this article. I just put here what I found but setting up ActionMailer turned out to be harder than I thought. So I just added some information that I found.

Reference: SendGrid on Heroku

SendGrid starter is free for apps sending up to 200 messages a day. To enable the add-on, run the following:

$ heroku addons:add sendgrid:starter

Previously we created a heroku app running on the cedar stack. The SendGrid documentation says:

"SendGrid requires you to setup the From: address when sending emails. Without it, their SMTP servers will throw exceptions."

It also says to look into this:

"We encourage developers to take a look at Pony for something simpler than ActionMailer, yet more convenient than net/smtp."

Configure ActionMailer

Try this tutorial: ActionMailer in Rails 3

Tom Ordonez