oahu-dragonfly 0.8.2

data/extra_docs/Configuration.md

@@ -0,0 +1,124 @@
+Configuration
+=============
+
+Given a Dragonfly app
+
+    app = Dragonfly[:app_name]
+
+Configuration can either be done like so...
+
+    app.configure do |c|
+      c.url_path_prefix = '/media'
+      # ...
+    end
+
+...or directly like so...
+
+    app.url_path_prefix = '/media'
+
+The defaults should be fairly sensible, but you can tweak a number of things if you wish.
+Here is an example of an app with all attributes configured:
+
+    app.configure do |c|
+      c.datastore = SomeCustomDataStore.new :egg => 'head'  # defaults to FileDataStore
+
+      c.cache_duration = 3600*24*365*2                      # defaults to 1 year # (1 year)
+      c.fallback_mime_type = 'something/mental'             # defaults to application/octet-stream
+      c.log = Logger.new($stdout)                           # defaults to Logger.new('/var/tmp/dragonfly.log')
+      c.trust_file_extensions = false                       # defaults to true
+
+      c.url_path_prefix = '/images'                         # defaults to nil
+      c.url_host = 'http://some.domain.com:4000'            # defaults to nil
+      c.url_suffix = '.jpg'                                 # defaults to nil - has no effect other than change the url
+
+      c.content_filename = proc{|job, request|              # defaults to the original name, with modified ext if encoded
+        "file.#{job.ext}"
+      }
+      c.content_disposition = :attachment                   # defaults to nil (use the browser default)
+
+      c.protect_from_dos_attacks = true                     # defaults to false - adds a SHA parameter on the end of urls
+      c.secret = 'This is my secret yeh!!'                  # should set this if concerned about DOS attacks
+
+      c.analyser.register(MyAnalyser)                       # See 'Analysers' for more details
+      c.processor.register(MyProcessor, :type => :fig)      # See 'Processing' for more details
+      c.encoder.register(MyEncoder) do |e|                  # See 'Encoding' for more details
+        e.some_value = 'geg'
+      end
+      c.generator.register(MyGenerator)                     # See 'Generators' for more details
+
+      c.register_mime_type(:egg, 'fried/egg')               # See 'MimeTypes' for more details
+
+      c.job :black_and_white do |size|                      # Job shortcut - lets you do image.black_and_white('30x30')
+        process :greyscale
+        process :thumb, size
+        encode  :gif
+      end
+    end
+
+Where is configuration done?
+----------------------------
+In Rails, it should be done in an initializer, e.g. 'config/initializers/dragonfly.rb'.
+Otherwise it should be done anywhere where general setup is done, early on.
+
+Saved configurations
+====================
+Saved configurations are useful if you often configure the app the same way.
+There are a number that are provided with Dragonfly:
+
+ImageMagick
+-----------
+
+    app.configure_with(:imagemagick)
+
+The {Dragonfly::ImageMagick::Config ImageMagick configuration} registers the app with the {Dragonfly::ImageMagick::Analyser ImageMagick Analyser}, {Dragonfly::ImageMagick::Processor ImageMagick Processor},
+{Dragonfly::ImageMagick::Encoder ImageMagick Encoder} and {Dragonfly::ImageMagick::Generator ImageMagick Generator}, and adds the 'job shortcuts'
+`thumb`, `jpg`, `png`, `gif` and `convert`.
+
+The file 'dragonfly/rails/images' does this for you.
+
+The processor, analyser, encoder and generator pass data around using tempfiles.
+
+Rails
+-----
+
+    app.configure_with(:rails)
+
+The {Dragonfly::Config::Rails Rails configuration} points the log to the Rails logger, configures the file data store root path, sets the url_path_prefix to /media, and
+registers the {Dragonfly::Analysis::FileCommandAnalyser FileCommandAnalyser} for helping with mime_type validations.
+
+The file 'dragonfly/rails/images' does this for you.
+
+Heroku
+------
+
+    app.configure_with(:heroku, 's3_bucket_name')
+
+The {Dragonfly::Config::Heroku Heroku configuration} configures it to use the {Dragonfly::DataStorage::S3DataStore}, using Heroku's config attributes.
+See {file:Heroku} for more info.
+
+Custom Saved Configuration
+--------------------------
+You can create your own saved configuration with any object that responds to 'apply_configuration':
+
+    module MyConfiguration
+
+      def self.apply_configuration(app, *args)
+        app.configure do |c|
+          c.url_path_prefix = '/hello/beans'
+          c.processor.register(MyProcessor)
+          # ...
+        end
+      end
+
+    end
+
+Then to configure:
+
+    app.configure_with(MyConfiguration, :any_other => :args)     # other args get passed through to apply_configuration
+
+You can also carry on configuring by passing a block
+
+    app.configure_with(MyConfiguration) do |c|
+      c.any_extra = :config_here
+      # ...
+    end

