dragonfly 0.6.2 → 0.7.0

data/extra_docs/Processing.md

@@ -1,98 +1,122 @@
 Processing
 ==========
 
-Processing is changing content in some way, and does not involve encoding.
-For example, resizing an image is classed as processing, whereas converting it from 'png' to 'jpeg' is classed as encoding.
+Changing data in some way, e.g. resizing an image, comes under the banner of Processing.
 
-All processing jobs are defined by a processing method and a processing options hash (which is passed to the method).
+You can register as many processors as you like.
 
-Let's say we have a dragonfly app called 'images'
+Let's say we have a Dragonfly app
 
-    app = Dragonfly::App[:images]
+    app = Dragonfly[:images]
 
-Data gets passed around between the datastore, processor, analyser, etc. in the form of an {Dragonfly::ExtendedTempObject ExtendedTempObject}.
+and an image object (actually a {Dragonfly::Job Job} object)...
 
-    temp_object = app.create_object(File.new('path/to/image.png'))
+    image = app.fetch('some/uid')
 
-We can process this object with any of the methods which have been registered with the app's processor.
-For example, registering the {Dragonfly::Processing::RMagickProcessor rmagick processor}
+...OR a Dragonfly model accessor...
 
-    app.register_processor(Dragonfly::Processing::RMagickProcessor)
+    image = @album.cover_image
 
-give us the processing methods `resize`, `crop`, `resize_and_crop`, `rotate`, etc.
+We can process it using any processing methods that have been registered with the processor.
 
-    temp_object.process(:resize, :geometry => '30x30!')        # => returns a new temp_object with width x height = 30x30
-    temp_object.process!(:resize, :geometry => '30x30!')       # => resizes its own data
+RMagickProcessor
+----------------
+The {Dragonfly::Processing::RMagickProcessor RMagickProcessor} is registered by default by
+the {Dragonfly::Config::RMagick RMagick configuration} used by 'dragonfly/rails/images'.
 
-The saved configuration {Dragonfly::Config::RMagickImages RMagickImages} registers the above processor automatically.
+If not already registered:
 
-Custom Processing
------------------
+    app.processor.register(Dragonfly::Processing::RMagickProcessor)
 
-To register a custom processor, derive from {Dragonfly::Processing::Base Processing::Base} and register.
-Each method takes the temp_object, and the (optional) processing options hash as its argument.
+gives us these methods:
 
-    class MyProcessor < Dragonfly::Processing::Base
-    
-      def black_and_white(temp_object, opts={})
-        # use temp_object.data, temp_object.path, etc...
-        # ...process and return a String, File, Tempfile or TempObject
-      end
+    image.process(:thumb, '400x300#')            # see below
 
-      # ... add as many methods as you wish
+    image.process(:crop, :width => 40, :height => 50, :x => 20, :y => 30)
+    image.process(:crop, :width => 40, :height => 50, :gravity => 'ne')
 
-    end
+    image.process(:flip)                         # flips it vertically
+    image.process(:flop)                         # flips it horizontally
 
-    app = Dragonfly::App[:images]
-    app.register_processor(MyProcessor)
+    image.process(:greyscale, :depth => 128)     # default depth 256
 
-You can register multiple processors.
+    image.process(:resize, '40x40')
+    image.process(:resize_and_crop, :width => 40, :height=> 50, :gravity => 'ne')
 
-As with analysers and encoders, if the processor is {Dragonfly::Configurable configurable}, we can configure it as we register it if we need to
+    image.process(:rotate, 45, :background_colour => 'transparent')   # default bg black
 
-    app.register_processor(MyProcessor) do |p|
-      p.some_attribute = 'hello'
-    end
+    image.process(:vignette)                     # options :x, :y, :radius, :sigma
+
+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
+
+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.
 
-Your new processing method is now available to use:
-    
-    temp_object = app.create_object(File.new('path/to/image.png'))
-    temp_object.process(:black_and_white, :some => 'option')         # processed temp_object
-
-To get the url for content processed by your custom processor, the long way is using something like:
-
-    app.url_for('some_uid',
-      :processing_method => :black_and_white,
-      :processing_options => {:size => '30x30'},
-      :format => :png
-    )
-
-or if using an activerecord model,
-
-    my_model.preview_image.url('some_uid',
-      :processing_method => :black_and_white,
-      :processing_options => {:size => '30x30'},
-      :format => :png
-    )
-
-However, this could soon get tedious if using more than once, so the best thing is to register a shortcut for it.
-So in your configuration of the Dragonfly app (or in an initializer if using 'dragonfly/rails/images') you
-could do something like:
-
-    app.parameters.add_shortcut(/^bw-(\d*x\d*)$/) do |string, match_data|
-      {
-        :processing_method => :black_and_white,
-        :processing_options => {:size => match_data[1]},
-        :format => :png
-      }
+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, File or Tempfile
     end
-    
-Now you can get urls by using the shortcut:
 
-    app.url_for('some_uid', 'bw-30x30')
+    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.
+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
 
-or with activerecord:
+    app.processor.register(MyProcessor)
 
-    my_model.preview_image.url('bw-30x30')
+    new_image = image.coolify(:some => :args)
 
-For more information about shortcuts, see {file:Shortcuts}.
+    new_image = image.uglify(:loads)

data/extra_docs/Rack.md

@@ -0,0 +1,53 @@
+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]
+    app.configure_with(:rmagick)
+
+    run app
+
+This enables the app to use all the RMagick 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,44 @@
+Using With Rails 2.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(:rmagick)
+    app.configure_with(:rails)
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+environment.rb:
+
+    config.middleware.insert 0, 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert 0, '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.7.0'
+    config.gem 'rmagick', :lib => 'RMagick'
+    config.gem 'rack-cache', :lib => 'rack/cache'
+
+Use it!
+-------
+
+To see what you can do with the model accessors, see {file:Models}.

data/extra_docs/Rails3.md

@@ -0,0 +1,51 @@
+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(:rmagick)
+    app.configure_with(:rails)
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+application.rb:
+
+    config.middleware.insert 0, 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert 0, 'Rack::Cache', {
+      :verbose     => true,
+      :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
+      :entitystore => "file:#{Rails.root}/tmp/dragonfly/cache/body"
+    }
+
+Gemfile
+-------
+
+    gem 'dragonfly', '~>0.7.0'
+    gem 'rmagick', :require => 'RMagick'
+    gem 'rack-cache', :require => 'rack/cache'
+
+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,21 @@
+Sinatra
+=======
+You can use {Dragonfly::Job Job}'s `to_response` method like so:
+
+    get '/images/:size.:format' do |size, format|
+      app.fetch_file('~/some/image.png').thumb(size).encode(format).to_response
+    end
+
+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(:rmagick) do |c|
+      c.url_path_prefix = '/media'
+    end
+
+    use Dragonfly::Middleware, :images, '/media'
+
+    get '/' #... do
+      # ...

data/extra_docs/URLs.md

@@ -0,0 +1,114 @@
+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..."
+
+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 RMagick:
+
+    app = Dragonfly[:images].configure_with(:rmagick)
+
+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