dragonfly 0.4.1 → 0.4.2

data/.yardopts

@@ -9,4 +9,5 @@ extra_docs/Shortcuts.md
 extra_docs/Analysers.md
 extra_docs/Processing.md
 extra_docs/Encoding.md
+extra_docs/ExampleUseCases.md
 LICENSE

data/VERSION

@@ -1 +1 @@
-0.4.1
+0.4.2

data/dragonfly.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{dragonfly}
-  s.version = "0.4.1"
+  s.version = "0.4.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Mark Evans"]
-  s.date = %q{2010-01-07}
+  s.date = %q{2010-01-10}
   s.email = %q{mark@new-bamboo.co.uk}
   s.extra_rdoc_files = [
     "LICENSE",

data/extra_docs/ExampleUseCases.md

@@ -1,17 +1,196 @@
 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.
+
+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)
+- 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'.
+
+Assuming we don't bother with any caching for development/testing environments, our environment.rb then has:
+
+    config.gem 'rmagick', :lib => 'RMagick'
+    config.gem 'dragonfly', :source => "http://www.gemcutter.org"
+
+(these are ignored by Heroku but you might want them locally)
+
+The gems file for Heroku, `.gems`, has
+
+    dragonfly
+
+(rmagick not needed because it is already installed)
+
+Then in our configuration initializer, we replace
+
+    c.datastore.configure do |d|
+      d.root_path = "#{Rails.root}/public/system/dragonfly/#{Rails.env}"
+    end
+
+with
+
+    # 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
+
+We've left the datastore as {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).
+
+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!
+
+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.
+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.
+Let's generate a configuration for a Dragonfly App called 'attachments'
 
-Rails thumbnails on Heroku with S3
-----------------------------------
+    ./script/generate dragonfly_app attachments
+
+This generates an initializer for configuring the Dragonfly App 'attachments'.
+
+We won't be using RMagick or Rack::Cache (as there is no processing), so our environment.rb only has:
+
+    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
+    end
+    c.register_analyser(Dragonfly::Analysis::FileCommandAnalyser)
+    c.register_encoder(Dragonfly::Encoding::TransparentEncoder)
+
+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).
+
+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 %>
 
-Serving attachments with no processing
---------------------------------------
 
 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 Rails helper files/generators)
