ModelClassAccessors

The primary class method is acts_as_fleximage which integrates Fleximage functionality into a model class. Upon doing so it also inserts a a number of class accessors (via the dsl_accessor gem). These accessors help set model level options.

If you simply want all the defaults, you can minimally setup your model with just a quick call like this:

class Photo < ActiveRecord::Base
  acts_as_fleximage :image_directory => 'path/to/image/directory'
end

If you want to use some of the below model options, I recommend passing a block to acts_as_fleximage like so:

class Photo < ActiveRecord::Base
  acts_as_fleximage do
    image_directory 'path/to/image/directory'
    require_image false

    preprocess_image do |image|
      image.resize '800x600'
    end
  end
end

If you need these values, they are later available as class methods. For instance:

Photo.image_directory => “path/to/image/directory”

All class level model options

image_directory

(String, no default)

Where the master images are stored, directory path relative to your app root.

s3_bucket

(String, no default)

Name of the bucket on your Amazon S3 where your master images are stored. To use S3 storage you must initialize the s3 gem in your application initialization by calling AWS::S3::Base.establish_connection! method with your credentials. Do not use image_directory if you are using s3 storage.

use_creation_date_based_directories

(Boolean, default true)

If true, master images will be stored in directories based on creation date. For example: "#{image_directory}/2007/11/24/123.png" for an image with an id of 123 and a creation date of November 24, 2007. Turing this off would cause the path to be “#{image_directory}/123.png” instead. This helps keep the OS from having directories that are too full.

image_storage_format

(:png or :jpg, default :png)

The format of your master images. Using :png will give you the best quality, since the master images as stored as lossless version of the original upload. :jpg will apply lossy compression, but the master image file sizes will be much smaller. If storage space is a concern use :jpg.

require_image

(Boolean, default true)

The model will raise a validation error if no image is uploaded with the record. Setting to false allows record to be saved with no uploaded image.

missing_image_message

(String, default “is required”)

Validation message to display when no image was uploaded for a record.

invalid_image_message

(String, default “was not a readable image”)

Validation message when an image is uploaded, but is not an image format that can be read by RMagick.

validates_image_size

(Size, default nil)

If you declare this value then a minimum size will be enforced. If an uploaded image does not meet the minimum size than a validation error is thrown for the record. Use a dimension of 0 on x or y to allow any size. For example a size of "320x0" would validate for an image of any width, as long as it was at least 320 pixels tall.

output_image_jpg_quality

(Integer, default 85)

When rendering JPGs, this represents the amount of compression. Valid values are 0 – 100, where 0 is very small and very ugly, and 100 is near lossless but very large in filesize.

default_image_path

(String, default nil)

If no image is present for this record, the image at this path will be used instead. Useful for a placeholder graphic for new content that may not have an image just yet. Combine this with require_image false to allow records to be created and rendered without uploading an image.

default_image

(Hash, default {})

If no image is present for this record, an image with this :size and :color will be created and used instead. This works great as a virtual image (not based on an uploaded master image) that you can adorn with text, overlays, or other effects. Combine this with require_image false to allow records to be created and rendered without uploading an image.

preprocess_image

(Block, no default)

Call this class method just like you would call operate in a view. The image transformation in the provided block will be run on every uploaded image before its saved as the master image.

Example

This example shows how you would explicitly declare settings using each of these methods.

class Photo < ActiveRecord::Base
  acts_as_fleximage do
    image_directory 'public/images/uploaded'
    # s3_bucket 'mywebsite-uploaded-photos' # uses S3 instead of file system or database

    use_creation_date_based_directories true
    image_storage_format      :png
    require_image             true
    missing_image_message     'is required'
    invalid_image_message     'was not a readable image'
    output_image_jpg_quality  85

    preprocess_image do |image|
      image.resize '1024x768'
    end
  end

  # normal model methods...
end