oahu-dragonfly 0.8.2

data/extra_docs/Mongo.md

@@ -0,0 +1,45 @@
+Mongo
+=====
+Dragonfly can be used with any ActiveModel-compatible model, therefore libraries like [Mongoid](http://mongoid.org) work out of the box.
+
+Furthermore, Mongo DB has support for storing blob-like objects directly in the database (using MongoDB 'GridFS'),
+so you can make use of this with the supplied {Dragonfly::DataStorage::MongoDataStore MongoDataStore}.
+
+For more info about ActiveModel, see {file:Models}.
+
+For more info about using the Mongo data store, see {file:DataStorage}.
+
+Example setup in Rails, using Mongoid
+-------------------------------------
+In config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    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
+    end
+
+    # Allow all mongoid models to use the macro 'image_accessor'
+    app.define_macro_on_include(Mongoid::Document, :image_accessor)
+
+    # ... any other setup, see Rails docs
+
+Then in models:
+
+    class Album
+      include Mongoid::Document
+
+      field :cover_image_uid
+      image_accessor :cover_image
+
+      # ...
+    end
+
+See {file:Models} for more info.

data/extra_docs/Processing.md

@@ -0,0 +1,77 @@
+Processing
+==========
+Registered processors allow you to modify data, e.g. resizing an image.
+
+You can register as many processors as you like.
+
+Let's say we have a Dragonfly app
+
+    app = Dragonfly[:images]
+
+and an image object (actually a {Dragonfly::Job Job} object)...
+
+    image = app.fetch('some/uid')
+
+...OR a Dragonfly model accessor...
+
+    image = @album.cover_image
+
+We can process it using any processing methods that have been registered with the processor.
+
+Lazy evaluation
+---------------
+
+    new_image = image.process(:some_method)
+
+doesn't actually do anything until you call something on the returned {Dragonfly::Job Job} object, like `url`, `data`, etc.
+
+Bang method
+-----------
+
+    image.process!(:some_method)
+
+modifies the image object itself, rather than returning a new object.
+
+ImageMagick Processor
+---------------------
+See {file:ImageMagick}.
+
+Custom Processors
+-----------------
+
+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, Pathname, File or Tempfile
+    end
+
+    new_image = image.process(:watermark)
+
+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
+
+      def coolify(temp_object, opts={})
+        SomeLib.coolify(temp_object.data, opts)
+      end
+
+      def uglify(temp_object, ugliness)
+        `uglify -i #{temp_object.path} -u #{ugliness}`
+      end
+
+      private
+
+      def my_helper_method
+        # do stuff
+      end
+
+    end
+
+    app.processor.register(MyProcessor)
+
+    new_image = image.coolify(:some => :args)
+
+    new_image = image.uglify(:loads)

data/extra_docs/Rack.md

@@ -0,0 +1,52 @@
+Rack
+====
+For more info about using Rack applications, see the docs at {http://rack.rubyforge.org/}
+
+Basic usage involves storing data (e.g. images),
+then serving it in some form.
+
+A basic rackup file `config.ru`:
+
+    require 'rubygems'
+    require 'dragonfly'
+
+    Dragonfly[:my_app_name].configure do |c|
+      # ... configuration here
+    end
+
+    run Dragonfly:App[:my_app_name]
+
+See {file:Configuration} for more details.
+
+The basic flow is instantiate an app -> configure it -> run it.
+
+Example: Using to serve resized images
+--------------------------------------
+
+`config.ru`:
+
+    require 'rubygems'
+    require 'dragonfly'
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+    run app
+
+This enables the app to use all the ImageMagick goodies provided by Dragonfly (see {file:Configuration}).
+By default the {Dragonfly::DataStorage::FileDataStore file data store} is used.
+
+In the console:
+
+    app = Dragonfly[:images]
+
+    # Store
+    uid = app.store(File.new('path/to/image.png'))      # ===> unique uid
+
+    # Get the url for a thumbnail
+    url = app.fetch(uid).thumb('400x300').url           # ===> "/media/BAhbBlsHOgZmIg9hc..."
+
+Now when we visit the url `/media/BAhbBlsHOgZmIg9hc...` in the browser, we get a resized image!
+
+Mounting in Rack
+----------------
+See {file:URLs}

data/extra_docs/Rails2.md

@@ -0,0 +1,57 @@
+Using With Rails 2.3
+====================
+
+**NOTE: RAILS 2.3 IS NOT SUPPORTED IN NEW VERSIONS OF DRAGONFLY SO PLEASE USE VERSION 0.8.2**
+
+Setting up the quick way
+------------------------
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly/rails/images'
+
+Setting up the more explicit way
+--------------------------------
+You can do the above explicitly.
+
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    app = Dragonfly[:images]
+    app.configure_with(:imagemagick)
+    app.configure_with(:rails)
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+environment.rb:
+
+    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert_before 'Dragonfly::Middleware', 'Rack::Cache', {
+      :verbose     => true,
+      :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
+      :entitystore => "file:#{Rails.root}/tmp/dragonfly/cache/body"
+    }
+
+Gems
+----
+environment.rb
+
+    config.gem 'dragonfly', '0.8.2'
+    config.gem 'rack-cache', :lib => 'rack/cache'
+
+Capistrano
+----------
+If using Capistrano with the above, you probably will want to keep the cache between deploys, so in deploy.rb:
+
+    namespace :dragonfly do
+      desc "Symlink the Rack::Cache files"
+      task :symlink, :roles => [:app] do
+        run "mkdir -p #{shared_path}/tmp/dragonfly && ln -nfs #{shared_path}/tmp/dragonfly #{release_path}/tmp/dragonfly"
+      end
+    end
+    after 'deploy:update_code', 'dragonfly:symlink'
+
+Use it!
+-------
+
+To see what you can do with the model accessors, see {file:Models}.

data/extra_docs/Rails3.md

@@ -0,0 +1,62 @@
+Using With Rails 3
+==================
+
+Setting up the quick way
+------------------------
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly/rails/images'
+
+Setting up the more explicit way
+--------------------------------
+You can do the above explicitly.
+
+config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    app = Dragonfly[:images]
+    app.configure_with(:imagemagick)
+    app.configure_with(:rails)
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+application.rb:
+
+    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :images
+    config.middleware.insert_before 'Dragonfly::Middleware', 'Rack::Cache', {
+      :verbose     => true,
+      :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
+      :entitystore => "file:#{Rails.root}/tmp/dragonfly/cache/body"
+    }
+
+Gemfile
+-------
+
+    gem 'dragonfly', '~>0.8.2'
+    gem 'rack-cache', :require => 'rack/cache'
+
+Capistrano
+----------
+If using Capistrano with the above, you probably will want to keep the cache between deploys, so in deploy.rb:
+
+    namespace :dragonfly do
+      desc "Symlink the Rack::Cache files"
+      task :symlink, :roles => [:app] do
+        run "mkdir -p #{shared_path}/tmp/dragonfly && ln -nfs #{shared_path}/tmp/dragonfly #{release_path}/tmp/dragonfly"
+      end
+    end
+    after 'deploy:update_code', 'dragonfly:symlink'
+
+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/Sinatra.md

@@ -0,0 +1,25 @@
+Sinatra
+=======
+You can use {Dragonfly::Job Job}'s `to_response` method like so:
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+    get '/images/:size.:format' do |size, format|
+      app.fetch_file('~/some/image.png').thumb(size).encode(format).to_response(env)
+    end
+
+`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
+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'
+    end
+
+    use Dragonfly::Middleware, :images
+
+    get '/' #... do
+      # ...

data/extra_docs/URLs.md

@@ -0,0 +1,169 @@
+URLs
+====
+
+We can get urls for any kind of job:
+
+    app = Dragonfly[:images]
+
+    app.fetch('my_uid').process(:flip).url                    # "/BAhbBlsH..."
+    app.generate(:text, 'hello').thumb('500x302').gif.url     # "/BAhbCFsHOgZ..."
+
+Path prefix
+-----------
+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:
+
+    app.url_path_prefix = '/media'
+
+(or done in a configuration block).
+
+    app.fetch('my_uid').url                                  # "/media/BAhbBlsH..."
+
+This is done for you when using {file:Configuration Rails defaults}.
+
+You can override it using
+
+    app.fetch('my_uid').url(:path_prefix => '/images')       # "/images/BAhbBlsH..."
+
+Host
+----
+You can also set a host for the urls
+
+    app.url_host = 'http://some.host'
+    app.fetch('my_uid').url                                  # "http://some.host/BAhb..."
+
+    app.fetch('my_uid').url(:host => 'http://localhost:80')  # "http://localhost:80/BAh..."
+
+Suffix
+------
+You can set a suffix for the urls (for example if some other component behaves badly with urls that have no file extension).
+
+Note that this has no effect on the response.
+
+    app.url_suffix = '.jpg'
+    app.fetch('some/uid').url                                # "...b21lL3VpZA.jpg"
+
+You can also pass it a block, that yields the {Dragonfly::Job Job}, for example:
+
+    app.url_suffix = proc{|job|
+      "/#{job.uid_basename}#{job.encoded_extname || job.uid_extname}"
+    }
+
+    app.fetch('2007/painting.pdf').url                       # "...eS5ib2R5/painting.pdf"
+    app.fetch('2007/painting.pdf').encode(:png).url          # "...gZlOgbmc/painting.png"
+
+And you can override it:
+
+    app.fetch('some/uid').url(:suffix => '/yellowbelly')     # "...b21lL3VpZA/yellowbelly"
+
+Content-Disposition
+-------------------
+You can manually set the content-disposition of the response:
+
+    app.content_disposition = :attachment    # should be :inline or :attachment (or :hidden)
+
+`:attachment` tells the browser to download it, `:inline` tells it to display in-browser if possible.
+
+You can also use a block:
+
+    app.content_disposition = proc{|job, request|
+      if job.format == :jpg || request['d'] == 'inline' # request is a Rack::Request object
+        :inline
+      else
+        :attachment
+      end
+    }
+
+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}"
+    }
+
+This will for example give the following filenames for the following jobs:
+
+    app.fetch('some/tree.png').process(:greyscale)      # -> 'tree_greyscale.png'
+    app.fetch('some/tree.png').process(:greyscale).gif  # -> 'tree_greyscale.gif'
+
+By default the original filename is used, with a modified extension if it's been encoded.
+
+Routed Endpoints
+----------------
+You can also use a number of Rack-based routers and create Dragonfly endpoints.
+
+If we have an app set up for using ImageMagick:
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+Then to get the url '/text/hello' to display the text "hello"...
+
+Rails 3 (routes.rb):
+
+    match '/text/:text' => app.endpoint{|params, app|
+      app.generate(:text, params[:text])
+    }
+
+{http://github.com/josh/rack-mount Rack-Mount}:
+
+    Routes = Rack::Mount::RouteSet.new do |set|
+
+      set.add_route app.endpoint{|params, a| a.generate(:text, params[:text]) },
+                      :path_info => %r{/text/(?:<text>.+)}
+
+      # ...
+
+    end
+
+{http://github.com/joshbuddy/usher Usher}:
+
+    routes = Usher::Interface.for(:rack) do
+      add('/text/:text').to app.endpoint{|params, app|
+        app.generate(:text, params[:text])
+      }
+    end
+
+{http://github.com/joshbuddy/http_router HTTP Router}:
+
+    r = HttpRouter.new
+    r.add('/text/:text').to app.endpoint{|params, app|
+      app.generate(:text, params[:text])
+    }
+
+In each case the url will need to be generated by the router of choice, or manually.
+
+Simple Endpoints
+----------------
+{Dragonfly::Job Job} objects can also be turned straight into Rack endpoints using `to_app`, e.g. in Rails 3:
+
+    match '/beach' => app.fetch_file('~/some/image.png').thumb('100x100#').jpg.to_app
+
+
+Denial-of-service attacks
+-------------------------
+Although the standard urls are fairly cryptic, a malicious person who knows the Dragonfly source code could potentially
+work out how to generate urls to spam your server with heavy requests, e.g. resize to 100000 by 100000 pixels.
+
+Therefore the app can be protected by requiring the presence of a "DOS-protection" SHA in the urls:
+
+    app.configure do |c|
+      c.protect_from_dos_attacks = true
+      c.secret = 'You should supply some random secret here'
+    end
+
+Then the standard generated urls will have a SHA query parameter attached:
+
+    app.fetch('my_uid').url          # "/BAhbBlsHOgZmIghzZGY?s=df76ba27"
+
+Any requests without the correct SHA parameter result in a 400 (bad parameters) error response.
+
+You can also validate for a correct SHA using routed endpoints:
+
+    match '/text/:text' => app.endpoint{|params, app|
+      app.generate(:text, params[:text]).validate_sha!(params[:sha])
+    }
+
+... where obviously you need to pass in a 'sha' parameter to the url, which can be found using
+
+    app.generate(:text, 'some text').sha