+
+    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.
+
+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.
+
+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
+    end
+
+We need the {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} for mime-type analysis.
+
+Then when we visit a url like
+
+    url = Dragonfly::App[:text].url_for('some text', :processing_options => {: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.
+

data/extra_docs/Index.md

@@ -19,6 +19,7 @@ Use the links at the top-right to navigate around the code, or jump straight to
 - {file:Processing.md Processing}
 - {file:Encoding.md Encoding}
 - {file:Shortcuts.md Shortcuts for processing and encoding}
+- {file:ExampleUseCases.md Example use cases}
 
 Installation
 ------------

data/extra_docs/UsingWithRails.md

@@ -82,3 +82,6 @@ but make sure to change the 'secret' configuration option, so as to protect your
     #   :metastore   => "file:#{Rails.root}/tmp/dragonfly/cache/meta",
     #   :entitystore => "file:#{Rails.root}/tmp/dragonfly/cache/body"
     # }
+
+
+To see what you can do with the active record accessors, see {file:ActiveRecord}.

data/lib/dragonfly/extended_temp_object.rb

@@ -1,4 +1,25 @@
 module Dragonfly
+  
+  # An ExtendedTempObject is just a TempObject that belongs to a Dragonfly App.
+  # 
+  # Because of this, it can make use of the app's registered processors, encoders and analysers
+  #
+  # Analysis methods can be accessed on the object itself, e.g. for a registered analysis method 'width', we have
+  #   temp_object.width    # ===> 280
+  #
+  # Processing methods can be accessed using 'process', e.g. for a registered process method 'resize', we have
+  #   temp_object.process(:resize, {:some => 'option'})    # ===> processed ExtendedTempObject
+  #
+  # Similarly, encoding with the method 'encode' delegates to the app's registered encoders
+  #   temp_object.encode(:png, {:some => 'option'})    # ===> encoded ExtendedTempObject
+  #
+  # We can use bang methods to operate on the temp_object itself, rather than return a new one:
+  #   temp_object.process!(:resize, {:some => 'option'})
+  #   temp_object.encode!(:png, {:some => 'option'})
+  #
+  # You can make use of the app's registered parameter shortcuts (for processing and encoding in one go) using 'transform', e.g.
+  #   temp_object.transform('300x200', :gif)       # ===> return a new processed and encoded ExtendedTempObject
+  #   temp_object.transform!('300x200', :gif)      # ===> operate on self
   class ExtendedTempObject < TempObject
     
     # Exceptions

data/lib/dragonfly/parameters.rb

@@ -52,8 +52,8 @@ module Dragonfly
       end
       
       def from_args(*args)
-        if args.empty? then new
-        elsif args.length == 1 && args.first.is_a?(Hash) then new(args.first)
+        if args.empty? then new_with_defaults
+        elsif args.length == 1 && args.first.is_a?(Hash) then new_with_defaults(args.first)
         elsif args.length == 1 && args.first.is_a?(Parameters) then args.first.dup
         else from_shortcut(*args)
         end

data/lib/dragonfly/temp_object.rb

@@ -1,6 +1,32 @@
 require 'tempfile'
 
 module Dragonfly
+
+  # A TempObject is used for HOLDING DATA.
+  # It's the thing that is passed between the datastore, the processor and the encoder, and is useful
+  # for separating how the data was created and how it is later accessed.
+  #
+  # You can initialize it various ways:
+  #
+  #   temp_object = Dragonfly::TempObject.new('this is the content')           # with a String
+  #   temp_object = Dragonfly::TempObject.new(File.new('path/to/content'))     # with a File
+  #   temp_object = Dragonfly::TempObject.new(some_tempfile)                   # with a Tempfile
+  #   temp_object = Dragonfly::TempObject.new(some_other_temp_object)          # with another TempObject
+  #
+  # However, no matter how it was initialized, you can always access the data a number of ways:
+  #
+  #   temp_object.data      # returns a data string
+  #   temp_object.file      # returns a file object holding the data
+  #   temp_object.path      # returns a path for the file
+  #
+  # The data/file are created lazily, something which you may wish to take advantage of.
+  #
+  # For example, if a TempObject is initialized with a file, and temp_object.data is never called, then
+  # the data string will never be loaded into memory.
+  #
+  # Conversely, if the TempObject is initialized with a data string, and neither temp_object.file nor temp_object.path
+  # are ever called, then the filesystem will never be hit.
+  #
   class TempObject
   
     # Class configuration

data/spec/dragonfly/parameters_spec.rb

@@ -231,13 +231,13 @@ describe Dragonfly::Parameters do
       @parameters_class.default_format = :tif
     end
     
-    it "should be the same as 'new' if empty args" do
-      @parameters_class.from_args.should == @parameters_class.new
+    it "should be the same as 'new_with_defaults' if empty args" do
+      @parameters_class.from_args.should == @parameters_class.new_with_defaults
     end
     
-    it "should treat the arguments as actual parameter values if args is a single hash" do
+    it "should treat the arguments as actual parameter values (including defaults) if args is a single hash" do
       @parameters_class.from_args(:uid => 'some_uid', :processing_method => :resize).
-        should == @parameters_class.new(:uid => 'some_uid', :processing_method => :resize)
+        should == @parameters_class.new_with_defaults(:uid => 'some_uid', :processing_method => :resize)
     end
 
     it "should simply return the same parameters if args is a single parameters object" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: dragonfly
 version: !ruby/object:Gem::Version 
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors: 
 - Mark Evans
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-07 00:00:00 +00:00
+date: 2010-01-10 00:00:00 +00:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency