(be warned that it dumps ALL databases. This can get huge uncompressed)

#!/bin/sh
# Isam (Biodegradablegeek.com) public domain 12/28/2008
# Basic BASH script to dump and compress a MySQL dump
 
out=sequel_`date +'%m%d%Y_%M%S'`.sql
dest=/bx/
 
function e {
  echo -e "n** $1"
}
 
e "Dumping SQL file ($out). May take awhile..."
#echo "oh snap" > $out
sudo mysqldump -u root -p --all-databases > $out
if [ $? -ne 0 ]; then
  e "MySQL dump failed. Check that server is up and your username/pass"
  exit 7
fi
 
e "Uncompressed SQL file size"
du -hs $out
 
e "Compressing SQL file"
gz=$out.tar.gz
tar -zvvcf $gz $out
rt=$?
 
if [ $rt -ne 0 ]; then
  e "tar failed (error=$rt). Will NOT remove uncompressed SQL file"
else
  e "Removing uncompressed SQL file"
  rm -f $out
  out=$gz
 
  e "Compressed SQL file size"
  du -hs $out
fi
 
e "Moving shit to '$dest'"
sudo mv $out $dest

BackThatSqlUp.sh

Seed data is data that the app is dependent on. It is data that has to exist if you were to wipe the database clean and reload your schema. Some examples would be a list of cities/states, a list of categories, or the initial ‘admin’ user account.

Most people looking at this thread want seed data rather than to populate their database with test/generated content. For the latter, you can go the route below or try Forgery

—

This is a response to the email I’ve been getting asking me how to use fixtures to load data into a database.

You want to create dummy entries in your Rails app, either for testing, for development, or for production, to make your site appear popular. Whatever the reason, populating your database can be done easily using fixtures.

While rake/fixtures/migrations can get a lot more complex, this will be a brief introductory example.

Initial App setup

$ rails characters
$ cd characters/

Edit config/database.yml – We only need a development database. So open up PHPMyAdmin or the MySQL command shell and:

mysql> CREATE DATABASE characters_development;
Query OK, 1 row affected (0.00 sec)

(I’m assuming you’re using MySQL. You can use anything; SQLite, Postgres, etc..)

Create a model and a table in the database (using a migration)

$ script/generate model Character
      exists  app/models/
      exists  test/unit/
      exists  test/fixtures/
      create  app/models/character.rb
      ....
 
$ vim db/migrate/001_create_characters.rb

Sexy migration:

class CreateCharacters < ActiveRecord::Migration
  def self.up
    create_table :characters do |t|
      t.string  :name, :alias, :motto
      t.timestamps
    end
  end
 
  def self.down
    drop_table :characters
  end
end

Now migrate development (default environment):

$ rake db:migrate

Create the characters fixture

$ vim test/fixtures/characters.yml

This is a YAML file. It is easy to read and easy to edit. (One may also use the CSV format, extension .csv).

Some notes:

• Each model has a corresponding fixture file with the same name in the test/fixtures/ path in your app’s root directory.
• Each ‘fixture’ is a record in the database table, and consists of a label, and then values for each field (i.e., name, age, etc..).
• Optional fields can be skipped. They will default to either NULL, or their default value set in the database.
• The id doesn’t need to be specified. It will be auto-incremented automatically, but be careful of conflicts if you’re specifying the ID for some fixtures and not others.
• Whitespace matters. Make it purty.
• You may embed Ruby code in the fixture file, in both the YAML and CSV fixture formats. (i.e., <% f() -%> or created_at: <%= Time.now %>)
• To load fixtures, you use rake db:fixtures:load. This loads the fixtures into your current environment (can be set via RAILS_ENV shell var or in config/environment.rb).One thing that might be confusing is the fact that fixtures reside in test/. Many people believe that fixtures can only be used in the test environment, but this is not the case.
• When a fixture are loaded, any data previously in the table will be wiped out. You don’t need to fear altering or losing your test data when testing (i.e., destroy methods, …), just reload the fixtures. In the test environment, fixtures may be loaded before each test case is run by using the fixtures method (fixtures :employees, :orders, …). Keep in mind that you’re using a freshly loaded fixtures between every case method (if you’re loading).

This is what our fixture file should look like. I will dissect it below:

riddler:
  name: Edward Nashton
  alias: Riddler
  motto: Riddle me this, riddle me that
 
pp:
  name: Peter Parker
  alias: Spiderman
  motto: One for JJ
  created_at: <%= Time.now %>
  updated_at: <%= Time.now %>
 
JILL:
  id: 101
  name: Jill Valentine
  motto: Im a member of S*T*A*R*S
 
dan_forden:
  name: Dan Forden
  motto: Toasty!
 
hotness:
  name: Sorceress
  motto: Time is mana
 
Airplane:
  name: Steve McCroskey
  motto: Looks like I picked the wrong week to quit sniffing glue.

Let’s examine the first fixture:

riddler:
  name: Edward Nashton
  alias: Riddler
  motto: Riddle me this, riddle me that

riddler:

This is a name for the fixture. It begins at the beginning of the line, and it doesn’t matter what you call it. That information is not saved in the database and you might never use it. Ideally, names should be descriptive. You may also just go generic, “person1, person2, person3″ etc.

When using the CSV format, fixture names are generated automatically and are in this format:

model_name-counter

In our example above, our fixtures would be named character-1, character-2, etc.

  name: Edward Nashton
  alias: Riddler
  motto: Riddle me this, riddle me that

These three are the values this fixture (record) will have in the database. They go under the fixture name, tabbed or spaced evenly. When going on to the next fixture, just leave a blank line.

The above is like doing this:

>> r = Character.new
>> r.name = 'Edward Nashton'
>> r.alias = 'Riddler'
>> r.motto = 'Riddle me this, riddle me that'
>> r.save

id, created_at and updated_at are optional, but may be specified. Keep in mind that this file is going to be preprocessed with Ruby, so you may embed Ruby code (ERb) anywhere in the file.

Load Fixture into Development Database

This loads fixtures into the current RAILS_ENV, which, by default, is development.

$ rake db:fixtures:load

If you check your database now, you will find the fixtures you just loaded residing in the specific table. Let’s poke at this table in the Rails console.

$ script/console
>> them = Character.find(:all)
=> [#> them[0].name
=> Edward Nashton
 
>> them[0].alias
=> Riddler
 
>> them[0].motto
=> Riddle me this, riddle me that

See these links for more info:

External links

• Fixtures Just Got a Whole Lot Easier
• Rails Fixture Tips
• The Lo-Down on Fixtures
• Fixtures in Rails 2.0
• Migration Related Rake Commands (Rake Cheatsheet)

I create a new rb file in lib/ (you can put your files in a sub-directory or anywhere ‘load’ can find them), then write the data I want inserted into the database in a new function in that file. I do so exactly as I would insert data in Rails. Model.create, Model.new, etc…

I then get into the Rails console (ruby script/console) and do load ‘file.rb’ and simply call the function. The database used will vary according to the environment you’re in (test, development, etc). Using ‘load’ every time you call your function(s) is preferred. Load will keep reloading the file (as opposed to ‘require’ which only reads a file once), staying up to date with edits you’re making to the file. For example, in the console:

>> load ‘funk.rb’; add_default_settings

(funk.rb is in /lib/ and add_default_settings is a function in that file)

As of 2.x, Rails now has rake db:migrate:reset and db:migrate:redo, which sends you down one migration and then back up to the current migration (or you can decide how many hops to take back using STEP=n). This is great, especially for tasks like populating a database.

So why don’t I use migrations? I do, but sometimes, especially in a proof-of-concept or throw-away app, I find it faster to skip the proper methods and write up a quick function. If you think that’s bad, you should see my lingering Python addiction. Sometimes I catch myself metaprogramming Ruby code in Python.

This short tutorial will be beneficial for you if database relationships and keywords like belongs_to and has_many confuse you, or if you’re trying to find out how relationships are implemented in Rails. As we create a small demonstration project, you’ll see that one beauty of Rails is how it does most of the work gluing everything together, after you’ve supplied it with information about your database’s structure.

But first — why bother learning about relationships? Very simply, they eliminate a major problem called an update anomaly, and they will probably save you disk space. Having info repeated in multiple entries can be problematic. How would you update a mass misspelling? Would you even notice a misspelled entry? Database normalization and multiple intertwined tables (via relationships) can curb this problem. Fortunately, ActiveRecord makes this easy.

For example, if you store the name and location of all your users in the same database table, you might be wasting disk space by having the same information repeated in multiple entries. You would be wasting a lot of space if your clam-cake-vendor-review site has hundreds of users living in “the State of Rhode Island and Providence Plantations.” This can be eliminated by having the locations tied to unique IDs in their own table, and associated to a user by their ID. This also makes renaming a location easy. Changing “the State of Rhode Island and Providence Plantations” to “Ocean State” is only done in one location, once.

Rather than going over all possible types of relationships here, I will be covering the very basics; Enough to help you grasp the main idea and see how it is implemented in Rails. Let’s begin by designing a simple project.

Project Description

Let’s design a basic musician database. Each artist will be one individual with a name, age, and list of songs (not albums). Each song will have a title, duration and fit under one genre. This design is overly simplified and far from realistic. For simplicity’s sake, we are ignoring the fact that an artist may consist of several individuals and may have multiple albums containing multiple songs, and each song, artist and album can fit under a mesh of genres. It might have a tough time competing with MusicBrainz or Last.fm, but it should be sufficient enough for our purpose.

Go Go Go

Ruby on Rails and your database software (I use MySQL, but SQLite/PostgreSQL work fine) should be installed and functional. For help installing Rails, see the official site and the official Wiki.

(If using an editor such as vim with rails.vim, you may substitute those commands and shortcuts for the console commands I use here)

In the directory you want your project to reside, create a Rails framework named themusic:

1
2
3
4
5
6
7
8

$ rails themusic
    create
    create app/controllers
    create app/helpers
    create app/models
    create app/views/layouts
    create app/environments
    ... omitted ...

Head into the newly created themusic directory and open config/database.yml using your favorite text editor. This file tells Rails what database software you’re using and how it can access it. Notice that this file is divided into three parts (environments): Development, test and production. Rails has the ability to use different databases and even database software for each environment. We will stick in the development environment.

In development, any changes you make to the code are immediate – not requiring a server restart to take effect – and errors spit out a detailed stack trace. The trade off? Performance takes a hit.

Fill in your database login information (you’ll likely just have to put in your password) before saving and closing the file. Create a new database named themusic_development. I use PHPMyAdmin, but this can be done in MySQL using the commandline:

1
2
3
4
5
6
7
8

<pre>
$ mysql -u username -h localhost -p
Enter password: (type pass and hit Enter)
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1984
 
mysql> CREATE DATABASE themusic_development;
Query OK, 1 row affected (0.04 sec)

Identifying Entities and Attributes

An entity is any object you are required to keep information on. Examples of entities include customers, orders, departments and items. How many entities are we keeping track of in our example app? Three: Artist, song and genre. Keep in mind that things you don't need to store data on are not entities. If your business doesn't require that you keep track of user or customer information, then they don't have to be entities. Identifying entities isn't always straightforward, and it's not uncommon to alter your app after the initial design phase, so don't sweat this too much right now; Just follow along.

Each entity has attributes. A person entity might have attributes such as name and DOB. If we were writing a stock inventory system, each item entity might have a price, manufacturer, description, and so forth. In our example, we have the following entities and attributes:

• Artist: Has a name, age and songs.
• Song: Has a title, duration and fits under one artist and one genre.
• Genre: Each has a name, and houses many songs.

Here's an aesthetic entity-relationship diagram (ERD) depicting this. A crow's foot line is a "has_many" relationship. (You can read it going in both directions as: An artist has many songs, a song belongs to an artist):

Also note sexy 60's font.

Generating the Models and Setting Up the Migrations and Relationships

We have defined our entities and their relationships on paper, and now need them implemented in Rails. Let's generate three models representing our entities:

1
2
3

$ ruby script/generate model Artist
$ ruby script/generate model Song
$ ruby script/generate model Genre

The generate script automatically creates a migration for each model.

Migrations are optional but immensely helpful (and awesome). If you have no clue what I'm talking about, see UnderstandingMigrations and the joy of migrations.

Let's edit each migration to create the appropriate fields for each table.

(Although not advised, you may use the MySQL console to create the tables and columns instead of using migrations and rake)

Table structure

The artist table will have the following fields:

• Unique ID: Created automatically by Rails; We don't need this in the migration file.
• Name: a string
• Age: a small integer

Open up the Artist model's migration file (db/migrate/001_create_artists.rb) and edit it to resemble this:

1
2
3
4
5
6
7
8
9
10
11
12

class CreateArtists < ActiveRecord::Migration
  def self.up
    create_table :artists do |t|
      t.column :name, :string
      t.column :age, :integer
    end
  end
 
  def self.down
    drop_table :artists
  end
end

The song table will have the following fields:

• Title: a string
• Duration in seconds: an integer
• Artist: Identified by the artist's unique ID (integer and cannot be NULL)
• Genre: Identified by the genre's unique ID (as above, a NON-NULL integer)

Edit the Song migration (db/migrate/002_create_songs.rb):

1
2
3
4
5
6
7
8
9
10
11
12
13
14

class CreateSongs < ActiveRecord::Migration
  def self.up
    create_table :songs do |t|
      t.column :title, :string
      t.column :duration, :integer
      t.column :artist_id, :integer, :null => false
      t.column :genre_id, :integer, :null => false
    end
  end
 
  def self.down
    drop_table :songs
  end
end

The genre table will have a name field. Edit that migration (db/migrations/003_create_genres.rb):

1
2
3
4
5
6
7
8
9
10
11

class CreateGenres < ActiveRecord::Migration
  def self.up
    create_table :genres do |t|
      t.column :name, :string
    end
  end
 
  def self.down
    drop_table :genres
  end
end

Use Rake to apply the migrations to your database. If all goes well, your console should display something like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

$ rake db:migrate
(in /home/lotus/rails/themusic)
== CreateArtists: migrating ====================
-- create_table(:artists)
   -> 0.0896s
== CreateArtists: migrated (0.0897s) ==============
 
== CreateSongs: migrating ======================
-- create_table(:songs)
   -> 0.0263s
== CreateSongs: migrated (0.0264s) ================
 
== CreateGenres: migrating =================
-- create_table(:genres)
   -> 0.0350s
== CreateGenres: migrated (0.0351s) ===========

Relationships

Rails needs to know how your models are related. We already did this in the design phase earlier above, but we now need to translate it into terms Rails can understand. Each artist will have multiple songs; Rails understands this using the keyword has_many. Edit the artist model (app/models/artist.rb) to look like this (notice that :songs is plural):

1
2
3

class Artist < ActiveRecord::Base
  has_many :songs
end

This association is pretty self-explanatory when spoken aloud: Artist has many Songs.

Each song will belong to one artist and one genre. In the migration, we specifically defined that artist_id and genre_id must exist, they cannot not be NULL. This means a song must belong to an artist and fit under a genre.

Edit song.rb (notice both params supplied to belongs_to are singular):

1
2
3
4

class Song < ActiveRecord::Base
  belongs_to :artist
  belongs_to :genre
end

We can have multiple songs under the same genre. This is a has_many association. Add it to genre.rb:

1
2
3

class Genre < ActiveRecord::Base
  has_many :songs
end

Interacting with Our App Via Console

Instead of creating a web interface or editing scaffolds, let's use the Rails console to interact with our application in its current state. The Rails console is a script named 'console' in our apps' script directory. This console gives you low level access to your Ruby on Rails application, which it loads on its own. It's a powerful debugger, and makes it fast and easy to test out individual components in your program -- not to mention it's fun! It isn't always practical but suffices perfectly for our purposes now.

Fire it up: ruby script/console. You should get a >> prompt.

The console includes tab-completion (for example, press Artist.f for a list of commands beginning with the letter f), so feel free to poke around and experiment.

Let's begin by creating an instance of the Artist model. Type the following and hit enter.

1

>> jb = Artist.new(:name => 'Joe Bloggs', :age => 36)

We have essentially created a new record in our database, but if you check your artist's table in the database now, you'll notice that this entry is non-existent. This is because it only exists in memory at this point. We have not saved it. It doesn't have a unique ID associated with it. The new_record? method returns true if the model has never been saved. You can access an object's methods and attributes via the console:

1
2
3
4
5
6
7
8

>> jb.new_record?
=> true
>> jb.name
=> "Joe Bloggs"
>> jb.age
=> 36
>> jb.id
=> nil

Now try this:

1
2

>> jb.songs
=> []

WTFMATEOMGMAGIC! []!? An empty array? Do you remember adding a songs attribute? I hope not, 'cause you didn't! Rails knows that an Artist object can have multiple songs because you defined this association in the Artist model as 'has_many :songs.' Each song the artist has will be added to this array.

Notice that the record gets an ID after it is saved:

1
2
3
4

>> jb.save
=> true
>> jb.id
=> 1

Save returns true on success. Let's create a Song instance:

1
2

>> tune = Song.new(:title => 'Love Me Three Times', :duration => 456)
=> #<song:0x2b420d56ec00 @attributes={"artist_id"=>nil, "title"=>"Love Me Three Times", "genre_id"=>nil, "duration"=>456}, @new_record=true>

Trying to save our song as this point gives us errors:

1
2
3

>> tune.save
ActiveRecord::StatementInvalid: Mysql::Error: Column 'artist_id' cannot be null:
... long trace omitted ...

Remember that artist_id and genre_id cannot be left nil. Let's create some genres on the fly. In practice, this should be done in a migration.

1
2
3
4
5
6
7
8
9
10

>> Genre.new(:name => 'Bluegrass').save
=> true
>> Genre.new(:name => 'Goa Trance').save
=> true
>> Genre.new(:name => 'Doo Wop').save
=> true
>> Genre.new(:name => 'Blues Rock').save
=> true
>> Genre.new(:name => 'Emo').save
=> true

Assign the tune a genre:

1

>> tune.genre = Genre.find_by_name('Blues Rock')

See that it has been set (don't worry if your ID differs):

1
2
3
4

>> tune.genre.name
=> "Blues Rock"
>> tune.genre_id
=> 4

Use the Array object's << operand to append to Joe Blogg's song array and then save it.

1
2
3

>> jb.songs << tune
>> tune.save
=> true

Exploration:

1
2
3
4
5
6

>> jb.songs[0].title
=> "Love Me Three Times"
>> tune.artist.name
=> "Joe Bloggs"
>> tune.artist_id
=> 1

Let's fetch and create an instance of Joe Blogg's record from the database:

1

>> bloggs = Artist.find_by_name('Joe Bloggs')

Let's explore this object further:

1
2
3
4
5
6

>> bloggs.name
=> "Joe Bloggs"
>> bloggs.songs[0].title
=> "Love Me Three Times"
>> bloggs.songs[0].genre.name
=> "Blues Rock"

Add a few more artists and songs to the database and then close the console (ctrl+D or type "quit").

In the Songs table in our database, the genre and artist are stored by ID as opposed to by string. Even if we have a centillion songs by one artist, updating that artist's info is only done in one place, once - in the record associated with that ID. If Joe Bloggs changes his name to "The Artist Formerly Known As Joe Bloggs," we only need to change this once, and it will take effect throughout our app.

Creating a Browser Interface

Don't get stoned (on beer) just yet. You have a basic understanding of why relationships are useful and how they work, but it's unlikely your application will be restricted to the Rails console. Let's create a very basic (and hideous) web interface for our music application. Each objective will be followed by details and caveats on its implementation.

We have models, but we also need controllers and views. Controllers handle events from the user, fetch data from models, and generate the output (view) that our users will see and interact with. This is known as the MVC architecture.

By convention, a controller's name is plural as opposed to a model which is singular. For example: StoriesController, PicturesController, PeopleController, etcetra; Rails adds the 'Controller' suffix to the name you give the generate script. Memorizing Rails' naming conventions can be confusing at first. I advise keeping the excellent pluralize tool on hand.

Objective #1

When the user visits http://domain.cxm/artists, we want them greeted with a list of the artists in our database. Clicking an artist's name will open a page with that artist's personal info and list of songs.

Use the following code to generate the first controller:

1

$ ruby script/generate controller Artists

The index view (what the user will see) needs to have a list of artists from the database. Add the following index method to the new controller in app/controllers/artists_controller.rb:

1
2
3
4
5

class ArtistsController < ApplicationController
    def index
        @artists = Artist.find(:all)
    end
end

find(:all) returns all the records in the Artists table. Create the view file app/views/artists/index.rhtml and add the following to it:

1
2
3
4
5
6
7

<h1>The Music Just Turns Me On</h1>
<h2>Available artists</h2>
<ul>
<% @artists.each do |artist| %>
    <li><%= link_to artist.name, :action => 'details', :id => artist.id %></li>
<% end %>
</ul>

Fire up the server script ($ ruby script/server) and point your browser to http://localhost:3000/artists. This is the default address for a rails application. If all is well with the world, you'll see this in your browser:

The Music Just Turns Me On

Available artists

• Joe Bloggs

In my example I only have one artist; More would better illustrate the code, particularly later below. Clicking on an artist's name will lead to an "Unknown action" error, as we do not yet have a details method in our ArtistsController. Let's add that to our controller now:

1
2
3
4

def details
    @artist = Artist.find_by_id(params[:id])
    @songs = @artist.songs
end

The details.rhtml view (create it in the same dir as the index view) should look like this:

1
2
3
4
5
6

<h1><%= @artist.name %> (<%= @artist.age %>)</h1>
<ol>
    <% @songs.each do |song| %>
        <li><%= song.title %> <%= song.duration %> -- <%= song.genre.name %></li>
    <% end %>
</ol>

Refresh (or run the server again if you closed it) and click an artist's name in your browser to see the details view:

Joe bloggs (36)

1. Love Me Three Times 456 -- Blues Rock

456 is the duration in seconds; Appropriate for storage, but will bring us terrible misfortune from the marketing department. Let's make it user-friendly in the form of minutes:seconds. Change the songs.each loop above to the following:

1
2
3
4
5
6
7
8
9
10

<ol>
<% @songs.each do |song| %>
    <%
        min = song.duration / 60
        sec = song.duration % 60
        @duration = '%d:%.2d' % [min, sec]
    %>
    <li><%= song.title %> <%= @duration %> -- <%= song.genre.name %></li>
<% end %>
</ol>

Check it in your browser:

Joe bloggs (36)

1. Love Me Three Times 7:36 -- Blues Rock

Purty!

Objective #2

Users should be able to browse via genre. Clicking 'Blues Rock' should list every Blues Rock song from every artist in the database; Let's make this happen.

First, we will make the song genres on the Artist details page links leading to a method called 'browse' in a not-yet-existent genres controller.

In details.rhtml, change the >li< ... >/li< line to reflect the following:

1
2

<li><%= song.title %> <%= @duration %> --
        <%= link_to song.genre.name, :controller => 'genres', :action => 'browse', :id => song.genre.id %></li>

Let's generate that controller and implement two methods.

1

$ ruby script/generate controller Genres index browse

Open app/controllers/genres_controller.rb. We have two method skeletons: index and browse. To the browse method's body, we want to add code that does this:

Psuedo-code:

a3dc31606a42206c5c45a0962bb075c0101

Here's the Ruby code, add it to the controller:

1
2
3
4
5

if params.include? :id
    @genre = Genre.find(:first, :conditions => ['id = ?', params[:id]])
else
    redirect_to :action => 'index'
end

The find() returns the first (and only, as each genre should be unique) record matching the ID that was passed from the previous page. You can swap that find method with the simpler and easier to read Genre.find_by_id(params[:id]) if you wish.

Generate created an index view and a browse view for us because we passed it the method names when generating the GenresController. Open browse.rhtml, delete the placeholder HTML inside and add the following:

1
2
3
4
5
6
7
8
9
10
11

<h1>Available <%= @genre.name %> songs</h1>
<ol>
<% @genre.songs.each do |song| %>
    <%
        min = song.duration / 60
        sec = song.duration % 60
        @duration = '%d:%.2d' % [min, sec]
    %>
    <li><%= link_to song.artist.name, :controller => 'artists', :action => 'details', :id => song.artist.id %> - <%= song.title %> (<%= @duration %>)</li>
<% end %>
</ol>

Notice the blatant violation of Ruby on Rail's fundamental Don't Repeat Yourself (DRY) principle. Having the same code pasted in more than one place is, among other things, sloppy programming. I only did this here because I don't want to violate the KISS principle. In your real apps, use partials, applications.rb and the application controller to maximize Code Reuse!

Point your browser to an artist's page and click a genre:

Available Blues Rock songs

1. Joe Bloggs - Love Me Three Times (7:36)

The user should also be able to browse by all the available genres in the database. The app/views/genres/index.rhtml view (not to be confused with the ArtistController method's index view) needs a list of genres. Add the following code into the GenresController's index method:

1

@genres = Genre.find(:all)

and the following in the genres/index.rhtml view (delete placeholder HTML, if any):

1
2
3
4
5
6

<h1>Browse by genre</h1>
<ul>
    <% @genres.each do |cat| %>
        <li><%= link_to cat.name, :action => :browse, :id => cat.id %></li>
    <% end %>
</ul>

Hit up http://localhost:3000/genres/:

Browse by genre

• Bluegrass
• Goa Trance
• Doo Wop
• Blues Rock
• Emo

Objective #3

Give the user the ability to add artists and songs via forms.

Open app/views/artists/index.rhtml and add the following form_tag code right below the h1 header:

1
2
3
4
5
6

<!-- Form to add a new artist -->
<% form_tag :action => :new do %>
    Name: <%= text_field :artist, :name %>
    Age: <%= text_field :artist, :age, :size => 1 %>
    <%= submit_tag 'Add new artist' %>
<% end %>

This snippet creates a form with three elements. A name textbox, an age textbox, and a submit button. ':action => :new' tells the form to direct the user's input to the ArtistController's new method. Open app/controllers/artists_controller.rb and add this new method now:

1
2
3
4
5

def new
    @newartist = params[:artist]
    Artist.new(@newartist).save
    redirect_to :action => :index
end

Here's a brief overview of how this function works:

Line 1: What is params[:artist]?

I won't go over params nor forms too thoroughly here. Above in our view, we had "text_field :artist, :name" and "text_field :artist, :age" -- The first parameter we passed to both, ':artist,' is the object name. Rails generates a hash with that name and puts each input field's name (that's the second part we passed the two text_fields, ':name' and :'age' respectively) as a key in that hash. The value that key corresponds to is what the user inputed on the form. For example, if we have a form asking the user to tell us about his car:

• text_field :car, :model
• text_field :car, :make
• text_field :car, :year

where the form's :action parameter points to method :vroom. In the vroom method, we'd have a hash named ':car' available in params (params[:car]). This hash will have three key-value pairs: params[:car][:model], params[:car][:make] and params[:car][:year]. The values of each will be whatever the user provided in the form's text fields.

Line 2: Why are we passing params[:artist] to the Artist constructor (Artist.new)?

We need to create a new Artist record in the database. We do so like this: Artist.new(:name => 'whatever', :age => 123). Artist.new accepts a hash with the keys :name and :age. @newartist is a hash with both those keys, because that's what we named our text_fields in the form above. It might be easier to understand knowing we can do this:

1

Artist.new(:name => @newartist[:name], :age => @newartist[:age]); Artist.save

@newartist is optional. We can pass params[:artist] directly to Artist.new. In the real world you'd want to check ALL input coming from the user before any further processing.

Line 3: Why are we redirecting to the index method?

By default, Rails would have tried to give the user the new.rhtml view, resulting in an error (we don't have such a view). We override this behavior by redirecting flow to the index method. The index method runs its course and the user is then served the index.rhtml view. In practice, this means the user is taken to the front page after they click the submit button.

After the changes above, this is what the artist form should now look like:

The Music Just Turns Me On

Name:


Age:

Available artists

... HTML output omitted ...

On the artist details page, let's implement the ability to add a new song via a form_tag. We need a list of available genres dynamically generated from the database available to the details.rhtml view. This will go into the ArtistController's details method:

1
2
3
4
5

  def details
    @artist = Artist.find_by_id(params[:id])
    @songs = @artist.songs
    @genres = Genre.find(:all)
  end

Open the details.rhtml view and add the following right under the header:

1
2
3
4
5
6
7
8
9

<% form_tag :action => :addsong, :id => @artist.id do %>
    Title: <%= text_field :song, :title %>
    Duration (seconds): <%= text_field :song, :duration, :size => 3 %>
    <br />
    <% @genres.each do |cat| %>
        <%= radio_button :song, :genre_id, cat.id %><%= cat.name %>
    <% end %>
    <%= submit_tag 'Add song' %>
<% end %>

This form will have a title and duration textfield, N(in this example, 5) genre radio buttons and a submit button. The radio_button helper accepts an object name (:song), an attribute name (in this case :genre_id, which can be accessed as params[:song].genre_id) and a tag value for that option (in our case, the numerical ID of the genre). We pass :id to the form_tag helper because we need it to lookup the artist record in the :addsong method, which we will now create. Open artists_controller.rb and add the following in the class body:

1
2
3
4
5
6
7
8
9
10
11

def addsong
    # Create new song
    @song = Song.new(params[:song])
 
    # Find artist and append new song to his current array of songs
    @artist = Artist.find_by_id(params[:id])
    @artist.songs << @song
    @song.save
 
    redirect_to :action => 'details', :id => params[:id]
end

Save. Run server script. Be amazed -- Unless it doesn't work; In which case compare your code with mine and make sure there are no typos, paying attention to nested brackets and colons.

The Music Just Turns Me On

Title:
Duration (seconds):

Available artists

... HTML output omitted ...

Deleting Records: Remember Josh Breckman

Be cautious if you attempt to implement functionality to delete records. Do not use the link_to helper to destroy/delete records! Requests that change the state of a program should be done using POST, not GET. If the user accidently reloads a page, it shouldn't change anything in the application. Firefox gives you a warning if you try to reload the page when data has been sent via POST.

You can remove records using the Model.destroy method. A safe alternative to link_to is button_to. Read the following links:

• Taking the unsafe GETs out of Rails
• The Spider of Doom

Exercises for the 1337 h4x0r

1. Give your users the ability to add and remove genres.
2. Break your application by passing it garbage (for example, http://domain.cxm/artists/view/wheeeeeee) and then fix it so it gracefully handles this input by implementing error handling.
3. Use form_for to add the ability to edit song details.
4. Use a layout to make 'Browse by artists' and 'Browse by genres' links universal throughout the app.
5. Create a website, use Gimp to design an award-winning logo, and then market this and use some of the earnings to order me an Ethanol IV drip.

Thanks to jcanady for the photo.

NOTE: If you are experiencing segmentation faults with vim and rails.vim, see this post.

When coding in Ruby on Rails, you’ll usually be switching between files and running scripts a lot. It can be time-consuming and frustrating coding Rails using a traditional text editor designed for working on big files individually. Vim lets you hop around within a file with enough speed to activate the cosmic treadmill – but without a plethora of hacks and custom key mappings, it’s weak as a Rails IDE. Fortunately, for those of us who are reluctant to kick the vim habit, Tim Pope comes to the rescue with rails.vim; A plugin that makes working with Rails in vim painless and efficient. In this guide, I will explain how to install and use rails.vim, along with a few other plugins you’ll find useful when writing Rails applications.

Vim would certainly fail the mom test, and it’s not something you can learn in one sitting. Learning vim is a lifelong process, and there are many sites and books that go over it extensively, therefore I won’t do that here. This guide assumes that you at least know what vim is and can open, edit and save files. Rails.vim works for vim, gvim and Cream, so vim in this article is referring to any of these three, unless otherwise stated.

For those who prefer Emacs, check out Effective Emacs by Steve Yegge and the official Wiki’s HowTouseEmacsWithRails.

TOC
Configuring vim/gvim
Rails.vim and Other Helpful Plugins
Usage and Examples
    Starting a New Project and Setting Up The Database
        Database.yml Setup
    Generating Models
    Migrations and :Rake
        :Rmigration pattern
        Related Files and The Command :R and its Mapping ]f
    A Glimpse of the Vim Database Extension Plugin
    Controllers, Views and Interfile Navigation
        :R or ]f
        :Rview [[controller/]view]
        :Rfind [name]
        gf ("goto file")
    Views and Partials
    We've Got You Surrounded
        Caveats
        Adding Surroundings
        Replacing Surroundings
        Removing Surroundings
        Rails.vim and Custom Surroundings
But Wait, There's More

Configuring Vim/gvim

Open your vim configuration file or create one if it doesn’t exist (i.e., new installation):

• $HOME/.vimrc in Linux and Mac OS X (might be ~/.gvimrc instead)
• $HOME\_vimrc (or $HOME\_gvimrc) in Windows

If you’re having trouble finding out where the config file goes, type “:version” and hit enter in vim for a list of compile flags, options and directories vim is using.

Add the following to the file and save it (if you must worry about what they do, see the vimdoc)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

filetype on  " Automatically detect file types.
set nocompatible  " We don't want vi compatibility.
 
" Add recently accessed projects menu (project plugin)
set viminfo^=!
 
" Minibuffer Explorer Settings
let g:miniBufExplMapWindowNavVim = 1
let g:miniBufExplMapWindowNavArrows = 1
let g:miniBufExplMapCTabSwitchBufs = 1
let g:miniBufExplModSelTarget = 1
 
" alt+n or alt+p to navigate between entries in QuickFix
map <silent> <m-p> :cp <cr>
map <silent> <m-n> :cn <cr>
 
" Change which file opens after executing :Rails command
let g:rails_default_file='config/database.yml'
 
syntax enable

Before installing rails.vim, you may want to glance over some additional (g)vim options I use. Otherwise, skip this optional step and jump directly to the installation.

The following settings in my config are worth looking over. These can be appended to the same vimrc file as above:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

set cf  " Enable error files & error jumping.
set clipboard+=unnamed  " Yanks go on clipboard instead.
set history=256  " Number of things to remember in history.
set autowrite  " Writes on make/shell commands
set ruler  " Ruler on
set nu  " Line numbers on
set nowrap  " Line wrapping off
set timeoutlen=250  " Time to wait after ESC (default causes an annoying delay)
" colorscheme vividchalk  " Uncomment this to set a default theme
 
" Formatting (some of these are for coding in C and C++)
set ts=2  " Tabs are 2 spaces
set bs=2  " Backspace over everything in insert mode
set shiftwidth=2  " Tabs under smart indent
set nocp incsearch
set cinoptions=:0,p0,t0
set cinwords=if,else,while,do,for,switch,case
set formatoptions=tcqr
set cindent
set autoindent
set smarttab
set expandtab
 
" Visual
set showmatch  " Show matching brackets.
set mat=5  " Bracket blinking.
set list
" Show $ at end of line and trailing space as ~
set lcs=tab:\ \ ,eol:$,trail:~,extends:>,precedes:<
set novisualbell  " No blinking .
set noerrorbells  " No noise.
set laststatus=2  " Always show status line.
 
" gvim specific
set mousehide  " Hide mouse after chars typed
set mouse=a  " Mouse in all modes

The following optional commands are helpful but require explicit creation of directories and files:

1
2
3
4

" Backups & Files
set backup                     " Enable creation of backup file.
set backupdir=~/.vim/backups " Where backups will go.
set directory=~/.vim/tmp     " Where temporary files will go.

Run vim to make sure it doesn’t halt to display any warnings or error messages. If it does, check that the specific folders (~/.vim/skeletons and ~/.vim/backups etc) exist and vim has write permission on them.

Rails.vim and Other Helpful Plugins

Installing vim plugins just requires putting files where they belong in vim’s root directory. We will be installing rails.vim along with some dependency plugins and a few others that make coding Rails in vim much simpler.

Below is a list of all the plugins you need to download and install. If they are .vim files, move them into your plugin folder, probably $HOME/.vim/plugin or $VIM\vimfiles\plugin (probably C:\vim\vimfiles\plugin). Doc files (.txt) go in $HOME/.vim/doc or vimfiles\doc\. Do the same with the contents of compressed files after you’ve extracted them. Again, if you’re having trouble locating where these files should go, type “:version” in vim and hit enter.

• rails.vim: This is the magic. The rails.zip file contains plugin/rails.vim and doc/rails.txt. Both should be moved into their proper location in your root vim directory ($VIM).
• Project: This adds a list of frequently used files to the lefthand side of vim. Rails.vim utilizes this script to create a directory tree of your Rails application. You’re probably familiar with this feature already, as is a basic feature of most modern IDEs.
• genutils 1.20 (NOT 2.x): Adds many useful functions
• multvals.vim: genutils depends on this.
• minibufexpl.vim: This adds (ugly, but functional) tabs to vim, making it much easier to keep track of the many files you’ll be working on simultaneously.
• dbext.vim: Adds database support to vim. This integrates seemlessly with rails.vim. More on it below.
• surround: Surround.vim adds mappings to let you easily work with “surroundings” in pairs. Such as { }, ” ” and < >. More on it below.

To get the help files working, Rails needs to generate help tags from the txt files you placed in the doc directory. Open vim and in normal (command) mode type the following and hit enter:
Linux: :helptags $HOME/.vim/doc
Windows: :helptags $VIM\vimfiles\doc

Your directory might differ from the above. In which case, again, check “:version”

Make sure it worked:

1

:help rails

For more information on vim’s help feature, use :help help or read about it in your browser. For help about a specific command, use :help command. Command can be a vim, rails.vim or other plugin command. For example :help rails or :help rgenerate.

Usage and Examples

Usage might seem intimidating at first because the plugins have-on top of vim’s already rich set of functions-added so much more functionality and commands to memorize, but you’ll quickly realize that getting used to rails.vim is easy due to the natural command names (and tab completion). Let’s begin by creating a dummy rails project.

Starting a New Project and Setting Up The Database

In Cream or gvim, you can create projects using the menu Plugin -> Rails -> Projects -> New. Alternatively, you can use the :Rails command in normal mode. Both the menu option and the :Rails command are wrappers for the native rails application, making it possible to pass them what you would normally pass rails in the console.

If you do not specify an absolute path when passing :Rails your project name, the rails application will be generated in the current working directory, usually the directory you were in when you started vim.

Let’s create a new framework named dummy. This command is typed in vim while in command mode (not the mode you type content in) and followed with the Enter key. Change /tmp/ to where ever you want this to reside (I.e., C:\Windows\Temp\):

1

:Rails /tmp/dummy

Database.yml Setup
The usual rails output will scroll across the screen and you will be dumped at the default file you specified in the vimrc file (g:rails_default_file). This will be README by default. If you haven’t changed it to database.yml like in my config above, you can jump to the database config file by typing :Rfind database.yml.

Put your database information under dummy_development and save as usual (:w). Now creating our dummy_development database is as easy as one short command:

1

:Rdbext!

(You can use a database frontend (like the excellent PHPMyAdmin) or the mysql command in a console to create your dummy_development database if you did not install dbext.)

Note: This issues a CREATE DATABASE command on the Rails environment in $RAILS_ENV, which is development by default, but you can have it create the test and production environments as well:

1
2

:Rdbext! test
:Rdbext! production

The last loaded environment configuration is what will be used throughout the Rails application. To change the environment, just provide the desired one as a parameter to the :Rdbext command (notice lack of bang: !). If you’ve created three environments and want to switch to the test environment:

1

:Rdbext test

This commands opens up a Results tab and displays the results on the bottom of the screen in a new window. Sometimes, this window can be intrusive and downright annoying. To close it, click it and hit ctrl+w, let go of both and quickly hit c.

For more information, check :help Rdbext. More on DBExt later.

Generating Models

If you wish to run something in the application’s script directory, you can use :Rscript:

1
2
3
4

:Rscript about
:Rscript console
:Rscript breakpointer
etc...

but you will probably never need to, as Rails.vim provides wrappers for most of Rails’ scripts and functions. The names of these will usually be :R followed by the name of the script. For example, :Rgenerate, :Rserver, :Rconsole, etcetra…

:Rgenerate takes the same parameters as Rails’ generate script. Let’s generate a model named Thing:

1

:Rgenerate model Thing

The model file is automatically loaded and given focus after its creation. Notice that you can still access database.yml via its tab on top of the vim window. Double click a tab to open it, and click it once to give it focus, then hit d to close it. Try that now on database.yml (and Results if it’s still open). More on tabs and the minibufexpl later.

Migrations and :Rake

Let’s edit the model’s migration file, which is created automatically for each generated model. You have a number of choices for jumping to this file:

:Rmigration pattern
The optional pattern can be any part of the migration’s filename (in this case, 001_create_things.rb). You can use things (notice it’s plural) because it matches the filename:

1

:Rmigration things

The migration number with or without the zeros. All three examples open the same migration:

1
2
3

:Rmigration 1
:Rmigration 01
:Rmigration 001

or any string of characters that match part of that migration’s filename without causing an ambiguity, like 001_create_things.rb:

1

:Rmigration te_t

Rmigration is context aware. It will default to opening the related migration file if executed without a parameter while the model file is open:

1

:Rmigration

More on related files below.

Related files and the command :R and its mapping ]f
The :R command or its mapping ]f open up the related file of whatever is currently open. A related file is something that is usually associated with the file you are opening. This is a construct in rails.vim, and that’s where the rules are defined. For example, a model’s related file is its migration. Even though both can be independent (you can have migrations without models and vice versa). Don’t think about this too much.

Below is an excerpt from :help rails-related. It shows a list of what file will be open when :R is issued while the Current File is open:

1
2
3
4
5
6

<strong>Current File            Related File</strong>
model            related migration
controller (in method)    template (view)
template (view)            controller (jump to method)
migration            next migration
config/routes.rb        config/environment.rb

Open the migration file and add the following to the create_table block in the self.up method:

1
2

t.column :description, :text
t.column :weight, :integer

After writing your self.up, you can use :Rinvert to have self.down automatically generated. You don’t have to do this here because self.down is already filled in (drop_table), but let’s try it anyway by creating a test table called “test” and using :Rinvert to update self.down. Your self.up should now look like this:

1
2
3
4
5
6
7
8
9

  def self.up
    create_table :things do |t|
      t.column :description, :text
      t.column :weight, :integer
    end
    create_table :test do |t|
      t.column :hi
    end
  end

and after running :Rinvert, your self.down will be:

1
2
3
4

  def self.down
    drop_table :test
    drop_table :things
  end

:Rinvert works great for most commands, even some complex queries, but it can’t reverse everything. A low level SQL query or a blank self.up might produce an IrreversableMigration error. Let’s apply our migration to the database by running :Rake. It defaults to db:migrate when run in the context of our migration file.

1

:Rake

A Glimpse of the Vim Database Extension Plugin

DBExt is powerful and deserves its own paper, but before getting derailed from our main topic, here are some useful DBExt commands:

:DBDescribeTable table outputs a table’s columns and their data types. Run it now on the things table:

1
2
3
4
5
6
7

:DBDescribeTable things
 
Connection: T(MYSQL)  D(bic_development)  U(username)
Field    Type    Null    Key        Default        Extra
id    int(11)    NO        PRI        NULL        auto_increment
description    text    YES        NULL
weight    int(11)    YES        NULL

:DBExecSQL query executes low level SQL queries that are either under the cursor, or passed as parameters. Let’s use it to populate our table:

1
2

:DBExecSQL INSERT INTO things VALUES (1, 'Worlds fattest man', 1200);
:DBExecSQL INSERT INTO things VALUES (2, 'Four quarter pounders', 1);

Let’s view the contents of the things table:

1

:DBSelectFromTable things

If the results window on the bottom gets stuck, click it and then hit ctrl+w the c to close it.

Read the extensive help file using :help DBExt.

Controllers, Views and Interfile Navigation

Let’s create a controller and a skeleton for a method named index:

1

:Rgenerate controller Things index

We want to display all the records from our Thing table in our index view. Let’s add some code this controller’s index method:

1
2
3

def index
    @people = Thing.find(:all)
end

For test purposes later, add the following method to ThingsController, under the index method:

1
2
3

def viewless
    @cast = "Cloud Strife"
end

Since we passed a method name (index) to :Rgenerate, Rails has automatically generated a view for that method. We have a number of ways to navigate to that view:

:R or ]f
The Related command was discussed above under Migrations and :Rake. A controller can have many views, so :R looks at the current method the cursor resides in to look up what view to open. Place the cursor anywhere in the index method and type :R (or hit ]f) to open up index.rhtml.

