dragonfly 0.6.2 → 0.7.0

data/extra_docs/GeneralUsage.md

@@ -0,0 +1,118 @@
+General Usage
+=============
+
+You can have multiple dragonfly apps, each with their own configuration.
+Each app has a name, and is referred to by that name.
+
+    Dragonfly[:images]    # ===> Creates an app called 'images'
+    Dragonfly[:images]    # ===> Refers to the already created app 'images'
+
+    app = Dragonfly[:images]
+
+Getting/generating content
+--------------------------
+Three methods can be used to get content:
+
+    app.fetch('some_uid')                   # Fetch from datastore (default filesystem)
+
+    app.fetch_file('~/path/to/file.png')    # Fetch from a local file
+
+    app.generate(:plasma, 400, 300)         # Generates using a method from the configured
+                                            # generator (in this case a plasma image)
+
+These all return {Dragonfly::Job Job} objects. These objects are lazy - they don't do any fetching/generating until
+some other method is called on them.
+
+Using the content
+-----------------
+Once we have a {Dragonfly::Job Job} object:
+
+    image = app.fetch('some_uid')
+
+We can get the data a number of ways...
+
+    image.data                           # => "\377???JFIF\000\..."
+    image.to_file('out.png')             # writes to file 'out.png' and returns a readable file object
+    image.tempfile                       # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a closed Tempfile object
+    image.file                           # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a readable (open) File object
+    image.file do |f|                    # Yields an open file object, returns the return value of
+      data = f.read(256)                 #  the block, and closes the file object
+    end
+    image.path                           # => '/var/folders/st/strHv74sH044JPabSiODz...' i.e. the path of the tempfile
+    image.size                           # => 134507 (size in bytes)
+
+We can get its url...
+
+    image.url                            # => "/media/BAhbBlsHOgZmIg9hc..."
+
+We can analyse it (see {file:Analysers} for more info) ...
+
+    image.width                          # => 280
+
+We can process it (see {file:Processing} for more info) ...
+
+    new_image = image.process(:thumb, '40x30')    # returns another 'Job' object
+
+We can encode it (see {file:Encoding} for more info) ...
+
+    new_image = image.encode(:gif)                # returns another 'Job' object
+
+Chaining
+--------
+Because the methods
+
+  - `fetch`
+
+  - `fetch_file`
+
+  - `generate`
+
+  - `process`
+
+  - `encode`
+
+all return {Dragonfly::Job Job} objects, we can chain them as much as we want...
+
+    image = app.fetch('some_uid').process(:greyscale).process(:thumb, '40x20#').encode(:gif)
+
+... and because they're lazy, we don't actually do any processing/encoding until either `apply` is called
+
+    image.apply              # actually 'does' the processing and returns self
+
+... or a method is called like `data`, `to_file`, etc.
+
+This means we can cheaply generate urls for processed data without doing any fetching or processing:
+
+    url = app.fetch('some_uid').process(:thumb, '40x20#').encode(:gif).url
+
+and then visit that url in a browser to get the actual processed image.
+
+Shortcuts
+---------
+Commonly used processing/encoding steps can be shortened, so instead of
+
+    app.fetch('some_uid').process(:greyscale).process(:thumb, '40x20#').encode(:jpg)
+
+we could use something like
+
+    app.fetch('some_uid').grey('40x20#')
+
+This does exactly the same, returning a {Dragonfly::Job Job} object.
+
+To define this shortcut:
+
+    app.configure do |c|
+      c.job :grey do |size|
+        process :greyscale
+        process :thumb, size
+        encode :jpg
+      end
+      # ...
+    end
+
+The {Dragonfly::Config::RMagick RMagick} configuration comes with the pre-defined shortcuts:
+
+    image.thumb('40x30')   # same as image.process(:thumb, '40x30')
+    image.jpg              # same as image.encode(:jpg)
+    image.png              # same as image.encode(:png)
+    image.gif              # same as image.encode(:gif)

data/extra_docs/Generators.md