data/extra_docs/Couch.md

@@ -0,0 +1,49 @@
+CouchDB
+=====
+Dragonfly can be used with any ActiveModel-compatible model, and so you can use it with CouchDB using [CouchRest::Model](https://github.com/couchrest/couchrest_model).
+
+Since CouchDB allows you to store files directly on documents as attachments, you can also use the supplied {Dragonfly::DataStorage::CouchDataStore CouchDataStore}.
+which allows storing files as attachments directly on documents.
+
+For more info about ActiveModel, see {file:Models}.
+
+For more info about using the Couch data store, see {file:DataStorage}.
+
+Example setup in Rails, using CouchRest::Model
+-------------------------------------
+In config/initializers/dragonfly.rb:
+
+    require 'dragonfly'
+
+    app = Dragonfly[:images]
+
+    # Get database config from config/couchdb.yml
+    couch_settings = YAML.load_file(Rails.root.join('config/couchdb.yml'))[Rails.env]
+
+    # Configure to use ImageMagick, Rails defaults, and the Couch data store
+    app.configure_with(:imagemagick)
+    app.configure_with(:rails) do |c|
+      c.datastore = Dragonfly::DataStorage::CouchDataStore.new(
+        :host => couch_settings['host'],
+        :port => couch_settings['port'],
+        :username => couch_settings['username'],
+        :password => couch_settings['password'],
+        :database => couch_settings['database']
+      )
+    end
+
+    # Allow all CouchRest::Model models to use the macro 'image_accessor'
+    app.define_macro(CouchRest::Model::Base, :image_accessor)
+
+    # ... any other setup, see Rails docs
+
+Then in models:
+
+    class Album < CouchRest::Model::Base
+      property :cover_image_uid
+      image_accessor :cover_image
+
+      # ...
+    end
+
+See {file:Models} for more info.

data/extra_docs/DataStorage.md

@@ -0,0 +1,153 @@
+Data Storage
+============
+
+Each dragonfly app has a key-value datastore to store the content (originals only).
+
+Lets say we have an app
+
+    app = Dragonfly[:my_app_name]
+
+Then we can store data like so:
+
+    uid = app.store('SOME CONTENT')       # Can pass in a String, File or Tempfile
+
+We can also save metadata at the same time, and give it a name and format (if you pass in a File object the filename is used by default)
+
+    uid = app.store('SOME CONTENT',
+      :meta => {:time => Time.now},
+      :name => 'great_content.txt',
+      :format => :txt
+    )
+
+We can get content with
+
+    content = app.fetch(uid)
+    content.data         # "SOME CONTENT"
+
+We can also get the extra saved attributes
+
+    content.meta         # {:time => Sat Aug 14 12:04:13 +0100 2010}
+    content.name         # 'great_content.txt'
+    content.format       # :txt
+
+We can destroy it with
+
+    app.destroy(uid)
+
+You can create your own datastore, or use one of the provided ones as outlined below.
+
+File datastore
+--------------
+The {Dragonfly::DataStorage::FileDataStore FileDataStore} stores data on the local filesystem.
+
+It is used by default.
+
+If for whatever reason you need to configure it again:
+
+    # shouldn't need this - it is the default
+    app.datastore = Dragonfly::DataStorage::FileDataStore.new
+
+    app.datastore.configure do |d|
+      d.root_path = '/my/custom/path'              # defaults to /var/tmp/dragonfly
+    end
+
+
+S3 datastore
+------------
+To configure with the {Dragonfly::DataStorage::S3DataStore S3DataStore}:
+
+    app.datastore = Dragonfly::DataStorage::S3DataStore.new
+
+    app.datastore.configure do |d|
+      c.bucket_name = 'my_bucket'
+      c.access_key_id = 'salfjasd34u23'
+      c.secret_access_key = '8u2u3rhkhfo23...'
+    end
+
+You can also pass these options to `S3DataStore.new` as an options hash.
+
+
+Mongo datastore
+---------------
+To configure with the {Dragonfly::DataStorage::MongoDataStore MongoDataStore}:
+
+    app.datastore = Dragonfly::DataStorage::MongoDataStore.new
+
+It won't normally need configuring, but if you wish to:
+
+    app.datastore.configure do |d|
+      c.host = 'http://egg.heads:5000'                # defaults to localhost
+      c.port = '27018'                                # defaults to mongo default (27017)
+      c.database = 'my_database'                      # defaults to 'dragonfly'
+      c.username = 'some_user'                        # only needed if mongo is running in auth mode
+      c.password = 'some_password'                    # only needed if mongo is running in auth mode
+    end
+
+You can also pass these options to `MongoDataStore.new` as an options hash.
+
+Couch datastore
+---------------
+To configure with the {Dragonfly::DataStorage::CouchDataStore CouchDataStore}:
+
+    app.datastore = Dragonfly::DataStorage::CouchDataStore.new
+
+To configure:
+
+    app.datastore.configure do |d|
+      c.host = 'localhost'                            # defaults to localhost
+      c.port = '5984'                                 # defaults to couchdb default (5984)
+      c.database = 'dragonfly'                        # defaults to 'dragonfly'
+      c.username = ''                                 # not needed if couchdb is in 'admin party' mode
+      c.password = ''                                 # not needed if couchdb is in 'admin party' mode
+    end
+
+You can also pass these options to `CouchDataStore.new` as an options hash.
+
+Custom datastore
+----------------
+Data stores are key-value in nature, and need to implement 3 methods: `store`, `retrieve` and `destroy`.
+
+    class MyDataStore
+
+      def store(temp_object, opts={})
+        # ... use temp_object.data, temp_object.file, temp_object.path, etc. ...
+        # store and return the uid
+        'return_some_unique_uid'
+      end
+
+      def retrieve(uid)
+        # return an array containing
+        [
+          content,            # either a File, String or Tempfile
+          extra_data          # Hash with optional keys :meta, :name, :format
+        ]
+      end
+
+      def destroy(uid)
+        # find the content and destroy
+      end
+
+    end
+
+You can now configure the app to use your datastore:
+
+    Dragonfly[:my_app_name].datastore = MyDataStore.new
+
+Notice that `store` takes a second `opts` argument.
+Any options other than `meta`, `name` and `format` get passed through to here, so calling
+
+    uid = app.store('SOME CONTENT',
+      :name => 'great_content.txt',
+      :some_other => :option
+    )
+
+will be split inside `store` like so:
+
+    def store(temp_object, opts={})
+      temp_object.data             # "SOME CONTENT"
+      temp_object.name             # 'great_content.txt'
+      opts                         # {:some_other => :option}
+      # ...
+    end
+
+    # ...

data/extra_docs/Encoding.md

@@ -0,0 +1,67 @@
+Encoding
+========
+Registered encoders change the format of data, e.g. a jpeg image to a png image.
+
+You can register as many encoders as you like.
+
+Let's say we have a Dragonfly app
+
+    app = Dragonfly[:images]
+
+and an image object (actually a {Dragonfly::Job Job} object)...
+
+    image = app.fetch('some/uid')
+
+...OR a Dragonfly model accessor...
+
+    image = @album.cover_image
+
+We can encode it to any format registered with the encoder.
+
+Lazy evaluation
+---------------
+
+    gif_image = image.encode(:gif)
+
+doesn't actually do anything until you call something on the returned {Dragonfly::Job Job} object, like `url`, `data`, etc.
+
+Bang method
+-----------
+
+    image.encode!(:gif)
+
+modifies the image object itself, rather than returning a new object.
+
+ImageMagick Encoder
+-------------------
+See {file:ImageMagick}.
+
+Custom Encoders
+---------------
+
+To register a custom encoder, for e.g. pdf format:
+
+    app.encoder.add do |temp_object, format|
+      throw :unable_to_handle unless format == :pdf
+      # use temp_object.data, temp_object.path, temp_object.file, etc.
+      SomeLibrary.convert_to_pdf(temp_object.data)
+      # return a String, Pathname, File or Tempfile
+    end
+
+    pdf_image = image.encode(:pdf)
+
+If `:unable_to_handle` is thrown, the next most recently registered encoder is used, and so on.
+
+Alternatively you can create a class like the ImageMagick one above, which implements the method `encode`, and register this.
+
+    class MyEncoder
+
+      def encode(temp_object, format, *args)
+        SomeLib.encode(temp_object.data, format, *args)
+      end
+
+    end
+
+    app.encoder.register(MyEncoder)
+
+    pdf_image = image.encode(:pdf, :some => :args)

data/extra_docs/GeneralUsage.md

@@ -0,0 +1,121 @@
+General Usage
+=============
+
+You can have multiple dragonfly apps, each with their own configuration.
+Each app has a name, and is referred to by that name.
+
+    Dragonfly[:images]    # ===> Creates an app called 'images'
+    Dragonfly[:images]    # ===> Refers to the already created app 'images'
+
+    app = Dragonfly[:images]
+
+Getting/generating content
+--------------------------
+Three 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.generate(:plasma, 400, 300)         # Generates using a method from the configured
+                                            # generator (in this case a plasma image)
+
+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.
+
+Using the content
+-----------------
+Once we have a {Dragonfly::Job Job} object:
+
+    image = app.fetch('some_uid')
+
+We can get the data a number of ways...
+
+    image.data                           # => "\377???JFIF\000\..."
+    image.to_file('out.png')             # writes to file 'out.png' and returns a readable file object
+    image.tempfile                       # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a closed Tempfile object
+    image.file                           # => #<File:/var/folders/st/strHv74sH044JPabSiODz... a readable (open) File object
+    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
+    image.path                           # => '/var/folders/st/strHv74sH044JPabSiODz...' i.e. the path of the tempfile
+    image.size                           # => 134507 (size in bytes)
+
+We can get its url...
+
+    image.url                            # => "/media/BAhbBlsHOgZmIg9hc..."
+
+We can analyse it (see {file:Analysers} for more info) ...
+
+    image.width                          # => 280
+
+We can process it (see {file:Processing} for more info) ...
+
+    new_image = image.process(:thumb, '40x30')    # returns another 'Job' object
+
+We can encode it (see {file:Encoding} for more info) ...
+
+    new_image = image.encode(:gif)                # returns another 'Job' object
+
+Chaining
+--------
+Because the methods
+
+  - `fetch`
+
+  - `fetch_file`
+
+  - `generate`
+
+  - `process`
+
+  - `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)
+
+... and because they're lazy, we don't actually do any processing/encoding until either `apply` is called
+
+    image.apply              # actually 'does' the processing and returns self
+
+... or a method is called like `data`, `to_file`, etc.
+
+This means we can cheaply generate urls for processed data without doing any fetching or processing:
+
+    url = app.fetch('some_uid').process(:thumb, '40x20#').encode(:gif).url
+
+and then visit that url in a browser to get the actual processed image.
+
+Shortcuts
+---------
+Commonly used processing/encoding steps can be shortened, so instead of
+
+    app.fetch('some_uid').process(:greyscale).process(:thumb, '40x20#').encode(:jpg)
+
+we could use something like
+
+    app.fetch('some_uid').grey('40x20#')
+
+This does exactly the same, returning a {Dragonfly::Job Job} object.
+
+To define this shortcut:
+
+    app.configure do |c|
+      c.job :grey do |size|
+        process :greyscale
+        process :thumb, size
+        encode :jpg
+      end
+      # ...
+    end
+
+The {Dragonfly::ImageMagick::Config 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.