This command only works if the related file exists. If the view doesn’t exist, you’ll get an “E345: Can’t find file … in path” error. Try this by putting the cursor on the viewless method before running the :R command again.

You can use :RS to split (what the S stands for) the current window into two, allowing you to view and edit both the controller and view simultaneously.

:Rview [[controller/]view]
Typed with no arguments, this command behaves the same as :R. If that view doesn’t exist, you can specify a name, either by the full path or just the view name and extension, and that view will be created.

For example, let’s create a view on the fly for the viewless method (extension is mandatory):

1

:Rview viewless.rhtml

We haven’t defined a controller above, so by default, :Rview assumes it is for the current controller. It will go into app/views/things/. We could specify a controller by using :Rview controller/view_name.extension.

Note that the file is only generated in memory and must be saved to disk explicitly (:w).

Alternating between files

A lot of times, you’ll be working exclusively on two files, back and forth. To alternate between the current file and the last file you were editing, use CTRL+^ (although in practice, you’re actually just hitting CTRL+6).

Rails.vim also has an alternate command (:A or the [f mapping), similar in function to related. It usually takes you to the current file's test file.

From :help rails-alternate, this tells you what the alternate file will be for the Current File open:

1
2
3
4
5
6

<strong>Current file      Alternate file</strong>
model                               unit test
controller (in method)    functional test
template (view)              helper
migration                         previous migration
config/routes.rb               config/database.yml

:Rfind [name]
Like vim’s :find command, this one also opens a file it finds either by the name you pass it or by whatever is under the cursor (behaves similarly to gf, more on that below). Rails.vim enhances the native command by giving it the ability to find files by controller and model name.

This opens the Thing model:

1

:Rfind thing

This opens the Things controller (case sensitive):

1

:Rfind ThingsController

This opens the index.rhtml view (you must be in the ThingsController):

1

:Rfind index

gf (“goto file”)
In rails.vim, the gf mapping is used to jump to a file under the cursor taking context into account. The following is from :help rails-gf:
—
Example uses of gf, and where they might lead. (* indicates cursor position)
Pos*t.find(:first)
app/models/post.rb

has_many :c*omments
app/models/comment.rb

link_to “Home”, :controller => :bl*og
app/controllers/blog_controller.rb

<%= render :partial => ’sh*ared/sidebar’ %>
app/views/shared/_sidebar.rhtml

<%= stylesheet_link_tag :scaf*fold %>
public/stylesheets/scaffold.css

class BlogController < Applica*tionController
app/controllers/application.rb

class ApplicationController < ActionCont*roller::Base
.../action_controller/base.rb

fixtures :pos*ts
test/fixtures/posts.yml

layout :pri*nt
app/views/layouts/print.rhtml

# In the Blog controller
def li*st
app/views/blog/list.rhtml

<%= link_to "New", new_comme*nt_path %>
app/controllers/comments_controller.rb (jumps to def new)

In the last example, the controller and action for the named route are determined by evaluating routes.rb as Ruby and doing some introspection. This means code from the application is executed. Keep this in mind when navigating unfamiliar applications.
—

Add the following to the index.rhtml view file, overwriting the default code already in there:

1
2
3
4
5
6
7
8
9

<h1>All the things in our Thing table</h1>
&lt;h1&gt;All the things in our Thing table&lt;/h1&gt;
<ol>
  <% @stuff.each do |x| %>
    <li>
    <%= x.description %> (weight: <%= x.weight %> pound(s))
    </li>
  <% end %>
</ol>

Views and Partials

The :Rextract command (:Rpartial is deprecated) makes creating partials a breeze. You choose a range of lines and supply the command a name you want for the new partial. The lines get replaced by a call to render the newly created partial, which now holds the lines that were extracted.

Let’s try using this by delegating output code between the <li> and </li> tags in our index.rhtml view into a partial named “ppp” by explicitly defining the line numbers (your line numbers might not match. Alter it accordingly):

1

:5,5Rextract ppp

A new partial with the filename _ppp.rhtml is created containing line #5 from our index.rhtml view. Line #5 now is a call to render the newly created ppp view: <%= render :partial => ‘ppp’ %> – The new partial only exists in memory at this point, and must be saved to disk explicitly.

This could also have been done in visual mode, selecting the lines we want extracted visually instead of by line numbers. Place the cursor at the beginning of the line, press v to enter visual mode and hit ‘$’ (shift+4) to jump to the end of the line, selecting the entire line along the way. Now hit : and type :Rextract ppp (it will come out as :’<,'>Rextract ppp) and hit enter. Same effect as above.

We’ve Got You Surrounded

Whether you’re coding, writing, or editing, Tim Pope’s surround plugin is very useful. It adds vim mappings to add, remove or edit “surroundings.” A surrounding is a pair of parentheses, brackets, quotes, tags, etc.

Some mappings require that you press the first few keystrokes within a second. For full functionality, make sure you’re using vim 7 or greater. Let’s begin by making sure the plugin is installed and works properly by testing a command:

Type (hello world) into vim, and with your cursor anywhere in that phrase, hit ds(. If (hello world) turns to hello world, the plugin is working fine. If not, then make sure you’re installed it correctly and are using Vim 7.0.

Caveats
* The keystrokes need to be typed in succession very fast. The timeoutlen setting in the vim config file can impair the ys* functions. The smaller the value for timeoutlen, the less time you have in between keystrokes to ensure vim catches the command. I set timeoutlen to 200, but put 250 as the value in the example vimrc at the beginning of this tutorial. Delete this setting or use a higher value (300+) if you’re having trouble using commands like yssa or yss.

* b, B, r, and a are aliases for ), }, ], and > respectively, and t represents a pair of HTML or XML tags.

