Configuration

Given a Dragonfly app

app = Dragonfly[:app_name]

Configuration can either be done using a block...

app.configure do |c|
  c.url_format = '/media/:job'
  # ...
end

...or directly...

app.url_format = '/media/:job'

The defaults should be fairly sensible, but you can tweak a number of things if you wish. Here is an example of an app with all attributes configured:

app.configure do |c|
  c.datastore = SomeCustomDataStore.new :egg => 'head'  # defaults to FileDataStore

  c.cache_duration = 3600*24*365*2                      # defaults to 1 year # (1 year)
  c.fallback_mime_type = 'something/mental'             # defaults to application/octet-stream
  c.log = Logger.new($stdout)                           # defaults to Logger.new('/var/tmp/dragonfly.log')
  c.trust_file_extensions = false                       # defaults to true

  c.url_format = '/images/:job/:basename.:format'       # defaults to '/:job/:basename.:format'
  c.url_host = 'http://some.domain.com:4000'            # defaults to nil

  c.content_filename = proc{|job, request|              # defaults to the original name, with modified ext if encoded
    "file.#{job.ext}"
  }
  c.content_disposition = :attachment                   # defaults to nil (use the browser default)

  c.protect_from_dos_attacks = true                     # defaults to false - adds a SHA parameter on the end of urls
  c.secret = 'This is my secret yeh!!'                  # should set this if concerned about DOS attacks

  c.analyser.register(MyAnalyser)                       # See 'Analysers' for more details
  c.processor.register(MyProcessor, :type => :fig)      # See 'Processing' for more details
  c.encoder.register(MyEncoder) do |e|                  # See 'Encoding' for more details
    e.some_value = 'geg'
  end
  c.generator.register(MyGenerator)                     # See 'Generators' for more details

  c.register_mime_type(:egg, 'fried/egg')               # See 'MimeTypes' for more details

  c.job :black_and_white do |size|                      # Job shortcut - lets you do image.black_and_white('30x30')
    process :greyscale
    process :thumb, size
    encode  :gif
  end

  c.define_url do |app, job, opts|                      # allows overriding urls - defaults to
    if job.step_types == [:fetch]                       #   app.server.url_for(job, opts)
      app.datastore.url_for(job.uid)
    else
      app.server.url_for(job, opts)
    end
  end

  c.server.before_serve do |job, env|                   # allows you to do something before content is served
    # do something
  end

  c.response_headers['X-Something'] = 'Custom header'   # You can set custom response headers
  c.response_headers['summink'] = proc{|job, request|   # either directly or via a callback
    job.image? ? 'image yo' : 'not an image'
  }

  # When using ImageMagick only...
  c.convert_command = "/opt/local/bin/convert"          # defaults to "convert"
  c.identify_command = "/opt/local/bin/identify"        # defaults to "identify"
  c.log_commands = true                                 # defaults to false
end

Where is configuration done?

In Rails, it should be done in an initializer, e.g. 'config/initializers/dragonfly.rb'. Otherwise it should be done anywhere where general setup is done, early on.

Reflecting on configuration

There are a few methods you can call on the app to see what processors etc. are registered: processor_methods, generator_methods, analyser_methods and job_methods.

Saved configurations

Saved configurations are useful if you often configure the app the same way. There are a number that are provided with Dragonfly:

ImageMagick

app.configure_with(:imagemagick)

The ImageMagick configuration registers the app with the ImageMagick Analyser, ImageMagick Processor, ImageMagick Encoder and ImageMagick Generator, and a number of job shortcuts.

The file 'dragonfly/rails/images' does this for you.

The processor, analyser, encoder and generator pass data around using tempfiles.

Rails

app.configure_with(:rails)

The Rails configuration points the log to the Rails logger, configures the file data store root path, sets the url path prefix to '/media', and registers the FileCommandAnalyser for helping with mime_type validations.

The file 'dragonfly/rails/images' does this for you.

Custom Saved Configuration

You can create your own saved configuration with any object that responds to 'apply_configuration':

module MyConfiguration

  def self.apply_configuration(app, *args)
    app.configure do |c|
      c.url_path_prefix = '/hello/beans'
      c.processor.register(MyProcessor)
      # ...
    end
  end

end

Then to configure:

app.configure_with(MyConfiguration, :any_other => :args)     # other args get passed through to apply_configuration

You can also carry on configuring by passing a block

app.configure_with(MyConfiguration) do |c|
  c.any_extra = :config_here
  # ...
end

If you wish to be able to use a symbol to represent your configuration (e.g. for a plugin, etc.) you can register it globally as a one-off:

Dragonfly::App.register_configuration(:myconfig){ My::Saved::Configuration }

Then from then on you can configure Dragonfly apps using

app.configure_with(:myconfig, :any_other => :args)