dragonfly 0.9.15 → 1.0

data/extra_docs/Mongo.md

@@ -1,42 +0,0 @@
-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]
-
-    # 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 :db => Mongoid.database
-    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

@@ -1,77 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,57 +0,0 @@
-Using With Rails 2.3
-====================
-
-**NOTE: RAILS 2.3 IS NOT SUPPORTED IN NEW VERSIONS OF DRAGONFLY SO PLEASE USE VERSION 0.8.5**
-
-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 0, 'Dragonfly::Middleware', :images, '/media'
-    config.middleware.insert_before 'Dragonfly::Middleware', 'Rack::Cache', {
-      :verbose     => true,
-      :metastore   => URI.encode("file:#{Rails.root}/tmp/dragonfly/cache/meta"),
-      :entitystore => URI.encode("file:#{Rails.root}/tmp/dragonfly/cache/body")
-    }
-
-Gems
-----
-environment.rb
-
-    config.gem 'dragonfly', '0.8.5'
-    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

@@ -1,56 +0,0 @@
-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 0, 'Rack::Cache', {
-      :verbose     => true,
-      :metastore   => URI.encode("file:#{Rails.root}/tmp/dragonfly/cache/meta"),
-      :entitystore => URI.encode("file:#{Rails.root}/tmp/dragonfly/cache/body")
-    } # unless Rails.env.production?  ## uncomment this 'unless' in Rails 3.1,
-                                      ## because it already inserts Rack::Cache in production
-    
-    config.middleware.insert_after 'Rack::Cache', 'Dragonfly::Middleware', :images
-
-Gemfile
--------
-
-    gem 'dragonfly', '~>0.9.15'
-    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}.

data/extra_docs/ServingRemotely.md

@@ -1,104 +0,0 @@
-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.
-
-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.s3.amazonaws.com/2011...
-
-Processed Content
------------------
-If using models, the quick and easy way to serve e.g. image thumbnails remotely is to process them _on upload_
-like most other attachment ruby gems (see {file:Models#Up-front_thumbnailing}),
-e.g. for my avatar model,
-
-    class Avatar
-      image_accessor :image do
-        copy_to(:small_image){|a| a.thumb('200x200#') }
-      end
-      image_accessor :small_image
-    end
-
-Then we can use `remote_url` for for each accessor.
-
-    avatar.image.remote_url            # http://my-bucket.s3.amazonaws.com/some/path.jpg
-    avatar.small_image.remote_url      # http://my-bucket.s3.amazonaws.com/some/other/path.jpg
-
-However, this has all the limitations that come with up-front processing, such as having to regenerate the thumbnail when the size requirement changes.
-
-Serving Processed Content *on-the-fly*
---------------------------------------
-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.
-
-We need to keep track of which thumbnails have been already created, by storing a uid for each one.
-Below is an example using an ActiveRecord 'Thumb' table to keep track of already created thumbnail uids.
-It has two string columns; 'job' and 'uid'.
-
-    app.configure do |c|
-  
-      # 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, give the datastore's remote url ...
-        if thumb
-          app.datastore.url_for(thumb.uid)
-        # ...otherwise give the local Dragonfly server url
-        else
-          app.server.url_for(job)
-        end
-      end
-
-      # Before serving from the local Dragonfly server...
-      c.server.before_serve do |job, env|
-        # ...store the thumbnail in the datastore...
-        uid = job.store
-        
-        # ...keep track of its uid so next time we can serve directly from the datastore
-        Thumb.create!(
-          :uid => uid,
-          :job => job.serialize     # 'BAhbBls...' - holds all the job info
-        )                           # e.g. fetch 'some_uid' then resize to '40x40'
-      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

@@ -1,25 +0,0 @@
-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 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_format = '/media/:job'
-    end
-
-    use Dragonfly::Middleware, :images
-
-    get '/' #... do
-      # ...

data/extra_docs/URLs.md

@@ -1,203 +0,0 @@
-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 format
------------
-The format of the standard urls can be configured using `url_format`:
-
-    app.configure do |c|
-      c.url_format = '/:job'
-    end
-
-(or call `app.server.url_format=` directly).
-
-`url_format = '/:job/:basename.:format'`:
-
-    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"
-
-`url_format = '/some-prefix/:job'`:
-
-    media = app.fetch('my_uid')
-    media.url                        # "/some-prefix/BAhbBlsHOgZmSSIJbWlsawY6BkVU"
-
-`url_format = '/blah'`:
-
-    media = app.fetch('my_uid')
-    media.url                        # "/blah?job=BAhbBlsHOgZmSSIJbWlsawY6BkVU"
-
-When using {file:Models}, any {file:Models#_Magic__Attributes magic attributes} will be used in url generation, e.g.
-
-    app.server.url_format = '/frogs/:job/:basename-:width.:format'
-
-with
-
-    class Frog
-      image_accessor :face  # columns face_uid, face_name and face_width
-    end
-
-gives
-
-    frog = Frog.new :face => Pathname.new('froggie.jpg')  # image with width 400
-    
-    frog.face.url                   # "/frogs/BAhbBlsHOgZmSSIIc2RmBjoGRVQ/froggie-400.jpg"
-
-Host
-----
-You can also set a host for the urls
-
-    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('my_uid').url(:host => 'http://localhost:80')  # "http://localhost:80/BAh..."
-
-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|
-      if job.process_steps.any?
-        "#{job.basename}_#{job.process_steps.first.name}.#{job.format}"
-      else
-        "#{job.basename}.#{job.format}"
-      end
-    }
-
-This will for example give the following filenames for the following jobs:
-
-    app.fetch('some/tree.png')                          # -> 'tree.png'
-    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.
-
-NOTE: Ruby treats curly braces slightly differently to `do`...`end` so be aware of this when using the above examples.
-
-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
-
-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