The FileColumn module allows you to easily handle file uploads. You can designate one or more columns of your model’s table as "file columns" like this:

  class Entry < ActiveRecord::Base

    file_column :image
  end

Now, by default, an uploaded file "test.png" for an entry object with primary key 42 will be stored in in "public/entry/image/42/test.png". The filename "test.png" will be stored in the record’s image column.

The methods of this module are automatically included into ActiveRecord::Base as class methods, so that you can use them in your models.

Generated Methods

After calling "file_column :image" as in the example above, a number of instance methods will automatically be generated, all prefixed by "image":

• Entry#image=(uploaded_file): this will handle a newly uploaded file (see below). Note that you can simply call your upload field "entry[image]" in your view (or use the helper).
• Entry#image(suffix=nil): This will return an absolute path (as a string) to the currently uploaded file or nil if no file has been uploaded
• Entry#image_relative_path(suffix): This will return a path relative to this file column’s base directory as a string or nil if no file has been uploaded. This would be "42/test.png" in the example.
• Entry#image_just_uploaded?: Returns true if a new file has been uploaded to this instance. You can use this in before_validation to resize images on newly uploaded files, for example.

You can access the raw value of the "image" column (which will contain the filename) via the ActiveRecord::Base#attributes or ActiveRecord::Base#[] methods like this:

  entry['image']    # e.g."test.png"

Storage of uploaded file

For a model class Entry and a column image, all files will be stored under "public/entry/image". A sub-directory named after the primary key of the object will be created, so that files can be stored using their real filename. For example, a file "test.png" stored in an Entry object with id 42 will be stored in

  public/entry/image/42/test.png

Files will be moved to this location in an after_save callback. They will be stored in a temporary location previously as explained in the next section.

Handling of form redisplay

Suppose you have a form for creating a new object where the user can upload an image. The form may have to be re-displayed because of validation errors. The uploaded file has to be stored somewhere so that the user does not have to upload it again. FileColumn will store these in a temporary directory (called "tmp" and located under the column’s base directory by default) so that it can be moved to the final location if the object is successfully created. If the form is never completed, though, you can easily remove all the images in this "tmp" directory once per day or so.

So in the example above, the image "test.png" would first be stored in "public/entry/image/tmp/<some_random_key>/test.png" and be moved to "public/entry/image/<primary_key>/test.png".

This temporary location of newly uploaded files has another advantage when updating objects. If the update fails for some reasons (e.g. due to validations), the existing image will not be overwritten, so it has a kind of "transactional behaviour".

Suffixes

FileColumn allows you to keep more than one file in a directory and will move/delete all the files it finds in a model object’s directory when necessary. You can access these files via the optional suffix parameter that some of the generated methods accept (see above). This suffix is inserted into the filename before the extension, separated by a dash.

Suppose your uploaded file is named "vancouver.jpg" and you want to create a thumb-nail and store it in the same directory. If you cal image("thumb"), you will receive an absolute path for the file "vancouver-thumb.jpg" in the same directory "vancouver.jpg" is stored. Look at the documentation of FileColumn::Magick for more examples.

File Extensions

FileColumn will try to fix the file extension of uploaded files, so that the files are served with the correct mime-type by your web-server. Most web-servers are setting the mime-type based on the file’s extension. You can disable this behaviour by passing the :fix_file_extensions option with a value of nil to file_column.

In order to set the correct extension, FileColumn tries to determine the files mime-type first. It then uses the MIME_EXTENSIONS hash to choose the corresponding file extension. You can override this hash by passing in a :mime_extensions option to file_column.

The mime-type of the uploaded file is determined with the following steps:

1. Run the external "file" utility. You can specify the full path to the executable in the :file_exec option or set this option to nil to disable this step
2. If the file utility couldn’t determine the mime-type or the utility was not present, the content-type provided by the user’s browser is used as a fallback.