dragonfly 0.6.2 → 0.7.0

data/extra_docs/Analysers.md

@@ -3,61 +3,97 @@ Analysers
 
 Analysing data for things like width, mime_type, etc. come under the banner of Analysis.
 
-Let's say we have a dragonfly app called 'images'
+You can register as many analysers as you like.
 
-    app = Dragonfly::App[:images]
+Let's say we have a Dragonfly app
 
-Data gets passed around between the datastore, processor, analyser, etc. in the form of an {Dragonfly::ExtendedTempObject ExtendedTempObject}.
+    app = Dragonfly[:images]
 
-    temp_object = app.create_object(File.new('path/to/image.png'))
+and an image object (actually a {Dragonfly::Job Job} object)...
 
-This object will have any methods which have been registered with the analyser. For example, registering
-the {Dragonfly::Analysis::RMagickAnalyser rmagick analyser}
+    image = app.fetch('some/uid')
 
-    app.register_analyser(Dragonfly::Analysis::RMagickAnalyser)
+...OR a Dragonfly model accessor...
 
-give us the methods `width`, `height`, `depth` and `number_of_colours` (or `number_of_colors`).
+    image = @album.cover_image
 
-    temp_object.width        # => 280
-    # ...etc.
+We can analyse it using any analysis methods that have been registered with the analyser.
 
-Registering the {Dragonfly::Analysis::FileCommandAnalyser 'file' command analyser}
+RMagickAnalyser
+---------------
+The {Dragonfly::Analysis::RMagickAnalyser RMagickAnalyser} is registered by default by the
+{Dragonfly::Config::RMagick RMagick configuration} used by 'dragonfly/rails/images'.
 
-    app.register_analyser(Dragonfly::Analysis::FileCommandAnalyser)
+If not already registered:
 
-gives us the method `mime_type`, which is necessary for the app to serve the file properly.
+    app.analyser.register(Dragonfly::Analysis::RMagickAnalyser)
 
-    temp_object.mime_type    # => 'image/png'
+gives us these methods:
 
-As the file command analyser is {Dragonfly::Configurable configurable}, we can configure it as we register it if we need to
+    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
 
-    app.register_analyser(Dragonfly::Analysis::FileCommandAnalyser) do |a|
-      a.file_command = '/usr/bin/file'
-    end
+FileCommandAnalyser
+-------------------
+The {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} is registered by default by the
+{Dragonfly::Config::Rails Rails configuration} used by 'dragonfly/rails/images'.
+
+As the name suggests, it uses the UNIX 'file' command.
+
+If not already registered:
+
+    app.analyser.register(Dragonfly::Analysis::FileCommandAnalyser)
+
+gives us:
 
-The saved configuration {Dragonfly::Config::RMagickImages RMagickImages} registers the above two analysers automatically.
+    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
+
+    app.analyser.register(Dragonfly::Analysis::FileCommandAnalyser) do |a|
+      a.use_filesystem = true
+    end
 
 Custom Analysers
 ----------------
 
-To register a custom analyser, derive from {Dragonfly::Analysis::Base Analysis::Base} and register.
+To register a single custom analyser:
+
+    app.analyser.add :wobbliness do |temp_object|
+      # can use temp_object.data, temp_object.path, temp_object.file, etc.
+      SomeLibrary.assess_wobbliness(temp_object.data)
+    end
+
+    image.wobbliness    # => 71
+
+You can create a class like the RMagick one above, in which case all public methods will be counted as analysis methods.
 Each method takes the temp_object as its argument.
 
-    class MyAnalyser < Dragonfly::Analysis::Base
-    
+    class MyAnalyser
+
       def coolness(temp_object)
-        # use temp_object.data, temp_object.path, etc...
         temp_object.size / 30
       end
 
-      # ... add as many methods as you wish
+      def uglyness(temp_object)
+        `ugly -i #{temp_object.path}`
+      end
+
+      private
+
+      def my_helper_method
+        # do stuff
+      end
 
     end
 
-    app.register_analyser(MyAnalyser)
-    
-    temp_object = app.create_object(File.new('path/to/image.png'))
-    
-    temp_object.coolness     # => 2067
+    app.analyser.register(MyAnalyser)
 