@@ -0,0 +1,92 @@
+Generators
+==========
+
+Unlike processors and encoders, generators create content out of nothing, rather than modifying already existing content, for example text image generation.
+
+You can register as many generators as you like.
+
+Given a Dragonfly app
+
+    app = Dragonfly[:images]
+
+we can get generated content using
+
+    image = app.generate(:some_method, :some => :args)
+
+where `:some_method` is added by the configured generators.
+
+RMagickGenerator
+----------------
+The {Dragonfly::Generation::RMagickGenerator RMagickGenerator} is registered by default by the
+{Dragonfly::Config::RMagick RMagick configuration} used by 'dragonfly/rails/images'.
+
+If not already registered:
+
+    app.generator.register(Dragonfly::Generation::RMagickGenerator)
+
+gives us these methods:
+
+    image = app.generate(:plasma, 600, 400, :gif)       # generate a 600x400 plasma image
+                                                        # last arg defaults to :png
+
+    image = app.generate(:text, "Hello there")          # an image of the text "Hello there"
+
+    image = app.generate(:text, "Hello there",
+      :font_size => 30,                                 # defaults to 12
+      :font_family => 'Monaco',
+      :stroke_color => '#ddd',
+      :color => 'red',
+      :font_style => 'italic',
+      :font_stretch => 'expanded',
+      :font_weight => 'bold',
+      :padding => '30 20 10',
+      :background_color => '#efefef',                   # defaults to transparent
+      :format => :gif                                   # defaults to png
+    )
+
+Note that the options are meant to resemble css as much as possible. You can also use, for example, `'font-family'` instead of `:font_family`.
+
+You can use `padding-top`, `padding-left`, etc., as well as the standard css shortcuts for `padding` (it assumes unit is px).
+
+An alternative for `:font_family` is `:font` (see {http://www.imagemagick.org/RMagick/doc/draw.html#font}), which could be a complete filename.
+Available fonts are those available on your system.
+
+Custom Generators
+-----------------
+To register a single custom generator:
+
+    app.generator.add :blank_image do |colour|
+      SomeLibrary.create_blank_image(colour)     # return a String, File or Tempfile
+    end
+
+    app.generate(:blank_image, 'red')      # => 'Job' object which we can get data, etc.
+
+
+Or create a class like the RMagick one above, in which case all public methods will be counted as generator methods.
+
+    class RoundedCornerGenerator
+
+      def top_left_corner(opts={})
+        SomeLib.tlc(opts)
+      end
+
+      def bottom_right_corner(opts={})
+        tempfile = Tempfile.new('brc')
+        `some_command -c #{opts[:colour]} -o #{tempfile.path}`
+        tempfile
+      end
+
+      # ...
+
+      private
+
+      def my_helper_method
+        # do stuff
+      end
+
+    end
+
+    app.generator.register(RoundedCornerGenerator)
+
+    app.generate(:top_left_corner, :colour => 'green')
+    app.generate(:bottom_right_corner, :colour => 'mauve')

data/extra_docs/Heroku.md

@@ -0,0 +1,51 @@
+Heroku
+======
+
+The default configuration won't work out of the box for Heroku, because
+
+- Heroku doesn't allow saving files to the filesystem (although it does use tempfiles)
+- We won't need {http://tomayko.com/src/rack-cache/ Rack::Cache} on Heroku because it already uses the caching proxy {http://varnish.projects.linpro.no/ Varnish}, which we can make use of
+
+Instead of the normal {Dragonfly::DataStorage::FileDataStore FileDataStore}, we can use the {Dragonfly::DataStorage::S3DataStore S3DataStore}.
+
+Assuming you have an S3 account set up...
+
+Gem dependencies:
+
+    - rmagick (require as 'RMagick')
+    - aws-s3 (require as aws/s3)
+    - dragonfly
+
+Initializer (e.g. config/initializers/dragonfly.rb):
+
+    require 'dragonfly'
+    app = Dragonfly[:images]
+
+    app.configure_with(:rmagick)
+    app.configure_with(:rails)
+    app.configure_with(:heroku, 'my_bucket_name') if Rails.env.production?
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+The datastore remains as the {Dragonfly::DataStorage::FileDataStore FileDataStore} for non-production environments.
+
+environment.rb (application.rb in Rails 3):
+
+    config.middleware.insert 0, 'Dragonfly::Middleware', :images, '/media'  # make sure this is the same
+                                                                            # as the app's configured prefix
+
+We don't store the S3 access key and secret in the repository, rather we use Heroku's
+{http://docs.heroku.com/config-vars config variables} using the command line (we only have to do this once).
+
+From your app's directory:
+
+    heroku config:add S3_KEY=XXXXXXXXX S3_SECRET=XXXXXXXXXX
+
+Obviously replace 'XXXXXXXXX' with your access key and secret.
+
+Now you can benefit from super-fast images served straight from Heroku's cache!
+
+NOTE: HEROKU'S CACHE IS CLEARED EVERY TIME YOU DEPLOY!!!
+
+If this is an issue, you may want to look into using something like a Memcached add-on, or maybe an after-deploy hook for hitting specific Dragonfly urls you want to cache, etc.
+It won't be a problem for most sites though.

data/extra_docs/Index.md

@@ -1,19 +1,17 @@
 Dragonfly Documentation
 =======================
+Dragonfly is a {http://rack.rubyforge.org Rack} framework for on-the-fly image handling in Ruby.
 
-Welcome to the documentation for Dragonfly!
+It is suitable for using with web frameworks such as Rails(2.3 and 3), Sinatra, etc.
 
-Dragonfly is a {http://rack.rubyforge.org Rack} framework for on-the-fly processing and encoding.
+I actually lied about image handling - it can be used for any type of content.
 
-It includes an extension for Ruby on Rails to enable easy image handling.
-It is intended to be highly customizable, and is not limited to images, but any data type that could suit on-the-fly processing/encoding.
-
-Use the dropdowns at the top-right to navigate around the code, or jump straight to one of the guides on the right.
+See the links on the right for more info.
 
 Installation
 ------------
 
-    gem install dragonfly --source=http://gemcutter.org
+    gem install dragonfly
 
 Issues
 ------
@@ -25,8 +23,9 @@ Suggestions/Questions
 
 Credits
 -------
-- <a href="http://github.com/markevans">Mark Evans</a> (author)
+- [Mark Evans](http://github.com/markevans) (author)
+- Loads of helpful comments, issues, questions, suggestions and insults from others - you know who you are!
 
 Copyright
 ---------
-Copyright (c) 2009 Mark Evans. See LICENSE for details.
+Copyright (c) 2009-2010 Mark Evans. See LICENSE for details.

data/extra_docs/MimeTypes.md

@@ -3,37 +3,38 @@ Mime Types
 
 Responses from the Dragonfly app have the HTTP 'Content-Type' header set.
 
-Suppose we request the url '/media/some_uid.jpg'.
-The mime-type is looked for in the following order (and the first found is used):
+This is decided by the first found from:
 
-1. The app's registered mime-types
-2. Analyse the content using the analyser's 'mime_type' method (if exists)
-3. Use the fallback mime-type (default 'application/octet-stream')
+1. The requested format (e.g. when encode is specifically called)
+2. The original file extension (you can configure it to ignore this if you wish)
+3. Analyse the content using the analyser's 'mime_type' method (if exists)
+4. Analyse the content using the analyser's 'format' method (if exists)
+5. Use the fallback mime-type (default 'application/octet-stream')
+
+Note that 'format' means 'jpg', 'png', etc. whereas mime-type would be 'image/jpeg', image/png', etc.
+Formats are mapped to mime-types using the app's registered list of mime-types.
 
 Registered mime-types
 ---------------------
 Registered mime-types default to the list given by Rack (see {http://rack.rubyforge.org/doc/Rack/Mime.html#MIME_TYPES Rack mime-types}).
 
-To register a mime-type for the format 'egg', you can do the following:
+To register a mime-type for the format 'egg':
 
-    Dragonfly::App[:my_app].register_mime_type(:egg, 'fried/egg')
+    Dragonfly[:my_app].register_mime_type(:egg, 'fried/egg')
 
 You can also do this inside a configuration block.
 
-Mime-type analysis
-------------------
-The {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} has a `mime_type` method which will return the
-mime-type of any given content.
-
-If this, or any other analyser that has the `mime_type` method, is registered, then this is used when no mime-type
-is found in the registered list.
+Analysers
+---------
+The {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} has a `mime_type` method and the
+{Dragonfly::Analysis::RMagickAnalyser RMagickAnalyser} has a `format` method.
 
-The FileCommandAnalyser is registered by default when you use the preconfigured 'dragonfly/rails/images' file.
+These are both registered by default when you use the preconfigured 'dragonfly/rails/images' file.
 
 Fallback mime-type
 ------------------
-By default this is 'application/octet-stream', but it can be changed using the configuration method on the app
+By default this is 'application/octet-stream', but it can be changed using
 
-    Dragonfly::App[:my_app].fallback_mime_type = 'meaty/beef'
+    Dragonfly[:my_app].fallback_mime_type = 'meaty/beef'
 
 This can also be done inside a configuration block.

data/extra_docs/Models.md

@@ -0,0 +1,251 @@
+Using with Models
+=================
+
+You can extend ActiveModel-compatible models to make working with content such as images
+as easy as working with strings or numbers!
+
+The examples below assume an initialized Dragonfly app, e.g.
+
+    app = Dragonfly[:images]
+
+ActiveRecord
+------------
+If you've required 'dragonfly/rails/images', then the following step will be already done for you.
+Otherwise:
+
+    app.define_macro(ActiveRecord::Base, :image_accessor)
+
+defines the macro `image_accessor` on any ActiveRecord models.
+
+Mongoid
+-------
+
+    app.define_macro_on_include(Mongoid::Document, :image_accessor)
+
+defines the macro `image_accessor` on any models that include `Mongoid::Document`
+
+Adding accessors
+----------------
+Now we have the method `image_accessor` available in our model classes, which we can use as many times as we like
+
+    class Album
+      image_accessor :cover_image
+      image_accessor :band_photo  # Note: this is a different image altogether, not a thumbnail of cover_image
+    end
+
+Each accessor (e.g. `cover_image`) depends on a string field to actually hold the datastore uid,
+named by appending the suffix `_uid` (e.g. `cover_image_uid`).
+
+For example, ActiveRecord models need a migration such as:
+
+    class MyMigration < ActiveRecord::Migration
+
+      def self.up
+        add_column :albums, :cover_image_uid, :string
+        add_column :albums, :band_photo_uid, :string
+      end
+
+      def self.down
+        remove_column :albums, :cover_image_uid
+        remove_column :albums, :band_photo_uid
+      end
+
+    end
+
+Using the accessors
+-------------------
+
+We can use the attribute much like other other model attributes:
+
+    @album = Album.new
+
+    @album.cover_image = "\377???JFIF\000\..."             # can assign as a string...
+    @album.cover_image = File.new('path/to/my_image.png')  # ... or as a file...
+    @album.cover_image = some_tempfile                     # ... or as a tempfile...
+    @album.cover_image = @album.band_photo                 # ... or as another Dragonfly attachment
+
+    @album.cover_image          # => #<Dragonfly::ActiveModelExtensions::Attachment:0x103ef6128...
+
+    @album.cover_image = nil
+    @album.cover_image          # => nil
+
+We can inspect properties of the attribute
+
+    @album.cover_image.width                          # => 280
+    @album.cover_image.height                         # => 140
+    @album.cover_image.number_of_colours              # => 34703
+    @album.cover_image.mime_type                      # => 'image/png'
+
+The properties available (i.e. 'width', etc.) come from the app's registered analysers - see {file:Analysers.md Analysers}.
+
+We can play around with the data
+
+    @album.cover_image.data                           # => "\377???JFIF\000\..."
+    @album.cover_image.to_file('out.png')             # writes to file 'out.png' and returns a readable file object
+    @album.cover_image.tempfile                       # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a closed Tempfile object
+    @album.cover_image.file                           # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a readable (open) File object
+    @album.cover_image.file do |f|                    # Yields an open file object, returns the return value of
+      data = f.read(256)                              #  the block, and closes the file object
+    end
+    @album.cover_image.path                           # => '/var/folders/st/strHv74sH044JPabSiODz...' i.e. the path of the tempfile
+    @album.cover_image.size                           # => 134507 (size in bytes)
+
+We can process the data
+
+    image = @album.cover_image.process(:thumb, '20x20')   # returns a 'Job' object, with similar properties
+    image.width                                          # => 20
+    @album.cover_image.width                              # => 280 (no change)
+
+The available processing methods available (i.e. 'thumb', etc.) come from the {Dragonfly} app's registered processors - see {file:Processing.md Processing}
+
+We can encode the data
+
+    image = @album.cover_image.encode(:gif)   # returns a 'Job' object, with similar properties
+    image.format                              # => :gif
+    @album.cover_image.format                 # => :png (no change)
+
+The encoding is implemented by the {Dragonfly} app's registered encoders (which will usually just be one) - see {file:Encoding.md Encoding}
+
+We can use configured shortcuts for processing/encoding, and chain them:
+
+    @album.cover_image.thumb('300x200#ne')     # => returns a 'Job' object, with similar properties
+
+We can chain all these things much like ActiveRecord scopes:
+
+    @album.cover_image.png.thumb('300x200#ne').process(:greyscale).encode(:tiff)
+
+Because the processing/encoding methods are lazy, no actual processing or encoding is done until a method like `data`, `file`, `to_file`, `width`, etc. is called.
+You can force the processing to be done if you must by then calling `apply`.
+
+    @album.cover_image.process(:greyscale).apply
+
+Persisting
+----------
+When the model is saved, a before_save callback persists the data to the {Dragonfly::App App}'s configured datastore (see {file:DataStorage.md DataStorage})
+The uid column is then filled in.
+
+    @album = Album.new
+
+    @album.cover_image_uid                                   # => nil
+
+    @album.cover_image = File.new('path/to/my_image.png')
+    @album.cover_image_uid                                   # => nil
+
+    @album.save
+    @album.cover_image_uid                                   # => '2009/12/05/file.png' (some unique uid, used by the datastore)
+
+URLs
+----
+Once the model is saved, we can get a url for the image (which is served by the Dragonfly {Dragonfly::App App} itself), and for its processed/encoded versions:
+
+    @album.cover_image.url                           # => '/media/BAhbBlsHOgZmIhgy...'
+    @album.cover_image.thumb('300x200#nw').url       # => '/media/BAhbB1sYusgZhgyM...'
+    @album.cover_image.process(:greyscale).jpg.url   # => '/media/BnA6CnRodW1iIg8z...'
+
+Because the processing/encoding methods (including shortcuts like `thumb` and `jpg`) are lazy, no processing or encoding is actually done.
+
+Validations
+-----------
+`validates_presence_of` and `validates_size_of` work out of the box, and Dragonfly also provides `validates_property`.
+
+    class Album
+
+      validates_presence_of :cover_image
+      validates_size_of :cover_image, :maximum => 500.kilobytes
+
+      validates_property :format, :of => :cover_image, :in => [:jpeg, :png, :gif]
+      # ..or..
+      validates_property :mime_type, :of => :cover_image, :in => %w(image/jpeg image/png image/gif)
+
+      validates_property :width, :of => :cover_image, :in => (0..400), :message => "é demais cara!"
+
+      # ...
+    end
+
+The property argument of `validates_property` will generally be one of the registered analyser properties as described in {file:Analysers.md Analysers}.
+However it would actually work for arbitrary properties, including those of non-dragonfly model attributes.
+
+Name and extension
+------------------
+If the object assigned is a file, or responds to `original_filename` (as is the case with file uploads in Rails, etc.), then `name` will be set.
+
+    @album.cover_image = File.new('path/to/my_image.png')
+
+    @album.cover_image.name    # => 'my_image.png'
+    @album.cover_image.ext     # => 'png'
+
+
+'Magic' Attributes
+------------------
+An accessor like `cover_image` only relies on the accessor `cover_image_uid` to work.
+However, in some cases you may want to record some other properties, whether it be for using in queries, or
+for caching an attribute for performance reasons, etc.
+
+For the properties `name`, `ext`, `size` and any of the registered analysis methods (e.g. `width`, etc. in the examples above),
+this is done automatically for you, if the corresponding accessor exists.
+
+For example - with ActiveRecord, given the migration:
+
+    add_column :albums, :cover_image_width, :integer
+
+This will automatically be set when assigned:
+
+    @album.cover_image = File.new('path/to/my_image.png')
+
+    @album.cover_image_width  # => 280
+
+They can be used to avoid retrieving data from the datastore for analysis
+
+    @album = Album.first
+
+    @album.cover_image.width     # => 280    - no need to retrieve data - takes it from `cover_image_width`
+    @album.cover_image.size      # => 134507 - but this needs to retrieve data from the data store, then analyse
+
+
+Custom Model
+------------
+The accessors only require that your model class implements `before_save`, `before_destroy` and `validates_each`
+(if using validations), as well as of course the `..._uid` field for storing the datastore uid.
+
+Here is an example of a minimal ActiveModel `Album` model:
+
+    class CustomModel::Base
+
+      extend ActiveModel::Callbacks
+      define_model_callbacks :save, :destroy
+
+      include ActiveModel::Validations   # if needed
+
+      def save
+        _run_save_callbacks {
+          # do some saving!
+        }
+      end
+
+      def destroy
+        _run_destroy_callbacks {
+          # do some destroying!
+        }
+      end
+
+    end
+
+Define our `image_accessor` macro...
+
+    app.define_macro(CustomModel::Base, :image_accessor)
+
+...which is used by `Album`:
+
+    class Album < CustomModel::Base
+
+      def cover_image_uid=
+        # ...
+      end
+
+      def cover_image_uid
+        # ...
+      end
+
+      image_accessor :cover_image
+
+    end