Chapter 10 will explore migrations in much greater depth, but this migration is relatively simple. Rails will apply migrations in the sequence of their filenames, with the opening number being the critical piece. The db/migrate folder already contains a migration whose name ends in _create_people.rb, defining a CreatePeople class. To make it easy for us to figure out what’s going on, the next migration will contain an AddPhotoExtensionToPerson class. Following the same naming convention, this will be a timestamp followed by _add_photo_extension_to_person.rb. To create the migration file, enter:

script/generate migration add_photo_extension_to_person

Or, in Heroku, choose Generate from the gear menu and then enter migration add_photo_extension_to_person.

The newly generated migration won’t have much in it, but you need to add details. There doesn’t need to be very much inside this migration, as it only creates (and destroys, if necessary) one field, :extension, of type :string:

class AddPhotoExtensionToPerson < ActiveRecord::Migration
  def self.up
    add_column :people, :extension, :string
  end

  def self.down
    remove_column :people, :extension
  end
end

When this migration is run, it will add a new column to the :people table that will be used to store :extension data. If rolled back, it deletes that column.

To run the migration, just run rake db:migrate as usual. The Rake tool will find the new migration file, know that it hasn’t run it yet, and add the column to the existing :people table, as requested.

Data storage issues should all be handled in the model. Normally, Rails will save any properties that come into the model that have names corresponding to columns in the corresponding database table.

However, the migration just shown didn’t create a column that would map to :photo; just one for :extension. This is deliberate. Because these photos will be stored as files outside of the database, Rails shouldn’t handle them automatically. Explicit model code, in app/models/person.rb, will have to do that. Fortunately, Rails has an easy (and declarative) way to make sure the code for storing the photo runs after the rest of validation has happened, with its after_save callback method;

# after the person has been written to the database, deal with
# writing any image data to the filesystem
  after_save :store_photo

Unfortunately, Rails doesn’t have a built-in store_photo method. That requires coding.

store_photo, the last method in the Person class, will call on some other methods that also need to be written, but it’s probably still easiest to look at store_photo first before examining the methods on which it depends:

private

# called after saving, to write the uploaded image to the filesystem
def store_photo
  if @file_data
    # make the photo_store directory if it doesn't exist already
    FileUtils.mkdir_p PHOTO_STORE
    # write out the image data to the file
    File.open(photo_filename, 'wb') do |f|
      f.write(@file_data.read)
    end
    # ensure file saved only when it newly arrives at model being saved
    @file_data = nil
  end
end

First, note that this method comes after the private keyword, making it invisible outside of the model class to which it belongs. Controllers and views shouldn’t be calling store_photo directly. Only other methods within the same model should be able to call it. (It’s not required that you make this method private, but it makes for cleaner code overall.)

Within the method itself, the first line, if @file_data, is simple—if there is actually data to be stored, then it’s worth proceeding. Otherwise, this isn’t necessary. Then there’s a call to Ruby’s file-handling classes, creating a directory for the photos. (This causes no harm if the directory already exists.) The next few lines open a file whose name is specified by photo_filename, write the data to it, and close it. At the end, store_photo sets @file_data to nil to make sure the file doesn’t get stored again elsewhere in the application.

This takes care of saving the file, which is the last thing done as the model finishes up its work on a form submission, but more details get attended to earlier, paving the way for saving the file. The photo= method takes care of a few details when a submission arrives:

# when photo data is assigned via the upload, store the file data
# for later and assign the file extension, e.g., ".jpg"
def photo=(file_data)
  unless file_data.blank?
    # store the uploaded data into a private instance variable
    @file_data = file_data
    # figure out the last part of the filename and use this as
    # the file extension. e.g., from "me.jpg" will return "jpg"
    self.extension = file_data.original_filename.split('.').last.downcase
  end
end

The def for this method looks a bit unusual because it takes advantage of a Rails convention. Writing def photo=(file_data) creates a method that grabs the file_data content for :photo, which Rails creates based on the contents of the file_field from the HTML form. It defines what happens when person.photo is assigned a value. That file_data content gets moved to an @file_data instance variable that is private to the model but is accessible to any of the methods within it. (@file_data is what store_photo referenced, for instance.)

The photo= method also handles the one piece of the filename that will get stored in the database—the file extension. It gets the original name, splits off the piece after the last ., and lowercases it. (You don’t have to be this draconian, but it does make for simpler maintenance.) Note that photo= just assigns a value to the extension variable of the current Person object. ActiveRecord will save that value automatically, as it maps to the :extension column created by the migration.

The next few pieces are filename housekeeping:

# File.join is a cross-platform way of joining directories;
# we could have written "#{RAILS_ROOT}/public/photo_store"
PHOTO_STORE = File.join RAILS_ROOT, 'public', 'photo_store'

# where to write the image file to
  def photo_filename
    File.join PHOTO_STORE, "#{id}.#{extension}"
  end

# return a path we can use in HTML for the image
  def photo_path
    "/photo_store/#{id}.#{extension}"
  end

PHOTO_STORE provides the application with a path to this Rails application’s public directory, where static files can go. The photo_filename method gets called by store_photo when it needs to know where the photo file should actually go on its host machine’s filesystem. You can see that instead of preserving the original filename, it uses the id—the primary key number for this Person—when it creates a name for the photo. This may seem like overkill, but it has the convenient virtue of avoiding filename conflicts. Otherwise, if multiple people had uploaded me.jpg, some of them would be surprised by the results.

The photo_path method handles filename housekeeping for views that need to display the image. It’s unconcerned with where the file exists in the server’s file system and focuses instead on where it will appear as a URL in the Rails application. Again, photo_path uses the id to create the name. Its one line, a string, actually is the return value.

There’s another housekeeping function that supports the view. Not everyone will necessarily have a photo, and broken image icons aren’t particularly attractive. To simplify dealing with this, the model includes a has_photo method that checks to see if there’s a file corresponding to the id and extension of the current record:

# if a photo file exists, then we have a photo
  def has_photo?
    File.exists? photo_filename
  end

Remember, Ruby will treat the last value created by a method as its return value—in this case, the response to File.exists?. This returns true if there is a file corresponding to the id and extension, and false if there isn’t.

The last piece that the application needs is a way to show off the picture. That’s a simple addition in the show.html.erb view:

<p>
  <b>Photo:</b>
    <% if @person.has_photo? %>
      <%= image_tag @person.photo_path %>
    <% else %>
      No photo.
    <% end %>
</p>

The has_photo? method from the model lets the view code decide whether or not to create an img element for the photo. If there is one, it uses the model’s photo_path method for the src attribute, pointing to the file in the public directory’s photo_store directory. If not, there’s plain text with the message “No photo” rather than a broken image icon.