dragonfly 0.1.6 → 0.2.1

data/.yardopts

@@ -0,0 +1,4 @@
+--no-private
+-e yard/setup.rb
+--files extra_docs/*
+

data/{README.markdown → README.md}

@@ -7,38 +7,20 @@ It includes an extension for Ruby on Rails to enable easy image handling.
 For the lazy rails user
 -----------------------
 
-In environment.rb:
+environment.rb:
 
     config.gem 'dragonfly-rails', :lib => 'dragonfly/rails/images'
     config.middleware.use 'Dragonfly::MiddlewareWithCache', :images
 
 Migration:
 
-    class AddCoverImageToAlbums < ActiveRecord::Migration
-
-      def self.up
-        add_column :albums, :cover_image_uid, :string
-      end
-
-      def self.down
-        remove_column :albums, :cover_image_uid
-      end
-
-    end
+    add_column :albums, :cover_image_uid, :string
 
 Model:
 
     class Album < ActiveRecord::Base
-    
-      
-      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)
-      
-      image_accessor :cover_image            # This provides the reader/writer for cover_image
-      
-      image_accessor :some_other_image       # have as many as you like - each needs a xxxx_uid column as per migration above
-    
+      image_accessor :cover_image            # Defines reader/writer for cover_image
+      # ...
     end
 
 View (for uploading via a file field):
@@ -52,6 +34,7 @@ View (for uploading via a file field):
 
 View (to display):
 
+    <%= image_tag @album.cover_image.url(:gif) %>
     <%= image_tag @album.cover_image.url('400x200') %>
     <%= image_tag @album.cover_image.url('100x100!', :png) %>
     <%= image_tag @album.cover_image.url('100x100#') %>
@@ -60,12 +43,17 @@ View (to display):
     ...etc.
 
 Using outside of rails, custom storage/processing/encoding/analysis, and more...
-------------------------------------------------------------------------
+--------------------------------------------------------------------------------
 Dragonfly is primarily a Rack app, the Rails part of it being nothing more than a separate layer on top of the main code, which means you can use it as a standalone app, or with Sinatra, Merb, etc.
 
 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.
 
-The docs are in the process of being added, and will appear soon!...
+For more info, consult the <a href="http://yardoc.org/docs/markevans-dragonfly">DOCUMENTATION</a>
+
+Issues
+======
+Please use the <a href="http://github.com/markevans/dragonfly/issues">github issue tracker</a> if you have any issues.
+
 
 Credits
 =======

data/Rakefile

@@ -10,6 +10,7 @@ begin
     s.homepage = "http://github.com/markevans/dragonfly"
     s.authors = ["Mark Evans"]
     s.add_dependency('rack')
+    s.has_rdoc = 'yard'
   end
   Jeweler::Tasks.new do |s|
     s.name = "dragonfly-rails"
@@ -23,7 +24,6 @@ begin
     s.add_dependency('dragonfly')
     s.add_dependency('rack')
     s.add_dependency('rack-cache')
-    s.add_dependency('mime-types')
     s.add_dependency('rmagick')
   end
 rescue LoadError
@@ -41,12 +41,12 @@ end
 
 require 'yard'
 YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb']
-  t.options = %w(--no-private)
+  t.files   = ['lib/**/*.rb', 'markdown_docs/*']
+  t.options = %w(--no-private -e yard/setup.rb --files extra_docs/*)
 end
 YARD::Rake::YardocTask.new 'yard:changed' do |t|
-  t.files   = `git stat | grep '.rb' | grep modified | cut -d' ' -f4`.split
-  t.options = %w(--no-private)
+  t.files   = `git stat | grep '.rb' | grep modified | grep -v yard | cut -d' ' -f4`.split
+  t.options = %w(--no-private -e yard/setup.rb --files extra_docs/*)
 end
 
 require 'spec/rake/spectask'
@@ -68,4 +68,4 @@ rescue LoadError
   puts "Cucumber is not available. In order to run features, you must: sudo gem install cucumber"
 end
 
-task :default => :spec
+task :default => [:spec, :features]

data/VERSION

@@ -1 +1 @@
-0.1.6
+0.2.1

data/config.rb

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

data/docs.watchr

@@ -1 +1 @@
-watch( 'lib/.*\.rb' )  {|md| system("rake yard:changed") }
+watch('lib/.*\.rb|yard/.*|extra_docs/.*')  {|md| system("rake yard:changed") }

data/dragonfly-rails.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{dragonfly-rails}
-  s.version = "0.1.6"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Evans"]
-  s.date = %q{2009-11-18}
+  s.date = %q{2009-12-11}
   s.email = %q{mark@new-bamboo.co.uk}
   s.homepage = %q{http://github.com/markevans/dragonfly}
   s.rdoc_options = ["--charset=UTF-8"]
@@ -25,20 +25,17 @@ Gem::Specification.new do |s|
       s.add_runtime_dependency(%q<dragonfly>, [">= 0"])
       s.add_runtime_dependency(%q<rack>, [">= 0"])
       s.add_runtime_dependency(%q<rack-cache>, [">= 0"])
-      s.add_runtime_dependency(%q<mime-types>, [">= 0"])
       s.add_runtime_dependency(%q<rmagick>, [">= 0"])
     else
       s.add_dependency(%q<dragonfly>, [">= 0"])
       s.add_dependency(%q<rack>, [">= 0"])
       s.add_dependency(%q<rack-cache>, [">= 0"])
-      s.add_dependency(%q<mime-types>, [">= 0"])
       s.add_dependency(%q<rmagick>, [">= 0"])
     end
   else
     s.add_dependency(%q<dragonfly>, [">= 0"])
     s.add_dependency(%q<rack>, [">= 0"])
     s.add_dependency(%q<rack-cache>, [">= 0"])
-    s.add_dependency(%q<mime-types>, [">= 0"])
     s.add_dependency(%q<rmagick>, [">= 0"])
   end
 end

data/dragonfly.gemspec

@@ -5,20 +5,21 @@
 
 Gem::Specification.new do |s|
   s.name = %q{dragonfly}
-  s.version = "0.1.6"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Evans"]
-  s.date = %q{2009-11-18}
+  s.date = %q{2009-12-11}
   s.email = %q{mark@new-bamboo.co.uk}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.markdown"
+     "README.md"
   ]
   s.files = [
     ".gitignore",
+     ".yardopts",
      "LICENSE",
-     "README.markdown",
+     "README.md",
      "Rakefile",
      "VERSION",
      "config.rb",
@@ -26,14 +27,21 @@ Gem::Specification.new do |s|
      "docs.watchr",
      "dragonfly-rails.gemspec",
      "dragonfly.gemspec",
-     "features/dragonfly.feature",
+     "extra_docs/ActiveRecord.md",
+     "extra_docs/Analysers.md",
+     "extra_docs/DataStorage.md",
+     "extra_docs/Encoding.md",
+     "extra_docs/GettingStarted.md",
+     "extra_docs/Processing.md",
+     "extra_docs/Shortcuts.md",
+     "extra_docs/UsingWithRails.md",
+     "features/images.feature",
+     "features/no_processing.feature",
      "features/steps/common_steps.rb",
      "features/steps/dragonfly_steps.rb",
      "features/support/env.rb",
-     "features/support/image_helpers.rb",
      "generators/dragonfly_app/USAGE",
      "generators/dragonfly_app/dragonfly_app_generator.rb",
-     "generators/dragonfly_app/templates/custom_processing.erb",
      "generators/dragonfly_app/templates/initializer.erb",
      "generators/dragonfly_app/templates/metal_file.erb",
      "irbrc.rb",
@@ -43,7 +51,6 @@ Gem::Specification.new do |s|
      "lib/dragonfly/active_record_extensions/class_methods.rb",
      "lib/dragonfly/active_record_extensions/instance_methods.rb",
      "lib/dragonfly/active_record_extensions/validations.rb",
-     "lib/dragonfly/analysis/analyser.rb",
      "lib/dragonfly/analysis/base.rb",
      "lib/dragonfly/analysis/file_command_analyser.rb",
      "lib/dragonfly/analysis/r_magick_analyser.rb",
@@ -55,6 +62,8 @@ Gem::Specification.new do |s|
      "lib/dragonfly/data_storage/base64_data_store.rb",
      "lib/dragonfly/data_storage/file_data_store.rb",
      "lib/dragonfly/data_storage/transparent_data_store.rb",
+     "lib/dragonfly/delegatable.rb",
+     "lib/dragonfly/delegator.rb",
      "lib/dragonfly/encoding/base.rb",
      "lib/dragonfly/encoding/r_magick_encoder.rb",
      "lib/dragonfly/encoding/transparent_encoder.rb",
@@ -62,7 +71,7 @@ Gem::Specification.new do |s|
      "lib/dragonfly/middleware.rb",
      "lib/dragonfly/middleware_with_cache.rb",
      "lib/dragonfly/parameters.rb",
-     "lib/dragonfly/processing/processor.rb",
+     "lib/dragonfly/processing/base.rb",
      "lib/dragonfly/processing/r_magick_processor.rb",
      "lib/dragonfly/r_magick_configuration.rb",
      "lib/dragonfly/rails/images.rb",
@@ -71,6 +80,7 @@ Gem::Specification.new do |s|
      "samples/beach.png",
      "samples/egg.png",
      "samples/round.gif",
+     "samples/sample.docx",
      "samples/taj.jpg",
      "spec/argument_matchers.rb",
      "spec/dragonfly/active_record_extensions/attachment_spec.rb",
@@ -79,12 +89,14 @@ Gem::Specification.new do |s|
      "spec/dragonfly/active_record_extensions/model_spec.rb",
      "spec/dragonfly/active_record_extensions/models.rb",
      "spec/dragonfly/active_record_extensions/spec_helper.rb",
-     "spec/dragonfly/analysis/analyser_spec.rb",
      "spec/dragonfly/analysis/r_magick_analyser_spec.rb",
      "spec/dragonfly/app_spec.rb",
      "spec/dragonfly/configurable_spec.rb",
      "spec/dragonfly/data_storage/data_store_spec.rb",
      "spec/dragonfly/data_storage/file_data_store_spec.rb",
+     "spec/dragonfly/delegatable_spec.rb",
+     "spec/dragonfly/delegator_spec.rb",
+     "spec/dragonfly/encoding/r_magick_encoder_spec.rb",
      "spec/dragonfly/extended_temp_object_spec.rb",
      "spec/dragonfly/middleware_spec.rb",
      "spec/dragonfly/middleware_with_cache_spec.rb",
@@ -96,8 +108,14 @@ Gem::Specification.new do |s|
      "spec/dragonfly_spec.rb",
      "spec/image_matchers.rb",
      "spec/simple_matchers.rb",
-     "spec/spec_helper.rb"
+     "spec/spec_helper.rb",
+     "yard/handlers/configurable_attr_handler.rb",
+     "yard/setup.rb",
+     "yard/templates/default/fulldoc/html/css/common.css",
+     "yard/templates/default/module/html/configuration_summary.erb",
+     "yard/templates/default/module/setup.rb"
   ]
+  s.has_rdoc = %q{yard}
   s.homepage = %q{http://github.com/markevans/dragonfly}
   s.rdoc_options = ["--charset=UTF-8"]
   s.require_paths = ["lib"]
@@ -111,12 +129,14 @@ Gem::Specification.new do |s|
      "spec/dragonfly/active_record_extensions/model_spec.rb",
      "spec/dragonfly/active_record_extensions/models.rb",
      "spec/dragonfly/active_record_extensions/spec_helper.rb",
-     "spec/dragonfly/analysis/analyser_spec.rb",
      "spec/dragonfly/analysis/r_magick_analyser_spec.rb",
      "spec/dragonfly/app_spec.rb",
      "spec/dragonfly/configurable_spec.rb",
      "spec/dragonfly/data_storage/data_store_spec.rb",
      "spec/dragonfly/data_storage/file_data_store_spec.rb",
+     "spec/dragonfly/delegatable_spec.rb",
+     "spec/dragonfly/delegator_spec.rb",
+     "spec/dragonfly/encoding/r_magick_encoder_spec.rb",
      "spec/dragonfly/extended_temp_object_spec.rb",
      "spec/dragonfly/middleware_spec.rb",
      "spec/dragonfly/middleware_with_cache_spec.rb",

data/extra_docs/ActiveRecord.md

@@ -0,0 +1,195 @@
+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]
+
+First extend activerecord
+
+    ActiveRecord::Base.extend Dragonfly::ActiveRecordExtensions
+
+Now register the app, giving the prefix for defining accessor methods (in this case 'image')
+
+    ActiveRecord::Base.register_dragonfly_app(:image, app)
+
+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... i.e. a tempfile holding the data
+    album.cover_image.file                           # alias for tempfile, above
+    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