Example Use Cases

Below are a number of examples of uses for Dragonfly which differ slightly from the standard image resizing with model attachments.

Non-image attachments in Rails

When using 'dragonfly/rails'images' or similar configuration, if you're not calling thumb, width or other image-related methods on your content, then non-image attachments should just work.

class User
  image_accessor :mugshot
end

user.mugshot = Rails.root.join('some/text_file.txt')
user.save!
user.mugshot.url   # /media/BAsfsdfajkl....

Furthermore, the imagemagick configuration gives you an image? analyser method which always returns a boolean so you can still make a thumbnail if it is an image

user.mugshot.thumb!('400x300#') if user.mugshot.image?

'dragonfly/rails/images' also gives you a file_accessor macro which is actually just the same as image_accessor, but a bit more meaningful when not dealing with images

class User
  file_accessor :mugshot
end

You can always define your own macro for dealing with non-image attachments:

Dragonfly[:my_app].define_macro(ActiveRecord::Base, :attachment_accessor)

class User
  attachment_accessor :mugshot
end

see Models for how to define macros with non-ActiveRecord libraries.

Quick custom image processing in Rails

With the imagemagick configuration, we can easily use convert to do some custom processing, e.g. in the view:

<%= image_tag @user.mugshot.thumb('300x300#').convert('-blur 4x2').url %>

If we use this a lot, we can define a shortcut for it - in config/initializers/dragonfly.rb:

Dragonfly[:images].configure do |c|
  c.job :blurred_square do |size|
    process :resize_and_crop, :width => size, :height => size
    process :convert, '-blur 4x2'
  end
end

then in the view:

<%= image_tag @user.mugshot.blurred_square(300).url %>

See ImageMagick for more info.

Using Javascript to generate on-the-fly thumbnails in Rails

Supposing we have a Pancake model with an image attachment

pancake = Pancake.create! :image => Pathname.new('path/to/pancake.png')

Setting the attachment sets the uid field (this example uses the FileDataStore)

pancake.image_uid    # '2011/04/27/17_04_32_705_pancake.png'

We can set up a Dragonfly endpoint in routes.rb for generating thumbnails:

match '/thumbs/:geometry' => app.endpoint { |params, app|
  app.fetch(params[:uid]).thumb(params[:geometry])
}

NOTE: if you use do...end here instead of curly braces, make sure you put brackets around the arguments to match, otherwise Ruby will parse it incorrectly

If we have access to the image uid in javascript, we can create the url like so:

var url = '/thumbs/400x300?uid=' + uid

Then we can get the content with ajax, create an img tag, etc.

NOTE: in the above example we've put the uid in the query string and not the path because the dot in it confuses Rails' pattern recognition. You could always put it in the path and escape/unescape it either side of the request.

Also javascript's built-in encodeURIComponent function may be useful when Rails has difficulty matching routes due to special characters like '#' and '/'.

Text generation with Sinatra

We can easily generate on-the-fly text with Sinatra and the ImageMagick Generator:

require 'rubygems'
require 'sinatra'
require 'dragonfly'

app = Dragonfly[:images].configure_with(:imagemagick)

get '/:text' do |text|
  app.generate(:text, text, :font_size => 30).to_response(env)
end

When we visit '/hello!' we get a generated image of the text "hello!".

See ImageMagick for more details.

Creating a Dragonfly plugin

You can create custom data stores, processors, encoders, analysers and generators, and then tie them all together with a saved configuration.

See Dragonfly-RMagick for an example. NOTE: you will probably want to create classes and modules in your own namespace, rather than the Dragonfly namespace (even though Dragonfly-RMagick uses it).