* In the examples below, the cursor position is represented by an asterisk (*).

Adding Surroundings
You can add a pair of surroundings around a word, line, sentence, paragraph or a specific number of characters.

Adding quotes around a word:
Old text | Command | Result
H*eya world | ysiw” | “Heya” world

Adding a pair of tags around a word:
Old text | Command | Result
I*talic text | ysiw<i> | <i>Italic</i> text

Adding arrows around a sentence:
Old text | Command | Result
Clandestin*e operation | yssa | <Clandestine operation>

An angry Kenny face:
Old text | Command | Result
*>< | yss)yss)yss( | ( ((><)) )
(notice usage of parantheses in the command. Using the opening bracket adds spaces between the target being surrounded.)

Replacing Surroundings
Replacing parentheses with quotes in a word:
Old text | Command | Result
(qu*ack) quack | cs(” | “quack” quack

Changing those double quotes to a pair of tags:
Old text | Command | Result
“q*uack” quack | cs” | quack quack

Changing those tags to brackets:
Old text | Command | Result
<qqqqq>q*uack</qqqqq> quack | cstr | [quack] quack

Removing Surroundings
Remove quotes around a word:
Old text | Command | Result
Hash “eater*” | ds” | Hash eater

Remove tags around a word:
Old text | Command | Result
<h1>h*ead</h1> | dst | head

Removing multiple surroundings around a sentence:
Old text | Command | Result
{“(iiight)”} | ds(ds”dsB | iiight

Rails.vim and Custom Surroundings
Rails.vim makes use of the surround plugin by adding a few useful surroundings. These only work when rails.vim is enabled (when RoR projects are open):

Old text | Command | Result
*end | yss= | <%= end %>

Old text | Command | Result
*end | yss- | <%= end -%>

Old text | Command | Result
*cat | yss# | <%# cat %>

You can create custom surroundings. Here’s one example:
:let g:surround_65 = “<a href=\”\”> \r </a>”

65 is the ASCII decimal for the ‘A’ character. You can use an ascii table to find the decimal corresponding to the character you want to use.

Usage:
Old text | Command | Result
I*Shot The Sheriff | yssA | <a href=”"> I Shot The Sheriff </a>

Be sure to read the extensive help files :help surround and :help rails-surround. They provide details and examples.

But Wait, There’s More

We’ve merely scratched the surface of rails.vim here. Be sure to check out the Official rails.vim Website, the author’s site, and the external links I provided below. For those looking for a more user-friendly, “real” GUI-based (as opposed to a TUI) IDE based around vim, try out VimMate.