-You can register multiple analysers.
+    image.coolness    # => -4.1
+    image.uglyness    # => "VERY"

data/extra_docs/Caching.md

@@ -0,0 +1,22 @@
+Caching
+=======
+
+Processing and encoding can be an expensive operation. The first time we visit the url,
+the image is processed, and there might be a short delay and getting the response.
+
+However, dragonfly apps send `Cache-Control` and `ETag` headers in the response, so we can easily put a caching
+proxy like {http://varnish.projects.linpro.no Varnish}, {http://www.squid-cache.org Squid},
+{http://tomayko.com/src/rack-cache/ Rack::Cache}, etc. in front of the app, so that subsequent requests are served
+super-quickly straight out of the cache.
+
+The file 'dragonfly/rails/images' puts Rack::Cache in front of Dragonfly by default.
+
+Given a dragonfly app
+
+    app = Dragonfly[:images]
+
+You can configure the 'Cache-Control' header with
+
+    app.cache_duration = 3600*24*365*3  # time in seconds
+
+For a well-written discussion of Cache-Control and ETag headers, see {http://tomayko.com/writings/things-caches-do}.

data/extra_docs/Configuration.md

@@ -0,0 +1,116 @@
+Configuration
+=============
+
+Given a Dragonfly app
+
+    app = Dragonfly[:app_name]
+
+Configuration can either be done like so...
+
+    app.configure do |c|
+      c.url_path_prefix = '/media'
+      # ...
+    end
+
+...or directly like so...
+
+    app.url_path_prefix = '/media'
+
+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:
+
+    app.configure do |c|
+      c.datastore = SomeCustomDataStore.new :egg => 'head'  # defaults to FileDataStore
+
+      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.url_path_prefix = '/images'                         # defaults to nil
+      c.url_host = 'http://some.domain.com:4000'            # defaults to nil
+
+      c.protect_from_dos_attacks = true                     # defaults to false - adds a SHA parameter on the end of urls
+      c.secret = 'This is my secret yeh!!'                  # should set this if concerned about DOS attacks
+
+      c.analyser.register(MyAnalyser)                       # See 'Analysers' for more details
+      c.processor.register(MyProcessor, :type => :fig)      # See 'Processing' for more details
+      c.encoder.register(MyEncoder) do |e|                  # See 'Encoding' for more details
+        e.some_value = 'geg'
+      end
+      c.generator.register(MyGenerator)                     # See 'Generators' for more details
+
+      c.register_mime_type(:egg, 'fried/egg')               # See 'MimeTypes' for more details
+
+      c.job :black_and_white do |size|                      # Job shortcut - lets you do image.black_and_white('30x30')
+        process :greyscale
+        process :thumb, size
+        encode  :gif
+      end
+    end
+
+Where is configuration done?
+----------------------------
+In Rails, it should be done in an initializer, e.g. 'config/initializers/dragonfly.rb'.
+Otherwise it should be done anywhere where general setup is done, early on.
+
+Saved configurations
+====================
+Saved configurations are useful if you often configure the app the same way.
+There are a number that are provided with Dragonfly:
+
+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`.
+
+The file 'dragonfly/rails/images' does this for you.
+
+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
+registers the {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} for helping with mime_type validations.
+
+The file 'dragonfly/rails/images' does this for you.
+
+Heroku
+------
+
+    app.configure_with(:heroku, 's3_bucket_name')
+
+The {Dragonfly::Config::Heroku Heroku configuration} configures it to use the {Dragonfly::DataStorage::S3DataStore}, using Heroku's config attributes.
+See {file:Heroku} for more info.
+
+Custom Saved Configuration
+--------------------------
+You can create your own saved configuration with any object that responds to 'apply_configuration':
+
+    module MyConfiguration
+
+      def self.apply_configuration(app, *args)
+        app.configure do |c|
+          c.url_path_prefix = '/hello/beans'
+          c.processor.register(MyProcessor)
+          # ...
+        end
+      end
+
+    end
+
+Then to configure:
+
+    app.configure_with(MyConfiguration, :any_other => :args)     # other args get passed through to apply_configuration
+
+You can also carry on configuring by passing a block
+
+    app.configure_with(MyConfiguration) do |c|
+      c.any_extra = :config_here
+      # ...
+    end

data/extra_docs/DataStorage.md

@@ -1,33 +1,133 @@
 Data Storage
 ============
 
-Each dragonfly app has a datastore.
+Each dragonfly app has a key-value datastore to store the content.
+Lets say we have an app
 
-    Dragonfly::App[:my_app_name].datastore
-    
-By default it uses the file data store, but you can configure it to use
-a custom data store (e.g. S3, SQL, CouchDB, etc.) by registering one with the correct interface, namely
-having `store`, `retrieve` and `destroy`.
+    app = Dragonfly[:my_app_name]
 
-    class MyDataStore < Dragonfly::DataStorage::Base
+Then we can store data like so:
 
-      def store(temp_object)
-        # ... use temp_object.data, temp_object.file, or temp_object.path and store
+    uid = app.store('SOME CONTENT')       # Can pass in a String, File or Tempfile
+
+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)
+
+    uid = app.store('SOME CONTENT',
+      :meta => {:time => Time.now},
+      :name => 'great_content.txt',
+      :format => :txt
+    )
+
+We can get content with
+
+    content = app.fetch(uid)
+    content.data         # "SOME CONTENT"
+
+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
+
+We can destroy it with
+
+    app.destroy(uid)
+
+You can create your own datastore, or use one of the provided ones as outlined below.
+
+File datastore
+--------------
+The {Dragonfly::DataStorage::FileDataStore FileDataStore} stores data on the local filesystem.
+
+It is used by default.
+
+If for whatever reason you need to configure it again:
+
+    # shouldn't need this - it is the default
+    app.datastore = Dragonfly::DataStorage::FileDataStore.new
+
+    app.datastore.configure do |d|
+      d.root_path = '/my/custom/path'              # defaults to /var/tmp/dragonfly
+    end
+
+
+S3 datastore
+------------
+To configure with the {Dragonfly::DataStorage::S3DataStore S3DataStore}:
+
+    app.datastore = Dragonfly::DataStorage::S3DataStore.new
+
+    app.datastore.configure do |d|
+      c.bucket_name = 'my_bucket'
+      c.access_key_id = 'salfjasd34u23'
+      c.secret_access_key = '8u2u3rhkhfo23...'
+    end
+
+You can also pass these options to `S3DataStore.new` as an options hash.
+
+
+Mongo datastore
+---------------
+To configure with the {Dragonfly::DataStorage::MongoDataStore MongoDataStore}:
+
+    app.datastore = Dragonfly::DataStorage::MongoDataStore.new
+
+It won't normally need configuring, but if you wish to:
+
+    app.datastore.configure do |d|
+      c.host = 'http://egg.heads:5000'                # defaults to localhost
+      c.port = '27018'                                # defaults to mongo default (27017)
+      c.database = 'my_database'                      # defaults to 'dragonfly'
+    end
+
+You can also pass these options to `MongoDataStore.new` as an options hash.
+
+Custom datastore
+----------------
+Data stores are key-value in nature, and need to implement 3 methods: `store`, `retrieve` and `destroy`.
+
+    class MyDataStore
+
+      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
 
       def retrieve(uid)
-        # find the content and return either a data string, a file, a tempfile or a Dragonfly::TempObject
+        # return an array containing
+        [
+          content,            # either a File, String or Tempfile
+          extra_data          # Hash with optional keys :meta, :name, :format
+        ]
       end
-  
+
       def destroy(uid)
         # find the content and destroy
       end
 
     end
 
-You can now configure the app to use this datastore like so
+You can now configure the app to use your datastore:
+
+    Dragonfly[:my_app_name].datastore = MyDataStore.new
 
-    Dragonfly::App[: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
+
+    uid = app.store('SOME CONTENT',
+      :name => 'great_content.txt',
+      :some_other => :option
+    )
+
+will be split inside `store` like so:
+
+    def store(temp_object, opts={})
+      temp_object.data             # "SOME CONTENT"
+      temp_object.name             # 'great_content.txt'
+      opts                         # {:some_other => :option}
+      # ...
+    end
 
-If you want your datastore to be configurable, you can include the {Dragonfly::Configurable Configurable} module.
+    # ...

data/extra_docs/Encoding.md

@@ -1,58 +1,83 @@
 Encoding
 ========
 
-'Encoding' encapsulates the idea of a format (e.g. 'png', 'jpeg', 'doc', 'txt', etc.), and any encoding options
-(e.g. bit_rate, etc.).
+Changing the format of data, but not changing the data itself,
+e.g. converting to gif format, comes under the banner of Encoding.
 
-It is up to the encoder to modify the data according to the requested format (note the format is not the same as the mime-type;
-the mime-type is detected by the analyser).
+You can register as many encoders as you like.
 
-The encoder needs to implement a single method, `encode`, which takes a {Dragonfly::ExtendedTempObject temp_object}, a format, and encoding options as arguments.
+Let's say we have a Dragonfly app
 
-    def encode(temp_object, format, encoding={})
-      #... encode and return a String, File, Tempfile or TempObject
-    end
+    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 encode it to any format registered with the encoder.
 
-Let's say we register the {Dragonfly::Encoding::RMagickEncoder rmagick encoder} to our dragonfly app called 'images'
+RMagickEncoder
+----------------
+The {Dragonfly::Encoding::RMagickEncoder RMagickEncoder} is registered by default by
+the {Dragonfly::Config::RMagick RMagick configuration} used by 'dragonfly/rails/images'.
 
-    app = Dragonfly::App[:images]
-    app.register_encoder(Dragonfly::Encoding::RMagickEncoder)
+If not already registered:
 
-Then we can encode {Dragonfly::ExtendedTempObject temp_objects} to formats recognised by the RMagickEncoder
+    app.encoder.register(Dragonfly::Encoding::RMagickEncoder)
+
+gives us:
+
+    image.encode(:jpg)
+    image.encode(:gif)
+    image.encode(:png)
+    image.encode(:tiff)
+
+and various other formats (see {Dragonfly::Encoding::RMagickEncoder RMagickEncoder})
+
+Lazy evaluation
+---------------
 
-    temp_object = app.create_object(File.new('path/to/image.png'))
+    gif_image = image.encode(:gif)
 
-    temp_object.encode(:png)    # => returns a new temp_object with data encoded as 'png'
-    temp_object.encode!(:gif)   # => encodes its own data as a 'png'
+doesn't actually do anything until you call something on the returned {Dragonfly::Job Job} object, like `url`, `data`, etc.
 
-    temp_object.encode(:doc)    # => throws :unable_to_handle
+Bang method
+-----------
 
-The saved configuration {Dragonfly::Config::RMagickImages RMagickImages} registers the above encoder automatically.
+    image.encode!(:gif)
+
+modifies the image object itself, rather than returning a new object.
 
 Custom Encoders
 ---------------
 
-To register a custom encoder, derive from {Dragonfly::Encoding::Base Encoding::Base} and register.
-As described above, you need to implement the `encode` method.
-If the encoder can't handle a format, it should throw `:unable_to_handle`, and control will pass to the previously
-registered encoder, and so on.
-
-    class MyEncoder < Dragonfly::Encoding::Base
-    
-      def encode(temp_object, format, encoding={})
-        if format.to_s == 'yo'
-          #... encode and return a String, File, Tempfile or TempObject
-        else
-          throw :unable_to_handle
-        end
-      end
-    
+To register a custom encoder, for e.g. pdf format:
+
+    app.encoder.add do |temp_object, 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
     end
-    
-    app.register_encoder(MyEncoder)
 
-If the encoder is {Dragonfly::Configurable configurable}, we can configure it as we register it if we need to
+    pdf_image = image.encode(:pdf)
+
+If `:unable_to_handle` is thrown, the next most recently registered encoder is used, and so on.
+
+Alternatively you can create a class like the RMagick one above, which implements the method `encode`, and register this.
+
+    class MyEncoder
+
+      def encode(temp_object, format, *args)
+        SomeLib.encode(temp_object.data, format, *args)
+      end
 
-    app.register_encoder(MyEncoder) do |e|
-      e.some_attribute = 'hello'
     end
+
+    app.encoder.register(MyEncoder)
+
+    pdf_image = image.encode(:pdf, :some => :args)