dragonfly 0.1.6 → 0.2.1

data/extra_docs/Analysers.md

@@ -0,0 +1,63 @@
+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'
+
+    app = Dragonfly::App[:images]
+
+Data gets passed around between the datastore, processor, analyser, etc. in the form of an {Dragonfly::ExtendedTempObject ExtendedTempObject}.
+
+    temp_object = app.create_object(File.new('path/to/image.png'))
+
+This object will have any methods which have been registered with the analyser. For example, registering
+the {Dragonfly::Analysis::RMagickAnalyser rmagick analyser}
+
+    app.register_analyser(Dragonfly::Analysis::RMagickAnalyser)
+
+give us the methods `width`, `height`, `depth` and `number_of_colours` (or `number_of_colors`).
+
+    temp_object.width        # => 280
+    # ...etc.
+
+Registering the {Dragonfly::Analysis::FileCommandAnalyser 'file' command analyser}
+
+    app.register_analyser(Dragonfly::Analysis::FileCommandAnalyser)
+
+gives us the method `mime_type`, which is necessary for the app to serve the file properly.
+
+    temp_object.mime_type    # => 'image/png'
+
+As the file command analyser is {Dragonfly::Configurable configurable}, we can configure it as we register it if we need to
+
+    app.register_analyser(Dragonfly::Analysis::FileCommandAnalyser) do |a|
+      a.file_command = '/usr/bin/file'
+    end
+
+The saved configuration {Dragonfly::RMagickConfiguration RMagickConfiguration} registers the above two analysers automatically.
+
+Custom Analysers
+----------------
+
+To register a custom analyser, derive from {Dragonfly::Analysis::Base Analysis::Base} and register.
+Each method takes the temp_object as its argument.
+
+    class MyAnalyser < Dragonfly::Analysis::Base
+    
+      def coolness(temp_object)
+        # use temp_object.data, temp_object.path, etc...
+        temp_object.size / 30
+      end
+
+      # ... add as many methods as you wish
+
+    end
+
+    app.register_analyser(MyAnalyser)
+    
+    temp_object = app.create_object(File.new('path/to/image.png'))
+    
+    temp_object.coolness     # => 2067
+
+You can register multiple analysers.

data/extra_docs/DataStorage.md

