Using with Models
You can extend ActiveModel-compatible models to make working with content such as images as easy as working with strings or numbers!
The examples below assume an initialized Dragonfly app, e.g.
app = Dragonfly[:images]
ActiveRecord
If you've required 'dragonfly/rails/images', then the following step will be already done for you. Otherwise:
app.define_macro(ActiveRecord::Base, :image_accessor)
defines the macro image_accessor on any ActiveRecord models.
Mongoid
app.define_macro_on_include(Mongoid::Document, :image_accessor)
defines the macro image_accessor on any models that include Mongoid::Document
CouchRest::Model
app.define_macro(CouchRest::Model::Base, :image_accessor)
defines the macro image_accessor on any models inherited from CouchRest::Model::Base.
Adding accessors
Now we have the method image_accessor available in our model classes, which we can use as many times as we like
class Album
image_accessor :cover_image
image_accessor :band_photo # Note: this is a different image altogether, not a thumbnail of cover_image
end
Each accessor (e.g. cover_image) depends on a string field to actually hold the datastore uid,
named by appending the suffix _uid (e.g. cover_image_uid).
For example, ActiveRecord models need a migration such as:
class MyMigration < ActiveRecord::Migration
def self.up
add_column :albums, :cover_image_uid, :string
add_column :albums, :band_photo_uid, :string
end
def self.down
remove_column :albums, :cover_image_uid
remove_column :albums, :band_photo_uid
end
end
Using the accessors
We can use the attribute much like other other model attributes:
@album = Album.new
@album.cover_image = "\377???JFIF\000\..." # can assign as a string...
@album.cover_image = File.new('path/to/my_image.png') # ... or as a file...
@album.cover_image = some_tempfile # ... or as a tempfile...
@album.cover_image = Pathname.new('some/path.gif') # ... or as a pathname...
@album.cover_image = @album.band_photo # ... or as another Dragonfly attachment
@album.cover_image # => #<Dragonfly::ActiveModelExtensions::Attachment:0x103ef6128...
@album.cover_image = nil
@album.cover_image # => nil
We can inspect properties of the attribute
@album.cover_image.width # => 280
@album.cover_image.height # => 140
@album.cover_image.number_of_colours # => 34703
@album.cover_image.mime_type # => 'image/png'
The properties available (i.e. 'width', etc.) come from the app's registered analysers - see Analysers.
We can play around with the data
@album.cover_image.data # => "\377???JFIF\000\..."
@album.cover_image.to_file('out.png') # writes to file 'out.png' and returns a readable file object
@album.cover_image.to_file('out.png',
:mode => 0600,
:mkdirs => false
)
@album.cover_image.tempfile # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a closed Tempfile object
@album.cover_image.file # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a readable (open) File object
@album.cover_image.file do |f| # Yields an open file object, returns the return value of
data = f.read(256) # the block, and closes the file object
end
@album.cover_image.path # => '/var/folders/st/strHv74sH044JPabSiODz...' i.e. the path of the tempfile
@album.cover_image.size # => 134507 (size in bytes)
We can process the data
image = @album.cover_image.process(:thumb, '20x20') # returns a 'Job' object, with similar properties
image.width # => 20
@album.cover_image.width # => 280 (no change)
The available processing methods available (i.e. 'thumb', etc.) come from the Dragonfly app's registered processors - see Processing
We can encode the data
image = @album.cover_image.encode(:gif) # returns a 'Job' object, with similar properties
image.format # => :gif
@album.cover_image.format # => :png (no change)
The encoding is implemented by the Dragonfly app's registered encoders (which will usually just be one) - see Encoding
We can use configured shortcuts for processing/encoding, and chain them:
@album.cover_image.thumb('300x200#ne') # => returns a 'Job' object, with similar properties
We can chain all these things much like ActiveRecord scopes:
@album.cover_image.png.thumb('300x200#ne').process(:greyscale).encode(:tiff)
Because the processing/encoding methods are lazy, no actual processing or encoding is done until a method like data, file, to_file, width, etc. is called.
You can force the processing to be done if you must by then calling apply.
@album.cover_image.process(:greyscale).apply
Assigning from a url
Dragonfly provides an accessor for assigning directly from a url:
@album.cover_image_url = 'http://some.url/file.jpg'
You can put this in a form view, e.g. in rails erb:
<% form_for @album, :html => {:multipart => true} do |f| %>
...
<%= f.text_field :cover_image_url %>
...
<% end %>
Removing an attachment via a form
Normally unassignment of an attachment is done like any other attribute, by setting to nil
@album.cover_image = nil
but this can't be done via a form - instead remove_<attachment_name> is provided, which can be used with a checkbox:
<%= f.check_box :remove_cover_image %>
Retaining across form redisplays
When a model fails validation, you don't normally want to have to upload your attachment again, so you can avoid having to do this by
including a hidden field in your form retained_<attribute_name>, e.g.
<% form_for @album, :html => {:multipart => true} do |f| %>
...
<%= f.file_field :cover_image %>
<%= f.hidden_field :retained_cover_image %>
...
<% end %>
Persisting
When the model is saved, a before_save callback persists the data to the App's configured datastore (see DataStorage) The uid column is then filled in.
@album = Album.new
@album.cover_image_uid # => nil
@album.cover_image = File.new('path/to/my_image.png')
@album.cover_image_uid # => nil
@album.save
@album.cover_image_uid # => '2009/12/05/file.png' (some unique uid, used by the datastore)
URLs
Once the model is saved, we can get a url for the image (which is served by the Dragonfly App itself), and for its processed/encoded versions:
@album.cover_image.url # => '/media/BAhbBlsHOgZmIhgy...'
@album.cover_image.thumb('300x200#nw').url # => '/media/BAhbB1sYusgZhgyM...'
@album.cover_image.process(:greyscale).jpg.url # => '/media/BnA6CnRodW1iIg8z...'
Because the processing/encoding methods (including shortcuts like thumb and jpg) are lazy, no processing or encoding is actually done.
Validations
validates_presence_of and validates_size_of work out of the box, and Dragonfly also provides validates_property.
class Album
validates_presence_of :cover_image
validates_size_of :cover_image, :maximum => 500.kilobytes
validates_property :format, :of => :cover_image, :in => [:jpeg, :png, :gif]
# ..or..
validates_property :mime_type, :of => :cover_image, :as => 'image/jpeg', :case_sensitive => false
validates_property :width, :of => :cover_image, :in => (0..400), :message => "é demais cara!"
# ...
end
The property argument of validates_property will generally be one of the registered analyser properties as described in Analysers.
However it would actually work for arbitrary properties, including those of non-dragonfly model attributes.
validates_property can also take a proc for the message, yielding the actual value and the model
validates_property :width, :of => :cover_image, :in => (0..400),
:message => proc{|actual, model| "Unlucky #{model.title} - was #{actual}" }
Name and extension
If the object assigned is a file, or responds to original_filename (as is the case with file uploads in Rails, etc.), then name will be set.
@album.cover_image = File.new('path/to/my_image.png')
@album.cover_image.name # => 'my_image.png'
@album.cover_image.ext # => 'png'
Meta data
You can store metadata along with the content data of your attachment:
@album.cover_image = File.new('path/to/my_image.png')
@album.cover_image. = {:taken => Date.yesterday}
@album.save!
@album.cover_image. # => {:model_class=>"Album",
# :model_attachment=>:cover_image,
# :taken=>Sat, 11 Sep 2010}
As you can see, a couple of things are added by the model. You can also access this directly on the Job object.
app.fetch(@album.cover_image_uid). # => {:model_class=>"Album", ...}
Meta data can be useful because at the time that Dragonfly serves content, it doesn't have access to your model, but it does have access to the meta data that was stored alongside the content, so you could use it to provide custom response headers, etc. (see Configuration).
Callbacks
after_assign
after_assign can be used to do something every time content is assigned:
class Person
image_accessor :mugshot do
after_assign{|a| a.process!(:rotate, 90) } # 'a' is the attachment itself
end
end
person.mugshot = Pathname.new('some/path.png') # after_assign callback is called
person.mugshot = nil # after_assign callback is NOT called
Inside the block, you can call methods on the model instance directly (self is the model):
class Person
image_accessor :mugshot do
after_assign{|a| a.process!(:rotate, angle) }
end
def angle
90
end
end
Alternatively you can pass in a symbol, corresponding to a model instance method:
class Person
image_accessor :mugshot do
after_assign :rotate_it
end
def rotate_it
mugshot.process!(:rotate, 90)
end
end
You can register more than one after_assign callback.
after_unassign
after_unassign is similar to after_assign, but is only called when the attachment is unassigned
person.mugshot = Pathname.new('some/path.png') # after_unassign callback is NOT called
person.mugshot = nil # after_unassign callback is called
Up-front thumbnailing
The best way to create different versions of content such as thumbnails is generally on-the-fly, however if you must
create another version on-upload, then you could create another accessor and automatically copy to it using copy_to.
class Person
image_accessor :mugshot do
copy_to(:smaller_mugshot){|a| a.thumb('200x200#') }
end
image_accessor :smaller_mugshot
end
person.mugshot = Pathname.new('some/400x300/image.png')
person.mugshot # ---> 400x300 image
person.smaller_mugshot # ---> 200x200 image
In the above example you would need both a mugshot_uid field and a smaller_mugshot_uid field on your model.
Storage options
Some datastores take options when calling store - you can pass these through using storage_xxx methods, e.g.
storage_path
The FileDataStore and S3DataStore both
can take a :path option to specify where to store the content (which will also become the uid for that content)
class Person
image_accessor :mugshot do
storage_path{ "some/path/#{first_name}/#{rand(100)}" } # You can call model instance methods (like 'first_name') directly
end
end
or
class Person
image_accessor :mugshot do
storage_path :path_for_mugshot
end
def path_for_mugshot
"some/path/#{first_name}/#{rand(100)}"
end
end
or you can also yield the attachment itself
storage_path{|a| "some/path/#{a.width}x#{a.height}.#{a.format}" }
BEWARE!!!! you must make sure the path (which will become the uid for the content) is unique and changes each time the content is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
BEWARE No. 2!!!! using id in the storage_path won't generally work on create, because Dragonfly stores the content in a call to before_save,
at which point the id won't yet exist.
You can pass any options through to the datastore using storage_xxx methods, or all at once using storage_opts:
class Person
image_accessor :mugshot do
storage_opts do |a|
{
:path => "some/path/#{id}/#{rand(100)}",
:other => 'option'
}
end
end
end
"Magic" Attributes
An accessor like cover_image only relies on the accessor cover_image_uid to work.
However, in some cases you may want to record some other properties, whether it be for using in queries, or
for caching an attribute for performance reasons, etc.
For the properties name, ext, size and any of the registered analysis methods (e.g. width, etc. in the examples above),
this is done automatically for you, if the corresponding accessor exists.
For example - with ActiveRecord, given the migration:
add_column :albums, :cover_image_width, :integer
This will automatically be set when assigned:
@album.cover_image = File.new('path/to/my_image.png')
@album.cover_image_width # => 280
They can be used to avoid retrieving data from the datastore for analysis
@album = Album.first
@album.cover_image.width # => 280 - no need to retrieve data - takes it from `cover_image_width`
@album.cover_image.size # => 134507 - but this needs to retrieve data from the data store, then analyse
Furthermore, any magic attributes you add a field for will be added to the meta data for that attachment (and so can be used when Dragonfly serves the content for e.g. setting custom response headers based on that meta - see Configuration).
Custom Model
The accessors only require that your model class implements before_save, before_destroy and validates_each
(if using validations), as well as of course the ..._uid field for storing the datastore uid.
Here is an example of a minimal ActiveModel Album model:
class CustomModel::Base
extend ActiveModel::Callbacks
define_model_callbacks :save, :destroy
include ActiveModel::Validations # if needed
def save
_run_save_callbacks {
# do some saving!
}
end
def destroy
_run_destroy_callbacks {
# do some destroying!
}
end
end
Define our image_accessor macro...
app.define_macro(CustomModel::Base, :image_accessor)
...which is used by Album:
class Album < CustomModel::Base
def cover_image_uid=
# ...
end
def cover_image_uid
# ...
end
image_accessor :cover_image
end