dragonfly 0.8.6 → 0.9.0

data/extra_docs/Analysers.md

@@ -1,52 +1,10 @@
 Analysers
 =========
+Analysers are registered with Dragonfly apps for adding methods to {file:GeneralUsage Job} objects and {file:Models model attachments} such as `width`, `height`, etc.
 
-Analysing data for things like width, mime_type, etc. come under the banner of Analysis.
-
-You can register as many analysers 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 analyse it using any analysis methods that have been registered with the analyser.
-
-ImageMagickAnalyser
--------------------
-The {Dragonfly::Analysis::ImageMagickAnalyser ImageMagickAnalyser} is registered by default by the
-{Dragonfly::Config::ImageMagick ImageMagick configuration} used by 'dragonfly/rails/images'.
-
-If not already registered:
-
-    app.analyser.register(Dragonfly::Analysis::ImageMagickAnalyser)
-
-gives us these methods:
-
-    image.width               # => 280
-    image.height              # => 355
-    image.aspect_ratio        # => 0.788732394366197
-    image.portrait?           # => true
-    image.landscape?          # => false
-    image.depth               # => 8
-    image.number_of_colours   # => 34703
-    image.format              # => :png
-
-RMagickAnalyser
--------------------
-The {Dragonfly::Analysis::RMagickAnalyser RMagickAnalyser} uses the {http://rmagick.rubyforge.org RMagick} library and provides methods `width`, `height`, `aspect_ratio`,
-`portrait?`, `landscape?`, `depth`, `number_of_colours` and `format` like the ImageMagickAnalyser.
-
-You can tell it not to use the file system when registering it
-
-    app.analyser.register(Dragonfly::Analysis::RMagickAnalyser){|a| a.use_filesystem = false }
+ImageMagick Analyser
+--------------------
+See {file:ImageMagick}.
 
 FileCommandAnalyser
 -------------------
@@ -63,10 +21,12 @@ gives us:
 
     image.mime_type    # => 'image/png'
 
-It doesn't use the filesystem by default (it operates on in-memory strings), but we can make it do so by using
+You shouldn't need to configure it but if you need to:
 
     app.analyser.register(Dragonfly::Analysis::FileCommandAnalyser) do |a|
-      a.use_filesystem = true
+      a.use_filesystem = false                 # defaults to true
+      a.file_command = '/opt/local/bin/file'   # defaults to 'file'
+      a.num_bytes_to_check = 1024              # defaults to 255 - only applies if not using the filesystem
     end
 
 Custom Analysers

data/extra_docs/Configuration.md

@@ -5,16 +5,16 @@ Given a Dragonfly app
 
     app = Dragonfly[:app_name]
 
-Configuration can either be done like so...
+Configuration can either be done using a block...
 
     app.configure do |c|
-      c.url_path_prefix = '/media'
+      c.url_format = '/media/:job'
       # ...
     end
 
-...or directly like so...
+...or directly...
 
-    app.url_path_prefix = '/media'
+    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:
@@ -25,11 +25,10 @@ Here is an example of an app with all attributes configured:
       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.infer_mime_type_from_file_ext = false               # defaults to true
+      c.trust_file_extensions = false                       # defaults to true
 
-      c.url_path_prefix = '/images'                         # defaults to nil
+      c.url_format = '/images/:job/:basename.:format'       # defaults to '/:job/:basename.:format'
       c.url_host = 'http://some.domain.com:4000'            # defaults to nil
-      c.url_suffix = '.jpg'                                 # defaults to nil - has no effect other than change the url
 
       c.content_filename = proc{|job, request|              # defaults to the original name, with modified ext if encoded
         "file.#{job.ext}"
@@ -53,6 +52,28 @@ Here is an example of an app with all attributes configured:
         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/convert"         # defaults to "convert"
+      c.log_commands = true                                 # defaults to false
     end
 
 Where is configuration done?
@@ -70,34 +91,19 @@ ImageMagick
 
     app.configure_with(:imagemagick)
 
-The {Dragonfly::Config::ImageMagick ImageMagick configuration} registers the app with the {Dragonfly::Analysis::ImageMagickAnalyser ImageMagickAnalyser}, {Dragonfly::Processing::ImageMagickProcessor ImageMagickProcessor},
-{Dragonfly::Encoding::ImageMagickEncoder ImageMagickEncoder} and {Dragonfly::Generation::ImageMagickGenerator ImageMagickGenerator}, and adds the 'job shortcuts'
-`thumb`, `jpg`, `png`, `gif` and `convert`.
+The {Dragonfly::ImageMagick::Config ImageMagick configuration} registers the app with the {Dragonfly::ImageMagick::Analyser ImageMagick Analyser}, {Dragonfly::ImageMagick::Processor ImageMagick Processor},
+{Dragonfly::ImageMagick::Encoder ImageMagick Encoder} and {Dragonfly::ImageMagick::Generator 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.
 
-RMagick
--------
-
-    app.configure_with(:rmagick)
-
-The {Dragonfly::Config::RMagick RMagick configuration} registers the app with the {Dragonfly::Analysis::RMagickAnalyser RMagickAnalyser}, {Dragonfly::Processing::RMagickProcessor RMagickProcessor},
-{Dragonfly::Encoding::RMagickEncoder RMagickEncoder} and {Dragonfly::Generation::RMagickGenerator RMagickGenerator}, and adds the 'job shortcuts'
-`thumb`, `jpg`, `png` and `gif`.
-
-By default the processor, analyser, encoder and generator pass data around using tempfiles.
-You can make it pass data around using in-memory strings using
-
-    app.configure_with(:rmagick, :use_filesystem => false)
-
 Rails
 -----
 
     app.configure_with(:rails)
 
-The {Dragonfly::Config::Rails Rails configuration} points the log to the Rails logger, configures the file data store root path, sets the url_path_prefix to /media, and
+The {Dragonfly::Config::Rails 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 {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} for helping with mime_type validations.
 
 The file 'dragonfly/rails/images' does this for you.
@@ -136,3 +142,12 @@ You can also carry on configuring by passing a block
       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)

data/extra_docs/Couch.md

@@ -0,0 +1,49 @@
+CouchDB
+=====
+Dragonfly can be used with any ActiveModel-compatible model, and so you can use it with CouchDB using [CouchRest::Model](https://github.com/couchrest/couchrest_model).
+
+Since CouchDB allows you to store files directly on documents as attachments, you can also use the supplied {Dragonfly::DataStorage::CouchDataStore CouchDataStore}.
+which allows storing files as attachments directly on documents.
+
+For more info about ActiveModel, see {file:Models}.
+
+For more info about using the Couch data store, see {file:DataStorage}.
+
+Example setup in Rails, using CouchRest::Model
+-------------------------------------
+In config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    app = Dragonfly[:images]
+
+    # Get database config from config/couchdb.yml
+    couch_settings = YAML.load_file(Rails.root.join('config/couchdb.yml'))[Rails.env]
+
+    # Configure to use ImageMagick, Rails defaults, and the Couch data store
+    app.configure_with(:imagemagick)
+    app.configure_with(:rails) do |c|
+      c.datastore = Dragonfly::DataStorage::CouchDataStore.new(
+        :host => couch_settings['host'],
+        :port => couch_settings['port'],
+        :username => couch_settings['username'],
+        :password => couch_settings['password'],
+        :database => couch_settings['database']
+      )
+    end
+
+    # Allow all CouchRest::Model models to use the macro 'image_accessor'
+    app.define_macro(CouchRest::Model::Base, :image_accessor)
+
+    # ... any other setup, see Rails docs
+
+Then in models:
+
+    class Album < CouchRest::Model::Base
+      property :cover_image_uid
+      image_accessor :cover_image
+
+      # ...
+    end
+
+See {file:Models} for more info.

data/extra_docs/DataStorage.md

@@ -1,6 +1,5 @@
 Data Storage
 ============
-
 Each dragonfly app has a key-value datastore to store the content (originals only).
 
 Lets say we have an app
@@ -9,14 +8,14 @@ Lets say we have an app
 
 Then we can store data like so:
 
-    uid = app.store('SOME CONTENT')       # Can pass in a String, File or Tempfile
+    # Can pass in a String, Pathname, File or Tempfile
+    uid = app.store('SOME CONTENT')
 
-We can also save metadata at the same time, and give it a name and format (if you pass in a File object the filename is used by default)
+We can also save metadata at the same time, and any other options the configured datastore accepts
 
     uid = app.store('SOME CONTENT',
-      :meta => {:time => Time.now},
-      :name => 'great_content.txt',
-      :format => :txt
+      :meta => {:time => Time.now, :name => 'content.txt'},
+      :some => 'option'
     )
 
 We can get content with
@@ -26,14 +25,27 @@ We can get content with
 
 We can also get the extra saved attributes
 
-    content.meta         # {:time => Sat Aug 14 12:04:13 +0100 2010}
-    content.name         # 'great_content.txt'
-    content.format       # :txt
+    content.meta         # {:time => Sat Aug 14 12:04:13 +0100 2010, :name => 'content.txt'}
+    content.name         # 'content.txt'
 
 We can destroy it with
 
     app.destroy(uid)
 
+Serving directly from the datastore
+-----------------------------------
+Datastores can optionally serve data directly too, by implementing `url_for`
+
+    app.datastore.url_for(uid, :some => 'option')   # ---> "http://some.url/thing.txt"
+
+or (the same)
+
+    app.remote_url_for(uid, :some => 'option')
+
+or
+
+    my_model.remote_url(:some => 'option')
+
 You can create your own datastore, or use one of the provided ones as outlined below.
 
 File datastore
@@ -48,9 +60,22 @@ If for whatever reason you need to configure it again:
     app.datastore = Dragonfly::DataStorage::FileDataStore.new
 
     app.datastore.configure do |d|
-      d.root_path = '/my/custom/path'              # defaults to /var/tmp/dragonfly
+      d.root_path = '/filesystem/path/public/place'   # defaults to /var/tmp/dragonfly
+      d.server_root = '/filesystem/path/public'       # filesystem root for serving from - default to nil
+      d.store_meta = false                            # default to true - can be switched off to avoid
+                                                      #  saving an extra .meta file if meta not needed
     end
 
+You can serve directly from the FileDataStore if the `server_root` is set.
+
+To customize the storage path (and therefore the uid), use the `:path` option on store
+
+    app.store("SOME CONTENT", :path => 'some/path.txt')
+
+To do this on a per-model basis see {file:Models#Storage_options}.
+
+**BEWARE!!!!** you must make sure the path (which will become the uid for the content) is unique and changes each time the content
+is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
 
 S3 datastore
 ------------
@@ -62,10 +87,28 @@ To configure with the {Dragonfly::DataStorage::S3DataStore S3DataStore}:
       c.bucket_name = 'my_bucket'
       c.access_key_id = 'salfjasd34u23'
       c.secret_access_key = '8u2u3rhkhfo23...'
+      c.region = 'eu-west-1'                        # defaults to 'us-east-1'
+      c.storage_headers = {'some' => 'thing'}       # defaults to {'x-amz-acl' => 'public-read'}
     end
 
 You can also pass these options to `S3DataStore.new` as an options hash.
 
+You can serve directly from the S3DataStore using e.g.
+
+    my_model.remote_url
+
+or with an expiring url:
+
+    my_model.remote_url(:expires => 3.days.from_now)
+
+Extra options you can use on store are `:path` and `:headers`
+
+    app.store("SOME CONTENT", :path => 'some/path.txt', :headers => {'x-amz-acl' => 'public-read-write'})
+
+To do this on a per-model basis see {file:Models#Storage_options}.
+
+**BEWARE!!!!** you must make sure the path (which will become the uid for the content) is unique and changes each time the content
+is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
 
 Mongo datastore
 ---------------
@@ -83,7 +126,32 @@ It won't normally need configuring, but if you wish to:
       c.password = 'some_password'                    # only needed if mongo is running in auth mode
     end
 
-You can also pass these options to `MongoDataStore.new` as an options hash.
+If you already have a mongo database or connection available, you can skip setting these and set `db` or `connection` instead.
+
+You can also pass any options to `MongoDataStore.new` as an options hash.
+
+You can't serve directly from the mongo datastore.
+
+Couch datastore
+---------------
+To configure with the {Dragonfly::DataStorage::CouchDataStore CouchDataStore}:
+
+    app.datastore = Dragonfly::DataStorage::CouchDataStore.new
+
+To configure:
+
+    app.datastore.configure do |d|
+      c.host = 'localhost'                            # defaults to localhost
+      c.port = '5984'                                 # defaults to couchdb default (5984)
+      c.database = 'dragonfly'                        # defaults to 'dragonfly'
+      c.username = ''                                 # not needed if couchdb is in 'admin party' mode
+      c.password = ''                                 # not needed if couchdb is in 'admin party' mode
+    end
+
+You can also pass these options to `CouchDataStore.new` as an options hash.
+
+You can serve directly from the couch datastore. You can optionally pass in a `:mime_type` option to `store`
+to tell it what to use for its 'Content-Type' header.
 
 Custom datastore
 ----------------
@@ -93,7 +161,6 @@ Data stores are key-value in nature, and need to implement 3 methods: `store`, `
 
       def store(temp_object, opts={})
         # ... use temp_object.data, temp_object.file, temp_object.path, etc. ...
-        # ... can also make use of temp_object.name, temp_object.format, temp_object.meta
         # store and return the uid
         'return_some_unique_uid'
       end
@@ -101,9 +168,9 @@ Data stores are key-value in nature, and need to implement 3 methods: `store`, `
       def retrieve(uid)
         # return an array containing
         [
-          content,            # either a File, String or Tempfile
-          extra_data          # Hash with optional keys :meta, :name, :format
-        ]
+          content,          # either a File, String or Tempfile
+          meta_data         # Hash - :name and :format are treated specially,
+        ]                   #  e.g. job.name is taken from job.meta[:name]
       end
 
       def destroy(uid)
@@ -117,20 +184,23 @@ You can now configure the app to use your datastore:
     Dragonfly[:my_app_name].datastore = MyDataStore.new
 
 Notice that `store` takes a second `opts` argument.
-Any options other than `meta`, `name` and `format` get passed through to here, so calling
+Any options, including `:meta`, get passed here
 
     uid = app.store('SOME CONTENT',
-      :name => 'great_content.txt',
+      :meta => {:name => 'great_content.txt'},
       :some_other => :option
     )
 
-will be split inside `store` like so:
+    # ...
+
+You can also optionally serve data directly from the datastore if it implements `url_for`:
+
+    class MyDataStore
 
-    def store(temp_object, opts={})
-      temp_object.data             # "SOME CONTENT"
-      temp_object.name             # 'great_content.txt'
-      opts                         # {:some_other => :option}
       # ...
-    end
 
-    # ...
+      def url_for(uid, opts={})
+        "http://some.domain/#{uid}"
+      end
+
+    end

data/extra_docs/Encoding.md

@@ -1,8 +1,6 @@
 Encoding
 ========
-
-Changing the format of data, but not changing the data itself,
-e.g. converting to gif format, comes under the banner of Encoding.
+Registered encoders change the format of data, e.g. a jpeg image to a png image.
 
 You can register as many encoders as you like.
 
@@ -20,37 +18,6 @@ and an image object (actually a {Dragonfly::Job Job} object)...
 
 We can encode it to any format registered with the encoder.
 
-ImageMagickEncoder
-------------------
-The {Dragonfly::Encoding::ImageMagickEncoder ImageMagickEncoder} is registered by default by
-the {Dragonfly::Config::ImageMagick ImageMagick configuration} used by 'dragonfly/rails/images'.
-
-If not already registered:
-
-    app.encoder.register(Dragonfly::Encoding::ImageMagickEncoder)
-
-gives us:
-
-    image.encode(:jpg)
-    image.encode(:gif)
-    image.encode(:png)
-    image.encode(:tiff)
-
-and various other formats (see {Dragonfly::Encoding::ImageMagickEncoder ImageMagickEncoder}).
-
-You can also pass additional options to the imagemagick command line:
-
-    image.encode(:jpg, '-quality 10')
-
-RMagickEncoder
---------------
-The {Dragonfly::Encoding::RMagickEncoder RMagickEncoder} uses the {http://rmagick.rubyforge.org RMagick} library to do similar things to the
-ImageMagickEncoder above.
-
-You can tell it not to use the file system when registering it using
-
-    app.encoder.register(Dragonfly::Encoding::RMagickEncoder){|e| e.use_filesystem = false }
-
 Lazy evaluation
 ---------------
 
@@ -65,6 +32,10 @@ Bang method
 
 modifies the image object itself, rather than returning a new object.
 
+ImageMagick Encoder
+-------------------
+See {file:ImageMagick}.
+
 Custom Encoders
 ---------------
 
@@ -74,7 +45,7 @@ To register a custom encoder, for e.g. pdf format:
       throw :unable_to_handle unless format == :pdf
       # use temp_object.data, temp_object.path, temp_object.file, etc.
       SomeLibrary.convert_to_pdf(temp_object.data)
-      # return a String, File or Tempfile
+      # return a String, Pathname, File or Tempfile
     end
 
     pdf_image = image.encode(:pdf)