AttachmentSaver

This plugin implements attachment storage and processing, integrated with ActiveRecord models and Ruby CGI/Rails-style uploads. Image processing operations including a number of different resizing & thumbnailing modes are provided, and the architecture simplifies clean implementation of other types of processing. Errors are carefully handled to minimize the possibility of broken uploads leaving incomplete or corrupt data.

RMagick, MiniMagick, ImageScience, and GdkPixbuf image processors are supported.

The pure-ruby ImageSize image processor is also supported (for inspecting images but not resizing them).

Compatibility

Currently tested against Rails 5.2 (up to 5.2.0.beta2), 5.1 (up to 5.1.4), 5.0 (up to 5.0.6), and 4.2 (up to 4.2.10), on Ruby 2.3.6, 2.4.3, and 2.5.0. Was also tested compatible with 2.3.14, 3.0.17, 3.1.8, 3.2.13, 4.2, and 5.0.

Examples

A 'dumb' attachment store that saves minimal info

in your model:

class SomeModel saves_attachment end

in your database schema:

create_table :some_model do |t| t.string :storage_key, :null => false end

in your new/update forms:

file_field :some_model, :uploaded_data

no special controller handling is required.

A 'dumb' attachment store that saves full file info automatically

as for above, but in the schema:

create_table :some_model do |t| t.string :storage_key, :null => false t.string :original_filename, :null => false # as sent by the user's browser, with IE path removed t.string :content_type, :null => false # as sent by the user's browser t.integer :size, :null => false # file size in bytes t.timestamps end

An image store that automatically saves width and height and corrects mime types & file extensions

in your models:

class Image saves_attachment :processor => 'rmagick' end

in your database schema:

create_table :photos do |t| t.string :storage_key, :null => false t.string :original_filename, :null => false # as sent by the user's browser, with IE path removed t.string :content_type, :null => false # corrected if the user's browser sent a mime type that didn't match the image t.integer :size, :null => false # file size in bytes t.integer :width, :null => false # set by the image processors t.integer :height, :null => false # ditto t.timestamps end

An image store that resizes images to produce thumbnails etc.

in your models:

class Photo saves_attachment :processor => 'RMagick', :derived_class => 'Thumbnail', :formats => {:page_width => '520x', # ImageMagick-style format string :small => [:shrink_to_fit, 250, 250], # or more explicit [operation, width, height] format :nav => [:cover_and_crop, 50, 50]} # lots of useful resize and/or crop modes available end

class Thumbnail saves_attachment end

in your database schema:

create_table :photos do |t| t.string :storage_key, :null => false t.string :original_filename, :null => false # as sent by the user's browser, with IE path removed t.string :content_type, :null => false # corrected if the user's browser sent a mime type that didn't match the image t.integer :size, :null => false # file size in bytes t.integer :width, :null => false # set by the image processors t.integer :height, :null => false # ditto t.timestamps end

create_table :thumbnails do |t| t.string :original_type, :null => false # multiple models can save their derived images as thumbnails t.integer :original_id, :null => false t.string :format_name, :null => false # from your :formats - eg. 'small', 'nav' t.string :storage_key, :null => false # still required (but will be based on the original's, for convenience) t.string :content_type, :null => false # these fields are optional (as they are for Photo) t.integer :size, :null => false t.integer :width, :null => false # but width and height are generally needed for layout t.integer :height, :null => false t.timestamps end

A custom image-processing format using your image-processor's features

in a file in your lib/ directory that's required in somewhere:

module AttachmentSaver::Processors::RMagick::Operations # or MiniMagick::Operations or ImageScience::Operations or GdkPixbuf::Operations - see lib/processors

this module is mixed in to the actual image objects built by the processor, so you can call its' methods directly

def wavy_black_and_white(wave_height, wave_length, &block) # RMagick returns the new object; MiniMagick acts on the same object (so you must dup); ImageScience yields; so, look at the existing lib/processors to see the appropriate pattern image = quantize(256, Magick::GRAYColorspace).wave(wave_height, wave_length)

# mix the operations in to the new image, for reuse
image.extend Operations

# yield up the new image
block.call(image)

end end

in your models:

class Image saves_attachment :processor => 'RMagick', :derived_class => 'SpecialImage', :formats => {:flashback => [:wavy_and_black_and_white, 10, 200]} end