dragonfly 0.6.2 → 0.7.0

data/config.rb

@@ -1,5 +0,0 @@
-require File.dirname(__FILE__) + '/lib/dragonfly'
-
-APP = Dragonfly::App[:images]
-APP.configure_with(Dragonfly::Config::RMagickImages)
-APP.url_handler.protect_from_dos_attacks = false

data/extra_docs/ActiveRecord.md

@@ -1,196 +0,0 @@
-ActiveRecord Extensions
-=======================
-
-Dragonfly provides a module that extends ActiveRecord so that you can access Dragonfly objects as if they were just another model attribute.
-
-Registering with ActiveRecord
------------------------------
-If you've used a rails generator, or required the file 'dragonfly/rails/images.rb', then this step will be already done for you.
-
-Suppose we have a dragonfly app
-
-    app = Dragonfly::App[:my_app_name]
-
-We can define an accessor on ActiveRecord models using
-
-    Dragonfly.active_record_macro(:image, app)
-
-The first argument is the prefix for the accessor macro (in this case 'image').
-
-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
-
-For each accessor, we need a database field ..._uid, as a string, so in our migrations:
-
-    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 active record 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          # => #<Dragonfly::ActiveRecordExtensions::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 (can also use American spelling)
-    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
-
-    temp_object = album.cover_image.process(:resize, :geometry => '20x20')   # returns an ExtendedTempObject, with similar properties
-    temp_object.width                                                        # => 20
-    album.cover_image.width                                                  # => 280 (no change)
-    
-    album.cover_image.process!(:resize, :geometry => '20x20')                # (operates on self)
-    album.cover_image.width                                                  # => 20
-
-The available processing methods available (i.e. 'resize', etc.) come from the {Dragonfly} app's registered processors - see {file:Processing.md Processing}
-
-We can encode the data
-
-    temp_object = album.cover_image.encode(:gif)   # returns an ExtendedTempObject, with similar properties
-    temp_object.mime_type                          # => 'image/gif'
-    album.cover_image.mime_type                    # => 'image/png' (no change)
-    
-    album.cover_image.encode!(:gif)                # (operates on self)
-    album.cover_image.mime_type                    # => 'image/gif'
-
-The encoding is implemented by the {Dragonfly} app's registered encoders (which will usually just be one) - see {file:Encoding.md Encoding}
-
-If we have a combination of processing and encoding that we often use, e.g.
-
-    album.cover_image.process(:resize_and_crop, :width => 300, :height => 200, :gravity => 'nw').encode(:gif)
-
-then we can register a shortcut (see {file:Shortcuts.md Shortcuts}) and use that with `transform`, e.g.
-
-    album.cover_image.transform('300x200#nw', :gif)           # returns an ExtendedTempObject, like process and encode above
-    album.cover_image.transform!('300x200#nw', :gif)          # (operates on self)
-
-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                                   # => 'PENDING' (actually a Dragonfly::ActiveRecordExtensions::PendingUID)
-    
-    album.save
-    album.cover_image_uid                                   # => '2009/12/05/170406_file' (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):
-
-    album.cover_image.url                       # => '/media/2009/12/05/170406_file' (Note there is no extension)
-    album.cover_image.url(:png)                 # => '/media/2009/12/05/170406_file.png'
-    album.cover_image.url('300x200#nw', :gif)   # => '/media/2009/12/05/170406_file.tif?m=resize_and_crop&o[height]=...'
-
-Note that any arguments given to `url` are of the same form as those used for `transform`, i.e. those registered as shortcuts (see {file:Shortcuts.md Shortcuts})
-These urls are what you would use in, for example, html views.
-
-Validations
------------
-`validates_presence_of` and `validates_size_of` work out of the box, and Dragonfly provides two more,
-`validates_property` and `validates_mime_type_of` (which is actually just a thin wrapper around `validates_property`).
-
-    class Album
-
-      validates_presence_of :cover_image
-      validates_size_of :cover_image, :maximum => 500.kilobytes
-      validates_mime_type_of :cover_image, :in => %w(image/jpeg image/png image/gif)
-      validates_property :width, :of => :cover_image, :in => (0..400)
-
-      # ...
-    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.
-See {Dragonfly::ActiveRecordExtensions::Validations Validations} for more info.
-
-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` and `ext` 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
-------------------
-The only model column necessary for the migration, as described above, is the uid column, e.g. `cover_image_uid`.
-However, in many cases you may want to record some other properties in the database, whether it be for using in sql queries, or
-for caching an attribute for performance reasons.
-
-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 column exists.
-For example:
-
-In the migration:
-
-    add_column :albums, :cover_image_ext, :string
-    add_column :albums, :cover_image_width, :integer
-
-These are automatically set when assigned:
-
-    album.cover_image = File.new('path/to/my_image.png')
-    
-    album.cover_image_ext    # => 'png'
-    album.cover_image_width  # => 280
-    
-They can be used to avoid retrieving data from the datastore for analysis (e.g. if you've used something like S3 to store data - see {file:DataStorage.md DataStorage})
-
-    album = Album.first
-    
-    album.cover_image.ext       # => 'png'  - no need to retrieve data - takes it from `cover_image_ext`
-    album.cover_image.width     # => 280    - no need to retrieve data - takes it from `cover_image_width`
-    album.cover_image.size      # => 134507 - but it needs to retrieve data from the data store, then analyse

data/extra_docs/ExampleUseCases.md

@@ -1,189 +0,0 @@
-Example Use Cases
-=================
-
-This document is concerned with different Dragonfly configurations, for various use cases.
-
-In a Rails app the configuration would generally be done in an initializer.
-
-In other Rack-based apps it could be config.ru, or anywhere where the application is generally set up.
-
-Image thumbnails in Rails
--------------------------
-See {file:UsingWithRails}
-
-
-Image thumbnails in Rails, hosted on Heroku with S3 storage
------------------------------------------------------------
-{http://heroku.com Heroku} is a commonly used platform for hosting Rack-based websites.
-The following assumes your site is set up for deployment onto 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}.
-Amazon's {http://aws.amazon.com/s3 S3} is a commonly used platform for storing data.
-
-The following assumes you have an S3 account set up, and know your provided 'access key' and 'secret'.
-
-### Rails 2.3
-
-environment.rb:
-
-    config.gem 'rmagick', :lib => 'RMagick'
-    gem 'aws-s3', :lib => 'aws/s3'
-    config.gem 'dragonfly'
-
-and
-.gems:
-
-    dragonfly
-    aws-s3
-
-### Rails 3
-
-Gemfile:
-
-    gem 'rmagick', '2.12.2', :require => 'RMagick'
-    gem 'aws-s3', :require => 'aws/s3'
-    gem 'dragonfly'
-
-Apparently to use Bundler you need to switch to the 'Bamboo' stack - see {http://docs.heroku.com/bamboo}
-
-### All versions
-
-Initializer (e.g. config/initializers/dragonfly.rb):
-
-    require 'dragonfly'
-    app = Dragonfly::App[:images]
-    app.configure_with(Dragonfly::Config::HerokuRailsImages, 'my_bucket_name')
-    Dragonfly.active_record_macro(:image, app)
-
-The datastore remains as the {Dragonfly::DataStorage::FileDataStore FileDataStore} for non-production environments.
-
-environment.rb (application.rb in Rails 3):
-
-    config.middleware.insert_after 'Rack::Lock', '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).
-
-From your app's directory:
-
-    heroku config:add S3_KEY=XXXXXXXXX S3_SECRET=XXXXXXXXXX
-
-Obviously you replace 'XXXXXXXXX' with your access key and secret.
-
-Now you can benefit use Dragonfly in the normal way, benefitting 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.
-
-
-Attaching files to ActiveRecord models with no processing or encoding
----------------------------------------------------------------------
-Although Dragonfly is normally concerned with processing and encoding, you may want to just use it with arbitrary uploaded files
-(e.g. .doc, .xls, .pdf files, etc.) without processing or encoding them, so as to still benefit from the {file:ActiveRecord ActiveRecord Extensions} API.
-
-The below shows how to do it in Rails, but the principles are the same in any context.
-
-Initializer, e.g. config/initializers/dragonfly.rb:
-
-    require 'dragonfly'
-
-    app = Dragonfly::App[:attachments]
-    app.configure_with(Dragonfly::Config::RailsDefaults) do |c|
-      c.register_analyser(Dragonfly::Analysis::FileCommandAnalyser)
-      c.register_encoder(Dragonfly::Encoding::TransparentEncoder)
-    end
-    Dragonfly.active_record_macro(:attachment, app)
-
-The {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} is needed to know the mime-type of the content,
-and the {Dragonfly::Encoding::TransparentEncoder TransparentEncoder} is like a 'dummy' encoder which does nothing
-(the way to switch off encoding will be simplified in future versions of Dragonfly).
-
-environment.rb (application.rb in Rails 3):
-
-    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :attachments
-
-If a user uploads a file called 'report.pdf', then normally the original file extension will be lost.
-Thankfully, to record it is as easy as adding an 'ext' column as well as the usual uid column to our migration
-(see {file:ActiveRecord} for more info about 'magic attributes'):
-
-    add_column :my_models, :attachment_uid, :string
-    add_column :my_models, :attachment_ext, :string
-    
-Then we include a helper method in our model for setting the correct file extension when we link to the attachment:
-
-    class MyModel < ActiveRecord::Base
-
-      attachment_accessor :attachment
-      
-      def url_for_attachment
-        attachment.url :format => attachment_ext
-      end
-    end
-
-Now we can add links to the attached file in our views:
-
-    <%= link_to 'Attachment', @my_model.url_for_attachment %>
-
-
-Generating test data
---------------------
-We may want to generate a load of test data in a test / populate script.
-
-Each {Dragonfly::App Dragonfly App} has a 'generate' method, which returns an {Dragonfly::ExtendedTempObject ExtendedTempObject} with generated data.
-The actual generation is delegated to the registered processors (along with any args passed in).
-
-For example, if our app is registered with the {Dragonfly::Processing::RMagickProcessor RMagickProcessor} (which is already done if using with one of
-the RMagick/RailsImage configurations)
-
-    Dragonfly::App[:my_app].register_processor(Dragonfly::Processing::RMagickProcessor)
-
-then we can generate images of different sizes/formats):
-
-    image = Dragonfly::App[:my_app].generate(300, 200)       # creates a png image of size 300x200 (as an ExtendedTempObject)
-    image.to_file('out.png')                                 # writes to file 'out.png'
-    image = Dragonfly::App[:my_app].generate(50, 50, :gif)   # creates a gif image of size 50x50
-
-
-Text image replacement
-----------------------
-A common technique for making sure a specific font is displayed on a website is replacing text with images.
-
-We can easily use Dragonfly to do this on-the-fly.
-
-Configuration (e.g. initializer in Rails):
-
-    require 'dragonfly'
-    Dragonfly::App[:text].configure_with(Dragonfly::Config::RMagickText) do |c|
-      c.url_handler.path_prefix = '/text'
-    end
-
-If using Rails, then in environment.rb (application.rb in Rails 3):
-
-    config.middleware.insert_after 'Rack::Lock', 'Dragonfly::Middleware', :text
-    
-You probably will want to insert Rack::Cache too or use some other caching proxy - see {file:UsingWithRails}.
-
-Then when we visit a url like
-
-    url = Dragonfly::App[:text].url_for('some text', :text, :font_size => 30, :font_family => 'Monaco')
-
-we get a png image of the text. We could easily wrap this in some kind of helper if we use it often.
-
-This configuration uses the {Dragonfly::Processing::RMagickTextProcessor RMagickTextProcessor} processor.
-Options can be specified either css-like (e.g. `'font-family' => 'Helvetica'`), or with underscore-style symbols
-(e.g. `:font_family => 'Helvetica'`).
-
-Available options are `font` (see {http://www.imagemagick.org/RMagick/doc/draw.html#font}),
-`'font-family'`,
-`'stroke_color'`,
-`'color'`,
-`'font_style'`,
-`'font_stretch'`,
-`'font_weight'` and
-`'padding'` (or `'padding-left'`, `'padding-top'`, etc.)

data/extra_docs/GettingStarted.md

@@ -1,114 +0,0 @@
-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::Config::RMagickImages)
-
-    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.