dragonfly 0.5.7 → 0.6.0

data/.gitignore

@@ -7,3 +7,4 @@ pkg
 doc
 tmp
 fixtures/*/tmp_app
+.ginger

data/.yardopts

@@ -13,3 +13,4 @@ extra_docs/Encoding.md
 extra_docs/MimeTypes.md
 extra_docs/ExampleUseCases.md
 LICENSE
+History.md

data/History.md

@@ -0,0 +1,109 @@
+0.6.0 (2010-05-11)
+==================
+
+Features
+--------
+- Added 'scale factor' for text generation, which gives better quality font rendering for smaller fonts
+- Configurable objects allow for passing args, and passing a block for extra config
+- Added more 'saved configurations', for easier setting up on e.g. Heroku
+- Added RMagickAnalyser#format
+- Added greyscale to RMagickProcessor
+- S3DataStore is configurable as to whether it uses the filesystem or not (to save a tempfile)
+
+Fixes
+-----
+- Some specs refactoring, including making text processing specs less brittle
+- RMagickEncoder::SUPPORTED_FORMATS was proving problematic - now we use a configurable list instead
+- Got Rails 3 beta3 cucumber features working
+- Added check to see if bucket already exists in S3DataStore - apparently this was problematic in EU
+
+Changes
+-------
+- temp_object.tempfile now returns a closed tempfile, which temp_object.file returns an open file.
+Can also pass a block to temp_object.file which closes the file automatically
+- Processors/Analysers/Encoders know about app now so can log to app's log
+- Imagemagick errors in RMagick processor/analyser/encoder now throw unable_to_handle and log a warning
+- Removed Rails generators - better being more explicit with saved configurations which are more concise now
+
+0.5.7 (2010-04-18)
+==================
+
+Fixes
+--------
+- Strip file command mime_type value because some versions of file command were appending a line-break
+
+0.5.6 (2010-04-13)
+==================
+
+Fixes
+--------
+- Wasn't working properly with Single-Table Inheritance
+
+0.5.5 (2010-04-13)
+==================
+
+Fixes
+--------
+- Rails 3 has changed 'metaclass' -> 'singleton_class' so adapt accordingly
+
+0.5.4 (2010-04-12)
+==================
+
+Features
+--------
+- Allow setting the uid manually
+
+Fixes
+-----
+- Assigning an accessor to nil wasn't working properly
+
+
+0.5.3 (2010-03-27)
+==================
+
+Fixes
+-----
+- Assigning an accessor to nil wasn't working properly
+
+
+0.5.2 (2010-03-04)
+==================
+
+Features
+--------
+- Added 'registered mime-types'
+- Enhanced docs
+
+Fixes
+-----
+- RMagickEncoder only encodes if not already in that format
+
+
+0.5.1 (2010-02-20)
+==================
+
+Fixes
+-----
+- Fixed 'broken pipe' errors in FileCommandAnalyser due to outputting loads of stuff to the command line stdin
+
+0.5.0 (2010-02-20)
+==================
+
+Added support
+-------------
+- support for Rails 3
+
+
+0.4.4 (2010-02-16)
+==================
+
+Better late than never to start logging change history...
+
+New features
+------------
+- added aspect_ratio to rmagick_analyser
+
+Added support
+-------------
+- support for ruby 1.9
+- added development dependencies to gemspec for easier setting up

data/VERSION

@@ -1 +1 @@
-0.5.7
+0.6.0

data/config.rb

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

data/dragonfly.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{dragonfly}
-  s.version = "0.5.7"
+  s.version = "0.6.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Evans"]
-  s.date = %q{2010-04-18}
+  s.date = %q{2010-05-11}
   s.email = %q{mark@new-bamboo.co.uk}
   s.extra_rdoc_files = [
     "LICENSE",
@@ -18,7 +18,7 @@ Gem::Specification.new do |s|
   s.files = [
     ".gitignore",
      ".yardopts",
-     "History.txt",
+     "History.md",
      "LICENSE",
      "README.md",
      "Rakefile",
@@ -41,25 +41,20 @@ Gem::Specification.new do |s|
      "features/images.feature",
      "features/no_processing.feature",
      "features/rails_2.3.5.feature",
-     "features/rails_3.0.0.beta.feature",
+     "features/rails_3.0.0.beta3.feature",
      "features/steps/common_steps.rb",
      "features/steps/dragonfly_steps.rb",
      "features/steps/rails_steps.rb",
      "features/support/env.rb",
-     "fixtures/dragonfly_setup.rb",
      "fixtures/files/app/models/album.rb",
      "fixtures/files/app/views/albums/new.html.erb",
      "fixtures/files/app/views/albums/show.html.erb",
-     "fixtures/files/config/initializers/aaa_dragonfly_load_path.rb",
+     "fixtures/files/config/initializers/dragonfly.rb",
      "fixtures/files/features/manage_album_images.feature",
      "fixtures/files/features/step_definitions/album_steps.rb",
      "fixtures/files/features/support/paths.rb",
-     "fixtures/rails",
      "fixtures/rails_2.3.5/template.rb",
-     "fixtures/rails_3.0.0.beta/template.rb",
-     "generators/dragonfly_app/USAGE",
-     "generators/dragonfly_app/dragonfly_app_generator.rb",
-     "generators/dragonfly_app/templates/initializer.erb",
+     "fixtures/rails_3.0.0.beta3/template.rb",
      "irbrc.rb",
      "lib/dragonfly.rb",
      "lib/dragonfly/active_record_extensions.rb",
@@ -72,6 +67,12 @@ Gem::Specification.new do |s|
      "lib/dragonfly/analysis/file_command_analyser.rb",
      "lib/dragonfly/analysis/r_magick_analyser.rb",
      "lib/dragonfly/app.rb",
+     "lib/dragonfly/belongs_to_app.rb",
+     "lib/dragonfly/config/heroku_rails_images.rb",
+     "lib/dragonfly/config/r_magick_images.rb",
+     "lib/dragonfly/config/r_magick_text.rb",
+     "lib/dragonfly/config/rails_defaults.rb",
+     "lib/dragonfly/config/rails_images.rb",
      "lib/dragonfly/configurable.rb",
      "lib/dragonfly/core_ext/object.rb",
      "lib/dragonfly/core_ext/string.rb",
@@ -93,8 +94,8 @@ Gem::Specification.new do |s|
      "lib/dragonfly/parameters.rb",
      "lib/dragonfly/processing/base.rb",
      "lib/dragonfly/processing/r_magick_processor.rb",
+     "lib/dragonfly/processing/r_magick_text_processor.rb",
      "lib/dragonfly/processor_list.rb",
-     "lib/dragonfly/r_magick_configuration.rb",
      "lib/dragonfly/rails/images.rb",
      "lib/dragonfly/temp_object.rb",
      "lib/dragonfly/url_handler.rb",
@@ -105,7 +106,6 @@ Gem::Specification.new do |s|
      "samples/taj.jpg",
      "spec/argument_matchers.rb",
      "spec/dragonfly/active_record_extensions/attachment_spec.rb",
-     "spec/dragonfly/active_record_extensions/initializer.rb",
      "spec/dragonfly/active_record_extensions/migration.rb",
      "spec/dragonfly/active_record_extensions/model_spec.rb",
      "spec/dragonfly/active_record_extensions/models.rb",
@@ -113,6 +113,7 @@ Gem::Specification.new do |s|
      "spec/dragonfly/analysis/file_command_analyser_spec.rb",
      "spec/dragonfly/analysis/r_magick_analyser_spec.rb",
      "spec/dragonfly/app_spec.rb",
+     "spec/dragonfly/belongs_to_app_spec.rb",
      "spec/dragonfly/configurable_spec.rb",
      "spec/dragonfly/core_ext/string_spec.rb",
      "spec/dragonfly/core_ext/symbol_spec.rb",
@@ -125,7 +126,8 @@ Gem::Specification.new do |s|
      "spec/dragonfly/extended_temp_object_spec.rb",
      "spec/dragonfly/middleware_spec.rb",
      "spec/dragonfly/parameters_spec.rb",
-     "spec/dragonfly/processing/rmagick_processor_spec.rb",
+     "spec/dragonfly/processing/r_magick_processor_spec.rb",
+     "spec/dragonfly/processing/r_magick_text_processor_spec.rb",
      "spec/dragonfly/temp_object_spec.rb",
      "spec/dragonfly/url_handler_spec.rb",
      "spec/dragonfly_spec.rb",
@@ -148,7 +150,6 @@ Gem::Specification.new do |s|
   s.test_files = [
     "spec/argument_matchers.rb",
      "spec/dragonfly/active_record_extensions/attachment_spec.rb",
-     "spec/dragonfly/active_record_extensions/initializer.rb",
      "spec/dragonfly/active_record_extensions/migration.rb",
      "spec/dragonfly/active_record_extensions/model_spec.rb",
      "spec/dragonfly/active_record_extensions/models.rb",
@@ -156,6 +157,7 @@ Gem::Specification.new do |s|
      "spec/dragonfly/analysis/file_command_analyser_spec.rb",
      "spec/dragonfly/analysis/r_magick_analyser_spec.rb",
      "spec/dragonfly/app_spec.rb",
+     "spec/dragonfly/belongs_to_app_spec.rb",
      "spec/dragonfly/configurable_spec.rb",
      "spec/dragonfly/core_ext/string_spec.rb",
      "spec/dragonfly/core_ext/symbol_spec.rb",
@@ -168,7 +170,8 @@ Gem::Specification.new do |s|
      "spec/dragonfly/extended_temp_object_spec.rb",
      "spec/dragonfly/middleware_spec.rb",
      "spec/dragonfly/parameters_spec.rb",
-     "spec/dragonfly/processing/rmagick_processor_spec.rb",
+     "spec/dragonfly/processing/r_magick_processor_spec.rb",
+     "spec/dragonfly/processing/r_magick_text_processor_spec.rb",
      "spec/dragonfly/temp_object_spec.rb",
      "spec/dragonfly/url_handler_spec.rb",
      "spec/dragonfly_spec.rb",

data/extra_docs/ActiveRecord.md

@@ -11,13 +11,11 @@ Suppose we have a dragonfly app
 
     app = Dragonfly::App[:my_app_name]
 
-First extend activerecord
+We can define an accessor on ActiveRecord models using
 
-    ActiveRecord::Base.extend Dragonfly::ActiveRecordExtensions
+    Dragonfly.active_record_macro(:image, app)
 
-Now register the app, giving the prefix for defining accessor methods (in this case 'image')
-
-    ActiveRecord::Base.register_dragonfly_app(:image, app)
+The first argument is the prefix for the accessor macro (in this case 'image').
 
 Adding accessors
 ----------------
@@ -73,8 +71,11 @@ 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... i.e. a tempfile holding the data
-    album.cover_image.file                           # alias for tempfile, above
+    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)
 

data/extra_docs/Analysers.md

@@ -35,7 +35,7 @@ As the file command analyser is {Dragonfly::Configurable configurable}, we can c
       a.file_command = '/usr/bin/file'
     end
 
-The saved configuration {Dragonfly::RMagickConfiguration RMagickConfiguration} registers the above two analysers automatically.
+The saved configuration {Dragonfly::Config::RMagickImages RMagickImages} registers the above two analysers automatically.
 
 Custom Analysers
 ----------------

data/extra_docs/Encoding.md

@@ -27,7 +27,7 @@ Then we can encode {Dragonfly::ExtendedTempObject temp_objects} to formats recog
 
     temp_object.encode(:doc)    # => throws :unable_to_handle
 
-The saved configuration {Dragonfly::RMagickConfiguration RMagickConfiguration} registers the above encoder automatically.
+The saved configuration {Dragonfly::Config::RMagickImages RMagickImages} registers the above encoder automatically.
 
 Custom Encoders
 ---------------

data/extra_docs/ExampleUseCases.md

@@ -17,10 +17,6 @@ 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.
 
-As explained in {file:UsingWithRails}, we can use a generator to create an initializer for setting up Dragonfly.
-
-    ./script/generate dragonfly_app images
-
 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)
@@ -31,46 +27,47 @@ Amazon's {http://aws.amazon.com/s3 S3} is a commonly used platform for storing d
 
 The following assumes you have an S3 account set up, and know your provided 'access key' and 'secret'.
 
-Assuming we don't bother with any caching for development/testing environments, our environment.rb then has:
+### Rails 2.3
 
-    config.gem 'rmagick', :lib => 'RMagick'
-    config.gem 'dragonfly', :source => "http://www.gemcutter.org"
+environment.rb:
 
-(these are ignored by Heroku but you might want them locally)
+    config.gem 'rmagick', :lib => 'RMagick'
+    gem 'aws-s3', :lib => 'aws/s3'
+    config.gem 'dragonfly'
 
-The gems file for Heroku, `.gems`, has
+and
+.gems:
 
     dragonfly
+    aws-s3
 
-(rmagick not needed because it is already installed)
+### Rails 3
 
-Then in our configuration initializer, we replace
+Gemfile:
 
-    c.datastore.configure do |d|
-      d.root_path = "#{Rails.root}/public/system/dragonfly/#{Rails.env}"
-    end
+    gem 'rmagick', '2.12.2', :require => 'RMagick'
+    gem 'aws-s3', :require => 'aws/s3'
+    gem 'dragonfly'
 
-with
+Apparently to use Bundler you need to switch to the 'Bamboo' stack - see {http://docs.heroku.com/bamboo}
 
-    # Use S3 for production
-    if Rails.env == 'production'
-      c.datastore = Dragonfly::DataStorage::S3DataStore.new
-      c.datastore.configure do |d|
-        d.bucket_name = 'my_s3_bucket_name'
-        d.access_key_id = ENV['S3_KEY'] || raise("ENV variable 'S3_KEY' needs to be set")
-        d.secret_access_key = ENV['S3_SECRET'] || raise("ENV variable 'S3_SECRET' needs to be set")
-      end
-    # and filesystem for other environments
-    else
-      c.datastore.configure do |d|
-        d.root_path = "#{Rails.root}/public/system/dragonfly/#{Rails.env}"
-      end
-    end
+### 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)
 
-We've left the datastore as {Dragonfly::DataStorage::FileDataStore FileDataStore} for non-production environments.
+The datastore remains as the {Dragonfly::DataStorage::FileDataStore FileDataStore} for non-production environments.
 
-As you can see we've used `ENV` to store the S3 access key and secret to avoid having them in the repository.
-Heroku has a {http://docs.heroku.com/config-vars way of setting these} using the command line (we only have to do this once).
+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:
 
@@ -80,8 +77,8 @@ 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!
 
-The only downside is that Heroku's cache is cleared every time you deploy, so 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.
+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.
 
 
@@ -91,33 +88,25 @@ Although Dragonfly is normally concerned with processing and encoding, you may w
 (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.
-Let's generate a configuration for a Dragonfly App called 'attachments'
-
-    ./script/generate dragonfly_app attachments
 
-This generates an initializer for configuring the Dragonfly App 'attachments'.
+Initializer, e.g. config/initializers/dragonfly.rb:
 
-We won't be using RMagick or Rack::Cache (as there is no processing), so our environment.rb only has:
+    require 'dragonfly'
 
-    config.gem 'dragonfly',  :source => 'http://gemcutter.org'
-
-and in the generated configuration, we DELETE the line
-
-    app.configure_with(Dragonfly::RMagickConfiguration)
-
-Then in the configure block, we add the lines
-
-    c.url_handler.configure do |u|
-      # ...
-      u.protect_from_dos_attacks = false
+    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
-    c.register_analyser(Dragonfly::Analysis::FileCommandAnalyser)
-    c.register_encoder(Dragonfly::Encoding::TransparentEncoder)
+    Dragonfly.active_record_macro(:attachment, app)
 
-We don't need to protect the urls from Denial-of-service attacks as we aren't doing any expensive processing.
 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 may change in the future).
+(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
@@ -150,7 +139,7 @@ Each {Dragonfly::App Dragonfly App} has a 'generate' method, which returns an {D
 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 Rails helper files/generators)
+the RMagick/RailsImage configurations)
 
     Dragonfly::App[:my_app].register_processor(Dragonfly::Processing::RMagickProcessor)
 
@@ -167,30 +156,34 @@ A common technique for making sure a specific font is displayed on a website is
 
 We can easily use Dragonfly to do this on-the-fly.
 
-The {Dragonfly::Processing::RMagickProcessor RMagickProcessor} has a 'text' method, which takes content in the form of text,
-and creates an image of the text, given the options passed in.
+Configuration (e.g. initializer in Rails):
 
-We can also make use of the simple {Dragonfly::DataStorage::TransparentDataStore TransparentDataStore}, where rather than fetch
-data for a given uid, the uid IS the data.
-
-The configuration will look something like:
-
-    Dragonfly::App[:text].configure do |c|
-      c.datastore = Dragonfly::DataStorage::TransparentDataStore.new
-      c.register_analyser(Dragonfly::Analysis::FileCommandAnalyser)
-      c.register_processor(Dragonfly::Processing::RMagickProcessor)
-      c.register_encoder(Dragonfly::Encoding::RMagickEncoder)
-      c.parameters.configure do |p|
-        p.default_format = :png
-        p.default_processing_method = :text
-      end
+    require 'dragonfly'
+    Dragonfly::App[:text].configure_with(Dragonfly::Config::RMagickText) do |c|
+      c.url_handler.path_prefix = '/text'
     end
 
-We need the {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} for mime-type analysis.
+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', :processing_options => {:font_size => 30, :font_family => 'Monaco'})
+    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.)