dragonfly 0.8.6 → 0.9.0

data/extra_docs/Mongo.md

@@ -17,13 +17,10 @@ In config/initializers/dragonfly.rb:
 
     app = Dragonfly[:images]
 
-    # Get database name from config/mongoid.yml
-    db = YAML.load_file(Rails.root.join('config/mongoid.yml'))[Rails.env]['database']
-
     # Configure to use ImageMagick, Rails defaults, and the Mongo data store
     app.configure_with(:imagemagick)
     app.configure_with(:rails) do |c|
-      c.datastore = Dragonfly::DataStorage::MongoDataStore.new :database => db
+      c.datastore = Dragonfly::DataStorage::MongoDataStore.new :db => Mongoid.database
     end
 
     # Allow all mongoid models to use the macro 'image_accessor'

data/extra_docs/Processing.md

@@ -1,7 +1,6 @@
 Processing
 ==========
-
-Changing data in some way, e.g. resizing an image, comes under the banner of Processing.
+Registered processors allow you to modify data, e.g. resizing an image.
 
 You can register as many processors as you like.
 
@@ -19,62 +18,6 @@ and an image object (actually a {Dragonfly::Job Job} object)...
 
 We can process it using any processing methods that have been registered with the processor.
 
-ImageMagickProcessor
---------------------
-The {Dragonfly::Processing::ImageMagickProcessor ImageMagickProcessor} is registered by default by
-the {Dragonfly::Config::ImageMagick ImageMagick configuration} used by 'dragonfly/rails/images'.
-
-If not already registered:
-
-    app.processor.register(Dragonfly::Processing::ImageMagickProcessor)
-
-gives us these methods:
-
-    image.process(:thumb, '400x300#')            # see below
-
-    image.process(:crop, :width => 40, :height => 50, :x => 20, :y => 30)
-    image.process(:crop, :width => 40, :height => 50, :gravity => 'ne')
-
-    image.process(:flip)                         # flips it vertically
-    image.process(:flop)                         # flips it horizontally
-
-    image.process(:greyscale, :depth => 128)     # default depth 256
-
-    image.process(:resize, '40x40')
-    image.process(:resize_and_crop, :width => 40, :height=> 50, :gravity => 'ne')
-
-    image.process(:rotate, 45, :background_colour => 'transparent')   # default bg black
-
-The method `thumb` takes a geometry string and calls `resize`, `resize_and_crop` or `crop` accordingly.
-
-    image.process(:thumb, '400x300')             # calls resize
-
-Below are some examples of geometry strings:
-
-    '400x300'            # resize, maintain aspect ratio
-    '400x300!'           # force resize, don't maintain aspect ratio
-    '400x'               # resize width, maintain aspect ratio
-    'x300'               # resize height, maintain aspect ratio
-    '400x300>'           # resize only if the image is larger than this
-    '400x300<'           # resize only if the image is smaller than this
-    '50x50%'             # resize width and height to 50%
-    '400x300^'           # resize width, height to minimum 400,300, maintain aspect ratio
-    '2000@'              # resize so max area in pixels is 2000
-    '400x300#'           # resize, crop if necessary to maintain aspect ratio (centre gravity)
-    '400x300#ne'         # as above, north-east gravity
-    '400x300se'          # crop, with south-east gravity
-    '400x300+50+100'     # crop from the point 50,100 with width, height 400,300
-
-RMagickProcessor
-----------------
-The {Dragonfly::Processing::RMagickProcessor RMagickProcessor} uses the {http://rmagick.rubyforge.org RMagick} library and provides the methods
-`thumb`, `crop`, `flip`, `flop`, `greyscale`, `resize`, `resize_and_crop` and `rotate` like the ImageMagickProcessor above.
-
-You can tell it not to use the file system when registering it
-
-    app.processor.register(Dragonfly::Processing::RMagickProcessor){|p| p.use_filesystem = false }
-
-
 Lazy evaluation
 ---------------
 
@@ -89,6 +32,10 @@ Bang method
 
 modifies the image object itself, rather than returning a new object.
 
+ImageMagick Processor
+---------------------
+See {file:ImageMagick}.
+
 Custom Processors
 -----------------
 
@@ -97,12 +44,12 @@ To register a single custom processor:
     app.processor.add :watermark do |temp_object, *args|
       # use temp_object.data, temp_object.path, temp_object.file, etc.
       SomeLibrary.add_watermark(temp_object.data, 'some/watermark/file.png')
-      # return a String, File or Tempfile
+      # return a String, Pathname, File or Tempfile
     end
 
     new_image = image.process(:watermark)
 
-You can create a class like the RMagick one above, in which case all public methods will be counted as processing methods.
+You can create a class like the ImageMagick one above, in which case all public methods will be counted as processing methods.
 Each method takes the temp_object as its argument, plus any other args.
 
     class MyProcessor

data/extra_docs/Rails2.md

@@ -1,6 +1,8 @@
 Using With Rails 2.3
 ====================
 
+**NOTE: RAILS 2.3 IS NOT SUPPORTED IN NEW VERSIONS OF DRAGONFLY SO PLEASE USE VERSION 0.8.4**
+
 Setting up the quick way
 ------------------------
 config/initializers/dragonfly.rb:
@@ -34,7 +36,7 @@ Gems
 ----
 environment.rb
 
-    config.gem 'dragonfly', '~>0.8.6'
+    config.gem 'dragonfly', '0.8.4'
     config.gem 'rack-cache', :lib => 'rack/cache'
 
 Capistrano

data/extra_docs/Rails3.md

@@ -23,7 +23,7 @@ config/initializers/dragonfly.rb:
 
 application.rb:
 
-    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert 0, 'Dragonfly::Middleware', :images
     config.middleware.insert_before 'Dragonfly::Middleware', 'Rack::Cache', {
       :verbose     => true,
       :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
@@ -33,7 +33,7 @@ application.rb:
 Gemfile
 -------
 
-    gem 'dragonfly', '~>0.8.6'
+    gem 'dragonfly', '~>0.9.0'
     gem 'rack-cache', :require => 'rack/cache'
 
 Capistrano
@@ -52,11 +52,3 @@ Use it!
 -------
 
 To see what you can do with the model accessors, see {file:Models}.
-
-Mounting in routes.rb
----------------------
-Instead of mounting as a middleware, you could skip that bit and mount directly in the routes.rb file:
-
-    match '/media(/:dragonfly)', :to => Dragonfly[:images]
-
-Make sure the the path prefix matches the Dragonfly app's configured url_path_prefix (which is /media by default for Rails).

data/extra_docs/ServingRemotely.md

@@ -0,0 +1,83 @@
+Serving Content Remotely
+========================
+
+Dragonfly stores original versions of content in a datastore which could be the {file:DataStorage#File\_datastore filesystem},
+{file:DataStorage#S3\_datastore S3}, etc., but when it comes to serving it, or serving a processed version
+(e.g. an image thumbnail), it fetches it and serves locally from the {Dragonfly::Server dragonfly server}.
+
+For most cases, this is the way to go - you have control over it and you can {file:Caching cache it using HTTP caching}.
+
+However, if for whatever reason you must serve content from the datastore directly, e.g. for lightening the load on your server, Dragonfly
+provides a number of ways of doing this.
+
+Serving Original Content
+------------------------
+The {file:DataStorage#File\_datastore FileDataStore}, {file:DataStorage#S3\_datastore S3DataStore} and
+{file:DataStorage#Couch\_datastore CouchDataStore} allow for serving data directly, so given a Dragonfly app
+
+    app = Dragonfly[:my_app]
+
+and the uid for some stored content
+
+    uid = app.store(Pathname.new('some/file.jpg'))
+
+we can get the remote url using
+
+    app.remote_url_for(uid)            # e.g. http://my-bucket.s3.amazonaws.com/2011/04/01/03/03/05/243/file.jpg
+
+or from a model attachment:
+
+    my_model.attachment.remote_url     # http://my-bucket.s....
+
+Serving Processed Content
+-------------------------
+Serving processed versions of content such as thumbnails remotely is a bit more tricky as we need to upload the thumbnail
+to the datastore in the on-the-fly manner.
+
+Dragonfly provides a way of doing this using `define_url` and `before_serve` methods.
+
+The details of keeping track of/expiring these thumbnails is up to you.
+
+Below is an example using an ActiveRecord 'Thumb' table to keep track of image thumbnails.
+It has two string columns; 'job' and 'uid'.
+
+    app.configure do |c|
+  
+      c.server.before_serve do |job, env|
+        # Before serving, the first time it is requested...
+        # store the thumbnail in the datastore
+        uid = job.store
+        
+        # Keep track of its uid
+        Thumb.create!(
+          :uid => uid,
+          :job => job.serialize     # 'BAhbBls...' - holds all the job info
+        )                           # e.g. fetch 'some_uid' then resize to '40x40'
+      end
+  
+      # Override the .url method...
+      c.define_url do |app, job, opts|
+        thumb = Thumb.find_by_job(job.serialize)
+        # If (fetch 'some_uid' then resize to '40x40') has been stored already..
+        if thumb
+          app.datastore.url_for(thumb.uid)
+        # ...otherwise serve from the Dragonfly server as per usual
+        else
+          app.server.url_for(job)
+        end
+      end
+  
+    end
+
+This would give
+
+    app.fetch('some_uid').thumb('40x40').url    # normal Dragonfly url e.g. /media/BAhbBls...
+    
+then from the second time onwards
+    
+    app.fetch('some_uid').thumb('40x40').url    # http://my-bucket.s3.amazonaws.com/2011...
+
+The above is just an example - there are a number of things you could do with `before_serve` and `define_url` -
+you could use e.g. Redis or some key-value store to keep track of thumbnails.
+You'd also probably want a way of expiring the thumbnails or destroying them when the original is destroyed, but this
+is left up to you as it's outside of the scope of Dragonfly.

data/extra_docs/Sinatra.md

@@ -10,16 +10,16 @@ You can use {Dragonfly::Job Job}'s `to_response` method like so:
 
 `to_response` returns a rack-style response array with status, headers and body.
 
-NOTE: uids from the datastore currently have slashes and dots in them so may cause problems when using ':uid' as
+NOTE: uids from the datastore may have slashes and dots in them so make sure you escape url-escape them when using ':uid' as
 a path segment.
 
 or you can mount as a middleware, like in rails:
 
     Dragonfly[:images].configure_with(:imagemagick) do |c|
-      c.url_path_prefix = '/media'
+      c.url_format = '/media/:job'
     end
 
-    use Dragonfly::Middleware, :images, '/media'
+    use Dragonfly::Middleware, :images
 
     get '/' #... do
       # ...

data/extra_docs/URLs.md

@@ -8,53 +8,61 @@ We can get urls for any kind of job:
     app.fetch('my_uid').process(:flip).url                    # "/BAhbBlsH..."
     app.generate(:text, 'hello').thumb('500x302').gif.url     # "/BAhbCFsHOgZ..."
 
-Path prefix
+Path format
 -----------
-If the app is mounted with a path prefix (such as when using in Rails), then we need to add this prefix
-to the urls:
+The format of the standard urls can be configured using `url_format`:
 
-    app.url_path_prefix = '/media'
+    app.configure do |c|
+      c.url_format = '/:job'
+    end
 
-(or done in a configuration block).
+(or call `app.server.url_format=` directly).
 
-    app.fetch('my_uid').url                                  # "/media/BAhbBlsH..."
+`url_format = '/:job/:basename.:format'`:
 
-This is done for you when using {file:Configuration Rails defaults}.
+    media = app.fetch('my_uid')
+    media.url                        # "/BAhbBlsHOgZmSSIJbWlsawY6BkVU"
+    media.name = 'milk.txt'
+    media.url                        # "/BAhbBlsHOgZmSSIJbWlsawY6BkVU/milk.txt"
+    media.encode(:pdf).url           # "/BAhbB1sHOgZ...RbBzoGZToIcGRm/milk.pdf"
+    media.url(:format => 'bang')     # "/BAhbBlsHOgZmSSIJbWlsawY6BkVU/milk.bang"
+    media.url(:some => 'thing')      # "/BAhbBlsHOgZmSSIJbWlsawY6BkVU/milk.txt?some=thing"
 
-You can override it using
+`url_format = '/some-prefix/:job'`:
 
-    app.fetch('my_uid').url(:path_prefix => '/images')       # "/images/BAhbBlsH..."
+    media = app.fetch('my_uid')
+    media.url                        # "/some-prefix/BAhbBlsHOgZmSSIJbWlsawY6BkVU"
 
-Host
-----
-You can also set a host for the urls
+`url_format = '/blah'`:
 
-    app.url_host = 'http://some.host'
-    app.fetch('my_uid').url                                  # "http://some.host/BAhb..."
+    media = app.fetch('my_uid')
+    media.url                        # "/blah?job=BAhbBlsHOgZmSSIJbWlsawY6BkVU"
 
-    app.fetch('my_uid').url(:host => 'http://localhost:80')  # "http://localhost:80/BAh..."
+When using {file:Models}, any {file:Models#_Magic__Attributes magic attributes} will be used in url generation, e.g.
 
-Suffix
-------
-You can set a suffix for the urls (for example if some other component behaves badly with urls that have no file extension).
+    app.server.url_format = '/frogs/:job/:basename-:width.:format'
 
-Note that this has no effect on the response.
+with
 
-    app.url_suffix = '.jpg'
-    app.fetch('some/uid').url                                # "...b21lL3VpZA.jpg"
+    class Frog
+      image_accessor :face  # columns face_uid, face_name and face_width
+    end
 
-You can also pass it a block, that yields the {Dragonfly::Job Job}, for example:
+gives
 
-    app.url_suffix = proc{|job|
-      "/#{job.uid_basename}#{job.encoded_extname || job.uid_extname}"
-    }
+    frog = Frog.new :face => Pathname.new('froggie.jpg')  # image with width 400
+    
+    frog.face.url                   # "/frogs/BAhbBlsHOgZmSSIIc2RmBjoGRVQ/froggie-400.jpg"
 
-    app.fetch('2007/painting.pdf').url                       # "...eS5ib2R5/painting.pdf"
-    app.fetch('2007/painting.pdf').encode(:png).url          # "...gZlOgbmc/painting.png"
+Host
+----
+You can also set a host for the urls
 
-And you can override it:
+    app.configure{|c| c.url_host = 'http://some.host' }      # or directly on app.server
+    
+    app.fetch('my_uid').url                                  # "http://some.host/BAhb..."
 
-    app.fetch('some/uid').url(:suffix => '/yellowbelly')     # "...b21lL3VpZA/yellowbelly"
+    app.fetch('my_uid').url(:host => 'http://localhost:80')  # "http://localhost:80/BAh..."
 
 Content-Disposition
 -------------------
@@ -79,7 +87,7 @@ Downloaded filename
 To specify the filename the browser uses for 'Save As' dialogues:
 
     app.content_filename = proc{|job, request|
-      "#{job.basename}_#{job.process_steps.first.name}.#{job.encoded_format || job.ext}"
+      "#{job.basename}_#{job.process_steps.first.name}.#{job.format}"
     }
 
 This will for example give the following filenames for the following jobs:
@@ -101,7 +109,7 @@ Then to get the url '/text/hello' to display the text "hello"...
 
 Rails 3 (routes.rb):
 
-    match '/text/:text' => app.endpoint{|params, app|
+    match '/text/:text' => app.endpoint { |params, app|
       app.generate(:text, params[:text])
     }
 
@@ -119,7 +127,7 @@ Rails 3 (routes.rb):
 {http://github.com/joshbuddy/usher Usher}:
 
     routes = Usher::Interface.for(:rack) do
-      add('/text/:text').to app.endpoint{|params, app|
+      add('/text/:text').to app.endpoint { |params, app|
         app.generate(:text, params[:text])
       }
     end
@@ -127,7 +135,7 @@ Rails 3 (routes.rb):
 {http://github.com/joshbuddy/http_router HTTP Router}:
 
     r = HttpRouter.new
-    r.add('/text/:text').to app.endpoint{|params, app|
+    r.add('/text/:text').to app.endpoint { |params, app|
       app.generate(:text, params[:text])
     }
 
@@ -167,3 +175,22 @@ You can also validate for a correct SHA using routed endpoints:
 ... where obviously you need to pass in a 'sha' parameter to the url, which can be found using
 
     app.generate(:text, 'some text').sha
+
+Overriding responses
+--------------------
+You can override/add headers using `response_headers`:
+
+    app.configure do |c|
+      c.response_headers['X-Something'] = 'Custom header'   # set directly..
+      c.response_headers['summink'] = proc{|job, request|   # ...or via a callback
+        job.image? ? 'image yo' : 'not an image'
+      }
+    end
+
+You can intercept the response from the dragonfly server by throwing `:halt` with a Rack response array from inside the `before_serve` callback:
+
+    app.configure do |c|
+      c.server.before_serve do |job, env|
+        throw :halt, [200, {'Content-type' => 'text/plain'}, ['hello']]
+      end
+    end

data/features/rails_3.0.5.feature

@@ -0,0 +1,8 @@
+Feature: champion uses dragonfly in his Rails 3.0.5 application
+  In order to be a champion
+  A user uses dragonfly in his Rails 3.0.5 application
+
+  Scenario: Set up dragonfly using initializer
+    Given a Rails 3.0.5 application set up for using dragonfly
+    Then the manage_album_images cucumber features in my Rails 3.0.5 app should pass
+    And the text_images cucumber features in my Rails 3.0.5 app should pass

data/features/steps/rails_steps.rb

@@ -1,9 +1,5 @@
 RAILS_APP_NAME = 'tmp_app'
 FIXTURES_PATH = ROOT_PATH + "/fixtures"
-GEMFILES = {
-  '2.3.5' => ROOT_PATH + '/Gemfile.rails.2.3.5',
-  '3.0.3' => ROOT_PATH + '/Gemfile',
-}
 
 def fixture_path(version)
   "#{FIXTURES_PATH}/rails_#{version}"
@@ -15,25 +11,18 @@ end
 
 ##############################################################################
 
-{
-  '2.3.5' => "BUNDLE_GEMFILE=#{GEMFILES['2.3.5']} rails #{RAILS_APP_NAME} -m template.rb",
-  '3.0.3' => "BUNDLE_GEMFILE=#{GEMFILES['3.0.3']} bundle exec rails new #{RAILS_APP_NAME} -m template.rb"
-}.each do |version, rails_command|
-
-  Given /^a Rails #{version} application set up for using dragonfly$/ do
-    raise "Problem setting up Rails app" unless `
-      cd #{fixture_path(version)} &&
-      rm -rf #{RAILS_APP_NAME} &&
-      #{rails_command}`
-  end
-  
+Given "a Rails 3.0.5 application set up for using dragonfly" do
+  raise "Problem setting up Rails app" unless `
+    cd #{fixture_path('3.0.5')} &&
+    rm -rf #{RAILS_APP_NAME} &&
+    bundle exec rails new #{RAILS_APP_NAME} -m template.rb`
 end
 
 Then /^the (.+) cucumber features in my Rails (.+) app should pass$/ do |filename, version|
   puts "\n*** RUNNING FEATURES IN THE RAILS APP... ***\n"
   path = File.join(fixture_path(version), RAILS_APP_NAME)
-  `cd #{path} && BUNDLE_GEMFILE=#{GEMFILES[version]} RAILS_ENV=cucumber rake db:migrate`
-  features_passed = system "cd #{path} && BUNDLE_GEMFILE=#{GEMFILES[version]} cucumber features/#{filename}.feature"
+  `cd #{path} && RAILS_ENV=cucumber rake db:migrate`
+  features_passed = system "cd #{path} && cucumber features/#{filename}.feature"
   puts "\n*** FINISHED RUNNING FEATURES IN THE RAILS APP ***\n"
   raise "Features failed" unless features_passed
 end