dragonfly 0.8.6 → 0.9.0

data/extra_docs/ExampleUseCases.md

@@ -0,0 +1,113 @@
+Example Use Cases
+=================
+Below are a number of examples of uses for Dragonfly which differ slightly from the standard image resizing with model attachments.
+
+Non-image attachments in Rails
+------------------------------
+When using `'dragonfly/rails'images'` or similar configuration, if you're not calling `thumb`, `width`
+or other image-related methods on your content, then non-image attachments should _just work_.
+
+    class User
+      image_accessor :mugshot
+    end
+
+    user.mugshot = Rails.root.join('some/text_file.txt')
+    user.save!
+    user.mugshot.url   # /media/BAsfsdfajkl....
+
+Furthermore, the imagemagick configuration gives you an `image?` analyser method which always returns a boolean
+so you can still make a thumbnail if it is an image
+
+    user.mugshot.thumb!('400x300#') if user.mugshot.image?
+
+`'dragonfly/rails/images'` also gives you a `file_accessor` macro which is actually just the same as `image_accessor`,
+but a bit more meaningful when not dealing with images
+
+    class User
+      file_accessor :mugshot
+    end
+
+You can always define your own macro for dealing with non-image attachments:
+
+    Dragonfly[:my_app].define_macro(ActiveRecord::Base, :attachment_accessor)
+
+    class User
+      attachment_accessor :mugshot
+    end
+
+see {file:Models} for how to define macros with non-ActiveRecord libraries.
+
+Quick custom image processing in Rails
+--------------------------------------
+With the imagemagick configuration, we can easily use `convert` to do some custom processing, e.g. in the view:
+
+    <%= image_tag @user.mugshot.thumb('300x300#').convert('-blur 4x2').url %>
+
+If we use this a lot, we can define a shortcut for it - in config/initializers/dragonfly.rb:
+
+    Dragonfly[:images].configure do |c|
+      c.job :blurred_square do |size|
+        process :resize_and_crop, :width => size, :height => size
+        process :convert, '-blur 4x2'
+      end
+    end
+
+then in the view:
+
+    <%= image_tag @user.mugshot.blurred_square(300).url %>
+
+See {file:ImageMagick} for more info.
+
+Using Javascript to generate on-the-fly thumbnails in Rails
+-----------------------------------------------------------
+Supposing we have a `Pancake` model with an image attachment
+
+    pancake = Pancake.create! :image => Pathname.new('path/to/pancake.png')
+
+Setting the attachment sets the uid field (this example uses the {file:DataStorage#File\_datastore FileDataStore})
+
+    pancake.image_uid    # '2011/04/27/17_04_32_705_pancake.png'
+
+We can set up a Dragonfly endpoint in routes.rb for generating thumbnails:
+
+    match '/thumbs/:geometry' => app.endpoint { |params, app|
+      app.fetch(params[:uid]).thumb(params[:geometry])
+    }
+
+If we have access to the image uid in javascript, we can create the url like so:
+
+    var url = '/thumbs/400x300?uid=' + uid
+
+Then we can get the content with ajax, create an img tag, etc.
+
+NB: in the above example we've put the uid in the query string and not the path because the dot in it confuses Rails' pattern recognition.
+You could always put it in the path and escape/unescape it either side of the request.
+
+Also javascript's built-in `encodeURIComponent` function may be useful when Rails has difficulty matching routes due to special characters like '#' and '/'.
+
+Text generation with Sinatra
+----------------------------
+We can easily generate on-the-fly text with Sinatra and the {Dragonfly::ImageMagick::Generator ImageMagick Generator}:
+
+    require 'rubygems'
+    require 'sinatra'
+    require 'dragonfly'
+
+    app = Dragonfly[:images].configure_with(:imagemagick)
+
+    get '/:text' do |text|
+      app.generate(:text, text, :font_size => 30).to_response(env)
+    end
+
+When we visit '/hello!' we get a generated image of the text "hello!".
+
+See {file:ImageMagick#Generator} for more details.
+
+Creating a Dragonfly plugin
+---------------------------
+You can create custom {file:DataStorage#Custom\_datastore data stores}, {file:Processing#Custom\_Processors processors},
+{file:Encoding#Custom\_Encoders encoders}, {file:Analysers#Custom\_Analysers analysers} and {file:Generators#Custom\_Generators generators}, and
+then tie them all together with a {file:Configuration#Custom\_Saved\_Configuration saved configuration}.
+
+See [Dragonfly-RMagick](http://github.com/markevans/dragonfly-rmagick) for an example.
+NOTE: you will probably want to create classes and modules in your own namespace, rather than the `Dragonfly` namespace (even though Dragonfly-RMagick uses it).

data/extra_docs/GeneralUsage.md

@@ -11,15 +11,19 @@ Each app has a name, and is referred to by that name.
 
 Getting/generating content
 --------------------------
-Three methods can be used to get content:
+A number of 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.fetch_url('somewhere.com/img.png')  # Fetch from a url (will work with http, https)
+
     app.generate(:plasma, 400, 300)         # Generates using a method from the configured
                                             # generator (in this case a plasma image)
 
+    app.create("CONTENT")                   # Can pass in a String, Pathname, File or Tempfile
+
 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.
 
@@ -44,6 +48,7 @@ We can get the data a number of ways...
 We can get its url...
 
     image.url                            # => "/media/BAhbBlsHOgZmIg9hc..."
+                                         # this won't work if we've used create to get the content
 
 We can analyse it (see {file:Analysers} for more info) ...
 
@@ -59,18 +64,7 @@ We can encode it (see {file:Encoding} for more info) ...
 
 Chaining
 --------
-Because the methods
-
-  - `fetch`
-
-  - `fetch_file`
-
-  - `generate`
-
-  - `process`
-
-  - `encode`
-
+Because the methods `fetch`, `fetch_file`, `fetch_url`, `generate`, `create`, `process` and `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)
@@ -109,13 +103,3 @@ To define this shortcut:
       end
       # ...
     end
-
-The {Dragonfly::Config::ImageMagick ImageMagick} 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)
-    image.convert('-scale 30x30')     # same as image.process(:convert, '-scale 30x30')
-
-`thumb` and `convert` can optionally take a format (e.g. :gif) as the second argument.

data/extra_docs/Generators.md

@@ -15,62 +15,19 @@ we can get generated content using
 
 where `:some_method` is added by the configured generators.
 
-ImageMagickGenerator
---------------------
-The {Dragonfly::Generation::ImageMagickGenerator ImageMagickGenerator} is registered by default by the
-{Dragonfly::Config::ImageMagick ImageMagick configuration} used by 'dragonfly/rails/images'.
-
-If not already registered:
-
-    app.generator.register(Dragonfly::Generation::ImageMagickGenerator)
-
-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/script/command-line-options.php#font}), which could be a complete filename.
-Available fonts are those available on your system.
-
-RMagickGenerator
-----------------
-The {Dragonfly::Generation::RMagickGenerator RMagickGenerator} gives you `plasma` and `text` like the imagemagick generator above, using the
-{http://rmagick.rubyforge.org RMagick} library.
-
-You can tell it not to use the file system when registering it
-
-    app.generator.register(Dragonfly::Generation::RMagickGenerator){|g| g.use_filesystem = false }
-
+ImageMagick Generator
+---------------------
+See {file:Imagemagick}.
 
 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
+    app.generator.add :triangle do |height|
+      SomeLibrary.create_triangle(height)     # return a String, Pathname, File or Tempfile
     end
 
-    app.generate(:blank_image, 'red')      # => 'Job' object which we can get data, etc.
-
+    app.generate(:triangle, 10)      # => 'Job' object which we can get data, etc.
 
 Or create a class like the ImageMagick one above, in which case all public methods will be counted as generator methods.
 
@@ -100,3 +57,12 @@ Or create a class like the ImageMagick one above, in which case all public metho
 
     app.generate(:top_left_corner, :colour => 'green')
     app.generate(:bottom_right_corner, :colour => 'mauve')
+
+You can also return meta data like name and format if you return an array from the generator
+
+    app.generator.add :triangle do |height|
+      [
+        SomeLibrary.create_triangle(height),
+        {:name => 'triangle.png', :format => :png}
+      ]
+    end

data/extra_docs/Heroku.md

@@ -12,10 +12,10 @@ Assuming you have an S3 account set up...
 
 Gem dependencies:
 
-    - aws-s3 (require as aws/s3)
+    - fog
     - dragonfly
 
-Initializer (e.g. config/initializers/dragonfly.rb):
+Initializer (e.g. config/initializers/dragonfly.rb in Rails):
 
     require 'dragonfly'
     app = Dragonfly[:images]
@@ -28,10 +28,9 @@ Initializer (e.g. config/initializers/dragonfly.rb):
 
 The datastore remains as the {Dragonfly::DataStorage::FileDataStore FileDataStore} for non-production environments.
 
-environment.rb (application.rb in Rails 3):
+application.rb if using with Rails:
 
-    # make sure the last arg is the same as the app's configured prefix
-    config.middleware.insert_before 'Rack::Lock', 'Dragonfly::Middleware', :images, '/media'
+    config.middleware.insert 0, 'Dragonfly::Middleware', :images
 
 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).
@@ -40,11 +39,11 @@ From your app's directory:
 
     heroku config:add S3_KEY=XXXXXXXXX S3_SECRET=XXXXXXXXXX
 
-Obviously replace 'XXXXXXXXX' with your access key and secret.
+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!!!
+**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.
+If this is an issue, you may want to look into storing thumbnails on S3 (see {file:ExampleUseCases}), 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/ImageMagick.md

@@ -0,0 +1,126 @@
+ImageMagick
+===========
+Either `require 'dragonfly/rails/images'` or `Dragonfly[:images].configure_with(:imagemagick)`
+gives us an ImageMagick {Dragonfly::ImageMagick::Processor Processor}, {Dragonfly::ImageMagick::Encoder Encoder},
+{Dragonfly::ImageMagick::Analyser Analyser} and {Dragonfly::ImageMagick::Generator Generator}.
+
+Given a {Dragonfly::Job Job} object
+
+    image = app.fetch('some/uid')
+
+...OR a Dragonfly model accessor...
+
+    image = @album.cover_image
+
+we have the following:
+
+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)
+    image.strip                       # same as image.process(:strip)
+    image.convert('-scale 30x30')     # same as image.process(:convert, '-scale 30x30')
+
+`thumb` and `convert` can optionally take a format (e.g. :gif) as the second argument.
+Bang methods like `image.thumb!('40x30')`, `image.png!` etc. will operate on `self`.
+
+Below are some examples of geometry strings for `thumb`:
+
+    '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
+
+Processor
+---------
+
+    image.process(:crop, :width => 40, :height => 50, :x => 20, :y => 30)
+    image.process(:crop, :width => 40, :height => 50, :gravity => 'ne')
+
+    image.process(:flip)                         # flips it vertically
+    image.process(:flop)                         # flips it horizontally
+
+    image.process(:greyscale, :depth => 128)     # default depth 256
+
+    image.process(:resize, '40x40')
+    image.process(:resize_and_crop, :width => 40, :height=> 50, :gravity => 'ne')
+
+    image.process(:rotate, 45, :background_colour => 'transparent')   # default bg black
+
+The method `thumb` takes a geometry string and calls `resize`, `resize_and_crop` or `crop` accordingly.
+
+    image.process(:thumb, '400x300')             # calls resize
+
+Encoder
+-------
+The {Dragonfly::ImageMagick::Encoder ImageMagick Encoder} gives us:
+
+    image.encode(:jpg)
+    image.encode(:gif)
+    image.encode(:png)
+    image.encode(:tiff)
+
+and various other formats (see {Dragonfly::ImageMagick::Encoder ImageMagick Encoder}).
+
+You can also pass additional options to the imagemagick command line:
+
+    image.encode(:jpg, '-quality 10')
+
+Analyser
+--------
+The {Dragonfly::ImageMagick::Analyser ImageMagick Analyser} 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
+    image.image?              # => true - will return true or false for any content
+
+Generator
+---------
+The {Dragonfly::ImageMagick::Generator ImageMagick Generator} gives us these methods:
+
+    image = app.generate(:plain, 600, 400, 'rgba(40,200,30,0.5)')
+    image = app.generate(:plain, 600, 400, '#ccc', :format => :gif)
+                                                        # generate a 600x400 plain image
+                                                        # any css-style colour should work
+
+    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 text generation 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/script/command-line-options.php#font}), which could be a complete filename.
+Available fonts are those available on your system.

data/extra_docs/MimeTypes.md

@@ -7,8 +7,8 @@ This is decided by the first found from:
 
 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)
+3. Analyse the content using the analyser's 'format' method (if exists)
+4. Analyse the content using the analyser's 'mime_type' 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.
@@ -27,7 +27,7 @@ You can also do this inside a configuration block.
 Analysers
 ---------
 The {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} has a `mime_type` method and the
-{Dragonfly::Analysis::ImageMagickAnalyser ImageMagickAnalyser} has a `format` method.
+{Dragonfly::ImageMagick::Analyser ImageMagick Analyser} has a `format` method.
 
 These are both registered by default when you use the preconfigured 'dragonfly/rails/images' file.
 

data/extra_docs/Models.md

@@ -24,6 +24,12 @@ Mongoid
 
 defines the macro `image_accessor` on any models that include `Mongoid::Document`
 
+CouchRest::Model
+-------
+    app.define_macro(CouchRest::Model::Base, :image_accessor)
+
+defines the macro `image_accessor` on any models inherited from `CouchRest::Model::Base`.
+
 Adding accessors
 ----------------
 Now we have the method `image_accessor` available in our model classes, which we can use as many times as we like
@@ -62,6 +68,7 @@ We can use the attribute much like other other model attributes:
     @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 = Pathname.new('some/path.gif')     # ... or as a pathname...
     @album.cover_image = @album.band_photo                 # ... or as another Dragonfly attachment
 
     @album.cover_image          # => #<Dragonfly::ActiveModelExtensions::Attachment:0x103ef6128...
@@ -119,6 +126,42 @@ You can force the processing to be done if you must by then calling `apply`.
 
     @album.cover_image.process(:greyscale).apply
 
+Assigning from a url
+--------------------
+Dragonfly provides an accessor for assigning directly from a url:
+
+    @album.cover_image_url = 'http://some.url/file.jpg'
+
+You can put this in a form view, e.g. in rails erb:
+
+    <% form_for @album, :html => {:multipart => true} do |f| %>
+      ...
+      <%= f.text_field :cover_image_url %>
+      ...
+    <% end %>
+
+Removing an attachment via a form
+---------------------------------
+Normally unassignment of an attachment is done like any other attribute, by setting to nil
+
+    @album.cover_image = nil
+
+but this can't be done via a form - instead `remove_<attachment_name>` is provided, which can be used with a checkbox:
+
+    <%= f.check_box :remove_cover_image %>
+
+Retaining across form redisplays
+--------------------------------
+When a model fails validation, you don't normally want to have to upload your attachment again, so you can avoid having to do this by
+including a hidden field in your form `retained_<attribute_name>`, e.g.
+
+    <% form_for @album, :html => {:multipart => true} do |f| %>
+      ...
+      <%= f.file_field :cover_image %>
+      <%= f.hidden_field :retained_cover_image %>
+      ...
+    <% end %>
+
 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})
@@ -190,6 +233,124 @@ As you can see, a couple of things are added by the model. You can also access t
 
     app.fetch(@album.cover_image_uid).meta     # => {:model_class=>"Album", ...}
 
+Meta data can be useful because at the time that Dragonfly serves content, it doesn't have access to your model, but it does
+have access to the meta data that was stored alongside the content, so you could use it to provide custom response headers, etc.
+(see {file:Configuration}).
+
+Callbacks
+---------
+**after_assign**
+
+`after_assign` can be used to do something every time content is assigned:
+
+    class Person
+      image_accessor :mugshot do
+        after_assign{|a| a.process!(:rotate, 90) }  # 'a' is the attachment itself
+      end
+    end
+
+    person.mugshot = Pathname.new('some/path.png')  # after_assign callback is called
+    person.mugshot = nil                            # after_assign callback is NOT called
+    
+Inside the block, you can call methods on the model instance directly (`self` is the model):
+
+    class Person
+      image_accessor :mugshot do
+        after_assign{|a| a.process!(:rotate, angle) }
+      end
+
+      def angle
+        90
+      end
+    end
+
+Alternatively you can pass in a symbol, corresponding to a model instance method:
+
+    class Person
+      image_accessor :mugshot do
+        after_assign :rotate_it
+      end
+
+      def rotate_it
+        mugshot.process!(:rotate, 90)
+      end
+    end
+
+You can register more than one `after_assign` callback.
+
+**after_unassign**
+
+`after_unassign` is similar to `after_assign`, but is only called when the attachment is unassigned
+
+    person.mugshot = Pathname.new('some/path.png')  # after_unassign callback is NOT called
+    person.mugshot = nil                            # after_unassign callback is called
+
+Up-front thumbnailing
+---------------------
+The best way to create different versions of content such as thumbnails is generally on-the-fly, however if you _must_
+create another version _on-upload_, then you could create another accessor and automatically copy to it using `copy_to`.
+
+    class Person
+      image_accessor :mugshot do
+        copy_to(:smaller_mugshot){|a| a.thumb('200x200#') }
+      end
+      image_accessor :smaller_mugshot
+    end
+
+    person.mugshot = Pathname.new('some/400x300/image.png')
+    
+    person.mugshot            # ---> 400x300 image
+    person.smaller_mugshot    # ---> 200x200 image
+
+In the above example you would need both a `mugshot_uid` field and a `smaller_mugshot_uid` field on your model.
+
+Storage options
+---------------
+Some datastores take options when calling `store` - you can pass these through using `storage_xxx` methods, e.g.
+
+**storage_path**
+
+The {Dragonfly::DataStorage::FileDataStore FileDataStore} and {Dragonfly::DataStorage::S3DataStore S3DataStore} both
+can take a `:path` option to specify where to store the content (which will also become the uid for that content)
+
+    class Person
+      image_accessor :mugshot do
+        storage_path{ "some/path/#{id}/#{rand(100)}" }  # You can call model instance methods (like 'id') directly
+      end
+    end
+
+or
+
+    class Person
+      image_accessor :mugshot do
+        storage_path :path_for_mugshot
+      end
+      
+      def path_for_mugshot
+        "some/path/#{id}/#{rand(100)}"
+      end
+    end
+
+or you can also yield the attachment itself
+
+        storage_path{|a| "some/path/#{a.width}x#{a.height}.#{a.format}" }
+
+**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.
+
+You can pass any options through to the datastore using `storage_xxx` methods, or all at once using `storage_opts`:
+
+    class Person
+      image_accessor :mugshot do
+        storage_opts do |a|
+          {
+            :path => "some/path/#{id}/#{rand(100)}",
+            :other => 'option'
+          }
+        end
+      end
+    end
+
 "Magic" Attributes
 ------------------
 An accessor like `cover_image` only relies on the accessor `cover_image_uid` to work.
@@ -216,6 +377,8 @@ They can be used to avoid retrieving data from the datastore for analysis
     @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
 
+Furthermore, any magic attributes you add a field for will be added to the meta data for that attachment (and so can be used when Dragonfly serves the content
+for e.g. setting custom response headers based on that meta - see {file:Configuration}).
 
 Custom Model
 ------------