fog-dragonfly 0.8.1

data/extra_docs/DataStorage.md

@@ -0,0 +1,136 @@
+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.
+
+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. ...
+        # ... can also make use of temp_object.name, temp_object.format, temp_object.meta
+        # 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,96 @@
+Encoding
+========
+
+Changing the format of data, but not changing the data itself,
+e.g. converting to gif format, comes under the banner of Encoding.
+
+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.
+
+ImageMagickEncoder
+------------------
+The {Dragonfly::Encoding::ImageMagickEncoder ImageMagickEncoder} is registered by default by
+the {Dragonfly::Config::ImageMagick ImageMagick configuration} used by 'dragonfly/rails/images'.
+
+If not already registered:
+
+    app.encoder.register(Dragonfly::Encoding::ImageMagickEncoder)
+
+gives us:
+
+    image.encode(:jpg)
+    image.encode(:gif)
+    image.encode(:png)
+    image.encode(:tiff)
+
+and various other formats (see {Dragonfly::Encoding::ImageMagickEncoder ImageMagickEncoder}).
+
+You can also pass additional options to the imagemagick command line:
+
+    image.encode(:jpg, '-quality 10')
+
+RMagickEncoder
+--------------
+The {Dragonfly::Encoding::RMagickEncoder RMagickEncoder} uses the {http://rmagick.rubyforge.org RMagick} library to do similar things to the
+ImageMagickEncoder above.
+
+You can tell it not to use the file system when registering it using
+
+    app.encoder.register(Dragonfly::Encoding::RMagickEncoder){|e| e.use_filesystem = false }
+
+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.
+
+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, 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::Config::ImageMagick 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.

data/extra_docs/Generators.md

@@ -0,0 +1,102 @@
+Generators
+==========
+
+Unlike processors and encoders, generators create content out of nothing, rather than modifying already existing content, for example text image generation.
+
+You can register as many generators as you like.
+
+Given a Dragonfly app
+
+    app = Dragonfly[:images]
+
+we can get generated content using
+
+    image = app.generate(:some_method, :some => :args)
+
+where `:some_method` is added by the configured generators.
+
+ImageMagickGenerator
+--------------------
+The {Dragonfly::Generation::ImageMagickGenerator ImageMagickGenerator} is registered by default by the
+{Dragonfly::Config::ImageMagick ImageMagick configuration} used by 'dragonfly/rails/images'.
+
+If not already registered:
+
+    app.generator.register(Dragonfly::Generation::ImageMagickGenerator)
+
+gives us these methods:
+
+    image = app.generate(:plasma, 600, 400, :gif)       # generate a 600x400 plasma image
+                                                        # last arg defaults to :png
+
+    image = app.generate(:text, "Hello there")          # an image of the text "Hello there"
+
+    image = app.generate(:text, "Hello there",
+      :font_size => 30,                                 # defaults to 12
+      :font_family => 'Monaco',
+      :stroke_color => '#ddd',
+      :color => 'red',
+      :font_style => 'italic',
+      :font_stretch => 'expanded',
+      :font_weight => 'bold',
+      :padding => '30 20 10',
+      :background_color => '#efefef',                   # defaults to transparent
+      :format => :gif                                   # defaults to png
+    )
+
+Note that the options are meant to resemble css as much as possible. You can also use, for example, `'font-family'` instead of `:font_family`.
+
+You can use `padding-top`, `padding-left`, etc., as well as the standard css shortcuts for `padding` (it assumes unit is px).
+
+An alternative for `:font_family` is `:font` (see {http://www.imagemagick.org/script/command-line-options.php#font}), which could be a complete filename.
+Available fonts are those available on your system.
+
+RMagickGenerator
+----------------
+The {Dragonfly::Generation::RMagickGenerator RMagickGenerator} gives you `plasma` and `text` like the imagemagick generator above, using the
+{http://rmagick.rubyforge.org RMagick} library.
+
+You can tell it not to use the file system when registering it
+
+    app.generator.register(Dragonfly::Generation::RMagickGenerator){|g| g.use_filesystem = false }
+
+
+Custom Generators
+-----------------
+To register a single custom generator:
+
+    app.generator.add :blank_image do |colour|
+      SomeLibrary.create_blank_image(colour)     # return a String, File or Tempfile
+    end
+
+    app.generate(:blank_image, 'red')      # => 'Job' object which we can get data, etc.
+
+
+Or create a class like the ImageMagick one above, in which case all public methods will be counted as generator methods.
+
+    class RoundedCornerGenerator
+
+      def top_left_corner(opts={})
+        SomeLib.tlc(opts)
+      end
+
+      def bottom_right_corner(opts={})
+        tempfile = Tempfile.new('brc')
+        `some_command -c #{opts[:colour]} -o #{tempfile.path}`
+        tempfile
+      end
+
+      # ...
+
+      private
+
+      def my_helper_method
+        # do stuff
+      end
+
+    end
+
+    app.generator.register(RoundedCornerGenerator)
+
+    app.generate(:top_left_corner, :colour => 'green')
+    app.generate(:bottom_right_corner, :colour => 'mauve')