@@ -0,0 +1,33 @@
+Data Storage
+============
+
+Each dragonfly app has a datastore.
+
+    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`.
+
+    class MyDataStore < Dragonfly::DataStorage::Base
+
+      def store(temp_object)
+        # ... use temp_object.data, temp_object.file, or temp_object.path and store
+        '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
+      end
+  
+      def destroy(uid)
+        # find the content and destroy
+      end
+
+    end
+
+You can now configure the app to use this datastore like so
+
+    Dragonfly::App[:my_app_name].datastore = MyDataStore.new
+
+If you want your datastore to be configurable, you can include the {Dragonfly::Configurable Configurable} module.

data/extra_docs/Encoding.md

@@ -0,0 +1,58 @@
+Encoding
+========
+
+'Encoding' encapsulates the idea of a format (e.g. 'png', 'jpeg', 'doc', 'txt', etc.), and any encoding options
+(e.g. bit_rate, etc.).
+
+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).
+
+The encoder needs to implement a single method, `encode`, which takes a {Dragonfly::ExtendedTempObject temp_object}, a format, and encoding options as arguments.
+
+    def encode(temp_object, format, encoding={})
+      #... encode and return a String, File, Tempfile or TempObject
+    end
+
+Let's say we register the {Dragonfly::Encoding::RMagickEncoder rmagick encoder} to our dragonfly app called 'images'
+
+    app = Dragonfly::App[:images]
+    app.register_encoder(Dragonfly::Encoding::RMagickEncoder)
+
+Then we can encode {Dragonfly::ExtendedTempObject temp_objects} to formats recognised by the RMagickEncoder
+
+    temp_object = app.create_object(File.new('path/to/image.png'))
+
+    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'
+
+    temp_object.encode(:doc)    # => throws :unable_to_handle
+
+The saved configuration {Dragonfly::RMagickConfiguration RMagickConfiguration} registers the above encoder automatically.
+
+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
+    
+    end
+    
+    app.register_encoder(MyEncoder)
+
+If the encoder is {Dragonfly::Configurable configurable}, we can configure it as we register it if we need to
+
+    app.register_encoder(MyEncoder) do |e|
+      e.some_attribute = 'hello'
+    end

data/extra_docs/GettingStarted.md

@@ -0,0 +1,114 @@
+Getting Started
+===============
+
+Below is a general guide for setting up and using Dragonfly.
+
+For setting up with Ruby on Rails, see {file:UsingWithRails UsingWithRails}.
+
+For more info about using Rack applications, see the docs at {http://rack.rubyforge.org/}
+
+Running as a Standalone Rack Application
+----------------------------------------
+
+Basic usage of a dragonfly app involves storing data (e.g. images),
+then serving that data, either in its original form, processed, encoded or both.
+
+A basic rackup file `config.ru`:
+
+    require 'rubygems'
+    require 'dragonfly'
+
+    Dragonfly::App[:my_app_name].configure do |c|
+      # ...
+      c.some_attribute = 'blah'
+      # ...
+    end
+
+    run Dragonfly:App[:my_app_name]
+
+As you can see, this involves instantiating an app, configuring it (how data is stored,
+processing, encoding, etc.), then running it.
+
+You can have multiple dragonfly apps, each with their own configuration.
+Each app has a name, and is referred to by that name.
+
+    Dragonfly::App[:images]    # ===> Creates an app called 'images'
+    Dragonfly::App[:images]    # ===> Refers to the already created app 'images'
+
+Example: Using to serve resized images
+--------------------------------------
+
+`config.ru`:
+
+    require 'rubygems'
+    require 'dragonfly'
+    require 'rack/cache'
+
+    app = Dragonfly::App[:images]
+    app.configure_with(Dragonfly::RMagickConfiguration)
+
+    use Rack::Cache,
+      :verbose     => true,
+      :metastore   => 'file:/var/cache/rack/meta',
+      :entitystore => 'file:/var/cache/rack/body'
+
+    run app
+
+This configures the app to use the RMagick {Dragonfly::Processing::RMagickProcessor processor},
+{Dragonfly::Encoding::RMagickEncoder encoder} and {Dragonfly::Analysis::RMagickAnalyser analyser}.
+By default the {Dragonfly::DataStorage::FileDataStore file data store} is used.
+
+Elsewhere in our code:
+
+    app = Dragonfly::App[:images]
+    
+    # Store
+    uid = app.store(File.new('path/to/image.png'))   # ===> returns a unique uid for that image, "2009/11/29/145804_file"
+    
+    # Get the url for a thumbnail
+    url = app.url_for(uid, '30x30', :gif)            # ===> "/2009/11/29/145804_file.gif?m=resize&o[geometry]=30x30"
+
+Now when we visit the url `/2009/11/29/145804_file.gif?m=resize&o[geometry]=30x30` in the browser, we get the resized
+image!
+
+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.
+
+In the example above, we've put the middleware {http://tomayko.com/src/rack-cache/ Rack::Cache} in front of the app.
+So although the first time we access the url the content is processed, every time after that it is received from the
+cache, and is served super quick!
+
+Avoiding Denial-of-service attacks
+----------------------------------
+The url given above, `/2009/11/29/145804_file.gif?m=resize&o[geometry]=30x30`, could easily be modified to
+generate all different sizes of thumbnails, just by changing the size, e.g.
+
+`/2009/11/29/145804_file.gif?m=resize&o[geometry]=30x31`,
+
+`/2009/11/29/145804_file.gif?m=resize&o[geometry]=30x32`,
+
+etc.
+
+Therefore the app can protect the url by generating a unique sha from a secret specified by you
+
+    Dragonfly::App[:images].url_handler.configure do |c|
+      c.protect_from_dos_attacks = true                           # Actually this is true by default
+      c.secret = 'You should supply some random secret here'
+    end
+
+Then the required urls become something more like
+
+`/2009/12/10/215214_file.gif?m=resize&o[geometry]=30x30&s=aa78e877ad3f6bc9`,
+
+with a sha parameter on the end.
+If we try to hack this url to get a different thumbnail,
+
+`/2009/12/10/215214_file.gif?m=resize&o[geometry]=30x31&s=aa78e877ad3f6bc9`,
+
+then we get a 400 (bad parameters) error.

data/extra_docs/Processing.md

@@ -0,0 +1,58 @@
+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.
+
+All processing jobs are defined by a processing method and a processing options hash (which is passed to the method).
+
+Let's say we have a dragonfly app called 'images'
+
+    app = Dragonfly::App[:images]
+
+Data gets passed around between the datastore, processor, analyser, etc. in the form of an {Dragonfly::ExtendedTempObject ExtendedTempObject}.
+
+    temp_object = app.create_object(File.new('path/to/image.png'))
+
+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}
+
+    app.register_processor(Dragonfly::Processing::RMagickProcessor)
+
+give us the processing methods `resize`, `crop`, `resize_and_crop`, `rotate`, etc.
+
+    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
+
+The saved configuration {Dragonfly::RMagickConfiguration RMagickConfiguration} registers the above processor automatically.
+
+Custom Processing
+-----------------
+
+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.
+
+    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
+
+      # ... add as many methods as you wish
+
+    end
+
+    app.register_processor(MyProcessor)
+    
+    temp_object = app.create_object(File.new('path/to/image.png'))
+    
+    temp_object.process(:black_and_white, :some => 'option')
+
+You can register multiple processors.
+
+As with analysers and encoders, if the processor is {Dragonfly::Configurable configurable}, we can configure it as we register it if we need to
+
+    app.register_processor(MyProcessor) do |p|
+      p.some_attribute = 'hello'
+    end

data/extra_docs/Shortcuts.md

@@ -0,0 +1,118 @@
+Shortcuts
+=========
+
+When you call {Dragonfly::App#fetch fetch}, {Dragonfly::ExtendedTempObject#transform transform},
+{Dragonfly::UrlHandler#url_for url_for}, (or {Dragonfly::ActiveRecordExtensions::Attachment#url url} on an ActiveRecord attachment), you can specify all the job parameters
+necessary to fetch the appropriate content.
+
+The parameters are the following:
+
+  - `:uid` - the uid used by the datastore to retrieve the data (was returned when stored)
+  - `:processing_method` - the method used to do the processing
+  - `:processing_options` - options hash passed to the processing method
+  - `:format` - the format to encode the data with, e.g. 'png'
+  - `:encoding` - an options hash passed to the encoder for other options, e.g. bitrate, etc.
+
+Say we have an app configured with the {Dragonfly::RMagickConfiguration RMagickConfiguration}
+
+    app = Dragonfly::App[:my_app]
+    app.configure_with(Dragonfly::RMagickConfiguration)
+
+we can call things like
+
+    app.fetch 'some_uid',
+      :processing_method => :resize_and_crop,
+      :processing_options => {:width => 100, :height => 50, :gravity => 'ne'},
+      :format => :jpg,
+      :encoding => {:some => 'option'}           # => gets a processed and encoded temp_object
+    
+    app.url_for 'some_uid',
+      :processing_method => :resize_and_crop,
+      :processing_options => {:width => 100, :height => 50, :gravity => 'ne'},
+      :format => :jpg,
+      :encoding => {:some => 'option'}           # => "/images/some_uid.tif?m=resize_and_crop&o[width]=...."
+
+YIKES!!!!!
+
+That's an awful lot of code every time, especially if we reuse the same parameters over and over.
+That's why for the arguments after the uid, you can register {Dragonfly::Parameters parameter shortcuts}.
+
+Simple shortcuts
+----------------
+If we were to use the parameters in the example above a number of times, we could register a simple named shortcut, say 'thumb', using a symbol.
+
+    app.parameters.add_shortcut(:thumb,
+      :processing_method => :resize_and_crop,
+      :processing_options => {:width => 100, :height => 50, :gravity => 'ne'},
+      :format => :jpg,
+      :encoding => {:some => 'option'}
+    )
+
+We can now use this named shortcut, `:thumb`, in place of the parameters elsewhere
+
+    app.fetch 'some_uid', :thumb           # => gets a processed and encoded temp_object as before    
+    app.url_for 'some_uid', :thumb         # => "/images/some_uid.tif?m=resize_and_crop&o[width]=....", as before
+    
+Complex shortcuts
+-----------------
+Rather than create a new named shortcut for every different set of parameters, we can make life easier by defining shortcuts
+which match a set of arguments, then form parameters from them.
+
+For example, take the shortcut
+
+    app.parameters.add_shortcut(/\d+x\d+/, Symbol) do |geometry, format|
+      {
+        :processing_method => :my_resize_method,
+        :processing_options => {:geometry => geometry},
+        :format => format
+      }
+    end
+
+It will match where there are two arguments, a string matching `/\d+x\d+/` and a symbol, and convert to a hash of job parameters.
+Note that the matching arguments are yielded to the block.
+So, for example,
+
+    app.url_for('some_uid', '100x50', :jpg)
+    
+generates the same url as if we'd used
+
+    app.url_for 'some_uid',
+      :processing_method => :my_resize_method,
+      :processing_options => {:geometry => 100},
+      :format => :jpg
+
+The following examples would not match
+
+    app.url_for('some_uid', '100xg50', :jpg)           # '100xg50' doesn't match /\d+x\d+/
+    app.url_for('some_uid', '100x50', 'jpg')           # 'jpg' is not a Symbol
+    app.url_for('some_uid', '100x50')                  # not enough arguments
+    app.url_for('some_uid', '100x50', :jpg, 4)         # too many arguments
+
+The arguments are matched using the `===` operator (as used in `case` statements), which is why, for example, `:jpg` matches `Symbol`.
+
+Regexp shortcuts
+----------------
+If we register a complex shortcut as a single regexp, then the match data is also yielded, for convenience.
+
+    app.parameters.add_shortcut(/(\d+)x(\d+)/) do |geometry, match_data|
+      {
+        :processing_method => :my_resize_method,
+        :processing_options => {:width => match_data[1], :height => match_data[2]}
+      }
+    end
+
+
+Default parameters
+------------------
+If we've configured a default parameter, e.g.
+
+    app.parameters.default_format = :jpg
+    
+then this will be used in these methods whenever that parameter is not given, such as in the example above.
+
+Avoiding processing/encoding
+----------------------------
+If `:processing_method` is set to nil, then no processing takes place when methods like {Dragonfly::App#fetch fetch}, {Dragonfly::ExtendedTempObject#transform transform},
+{Dragonfly::UrlHandler#url_for url_for}, and {Dragonfly::ActiveRecordExtensions::Attachment#url url} are called.
+
+Similarly, if `:format` is set to nil, then no encoding takes place.