dragonfly 0.9.15 → 1.0

data/extra_docs/Encoding.md

@@ -1,67 +0,0 @@
-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/ExampleUseCases.md

@@ -1,116 +0,0 @@
-Example Use Cases
-=================
-Below are a number of examples of uses for Dragonfly which differ slightly from the standard image resizing with model attachments.
-
-Non-image attachments in Rails
-------------------------------
-When using `'dragonfly/rails'images'` or similar configuration, if you're not calling `thumb`, `width`
-or other image-related methods on your content, then non-image attachments should _just work_.
-
-    class User
-      image_accessor :mugshot
-    end
-
-    user.mugshot = Rails.root.join('some/text_file.txt')
-    user.save!
-    user.mugshot.url   # /media/BAsfsdfajkl....
-
-Furthermore, the imagemagick configuration gives you an `image?` analyser method which always returns a boolean
-so you can still make a thumbnail if it is an image
-
-    user.mugshot.thumb!('400x300#') if user.mugshot.image?
-
-`'dragonfly/rails/images'` also gives you a `file_accessor` macro which is actually just the same as `image_accessor`,
-but a bit more meaningful when not dealing with images
-
-    class User
-      file_accessor :mugshot
-    end
-
-You can always define your own macro for dealing with non-image attachments:
-
-    Dragonfly[:my_app].define_macro(ActiveRecord::Base, :attachment_accessor)
-
-    class User
-      attachment_accessor :mugshot
-    end
-
-see {file:Models} for how to define macros with non-ActiveRecord libraries.
-
-Quick custom image processing in Rails
---------------------------------------
-With the imagemagick configuration, we can easily use `convert` to do some custom processing, e.g. in the view:
-
-    <%= image_tag @user.mugshot.thumb('300x300#').convert('-blur 4x2').url %>
-
-If we use this a lot, we can define a shortcut for it - in config/initializers/dragonfly.rb:
-
-    Dragonfly[:images].configure do |c|
-      c.job :blurred_square do |size|
-        process :resize_and_crop, :width => size, :height => size
-        process :convert, '-blur 4x2'
-      end
-    end
-
-then in the view:
-
-    <%= image_tag @user.mugshot.blurred_square(300).url %>
-
-See {file:ImageMagick} for more info.
-
-Using Javascript to generate on-the-fly thumbnails in Rails
------------------------------------------------------------
-Supposing we have a `Pancake` model with an image attachment
-
-    pancake = Pancake.create! :image => Pathname.new('path/to/pancake.png')
-
-Setting the attachment sets the uid field (this example uses the {file:DataStorage#File\_datastore FileDataStore})
-
-    pancake.image_uid    # '2011/04/27/17_04_32_705_pancake.png'
-
-We can set up a Dragonfly endpoint in routes.rb for generating thumbnails:
-
-    match '/thumbs/:geometry' => app.endpoint { |params, app|
-      app.fetch(params[:uid]).thumb(params[:geometry])
-    }
-
-NOTE: if you use `do`...`end` here instead of curly braces, make sure you put brackets around the arguments to `match`,
-otherwise Ruby will parse it incorrectly
-
-If we have access to the image uid in javascript, we can create the url like so:
-
-    var url = '/thumbs/400x300?uid=' + uid
-
-Then we can get the content with ajax, create an img tag, etc.
-
-NOTE: in the above example we've put the uid in the query string and not the path because the dot in it confuses Rails' pattern recognition.
-You could always put it in the path and escape/unescape it either side of the request.
-
-Also javascript's built-in `encodeURIComponent` function may be useful when Rails has difficulty matching routes due to special characters like '#' and '/'.
-
-Text generation with Sinatra
-----------------------------
-We can easily generate on-the-fly text with Sinatra and the {Dragonfly::ImageMagick::Generator ImageMagick Generator}:
-
-    require 'rubygems'
-    require 'sinatra'
-    require 'dragonfly'
-
-    app = Dragonfly[:images].configure_with(:imagemagick)
-
-    get '/:text' do |text|
-      app.generate(:text, text, :font_size => 30).to_response(env)
-    end
-
-When we visit '/hello!' we get a generated image of the text "hello!".
-
-See {file:ImageMagick#Generator} for more details.
-
-Creating a Dragonfly plugin
----------------------------
-You can create custom {file:DataStorage#Custom\_datastore data stores}, {file:Processing#Custom\_Processors processors},
-{file:Encoding#Custom\_Encoders encoders}, {file:Analysers#Custom\_Analysers analysers} and {file:Generators#Custom\_Generators generators}, and
-then tie them all together with a {file:Configuration#Custom\_Saved\_Configuration saved configuration}.
-
-See [Dragonfly-RMagick](http://github.com/markevans/dragonfly-rmagick) for an example.
-NOTE: you will probably want to create classes and modules in your own namespace, rather than the `Dragonfly` namespace (even though Dragonfly-RMagick uses it).

data/extra_docs/GeneralUsage.md

@@ -1,105 +0,0 @@
-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
---------------------------
-A number of 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.fetch_url('somewhere.com/img.png')  # Fetch from a url (will work with http, https)
-
-    app.generate(:plasma, 400, 300)         # Generates using a method from the configured
-                                            # generator (in this case a plasma image)
-
-    app.create("CONTENT")                   # Can pass in a String, Pathname, File or Tempfile
-
-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..."
-                                         # this won't work if we've used create to get the content
-
-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`, `fetch_url`, `generate`, `create`, `process` and `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

data/extra_docs/Generators.md

@@ -1,68 +0,0 @@
-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.
-
-ImageMagick Generator
----------------------
-See {file:ImageMagick}.
-
-Custom Generators
------------------
-To register a single custom generator:
-
-    app.generator.add :triangle do |height|
-      SomeLibrary.create_triangle(height)     # return a String, Pathname, File or Tempfile
-    end
-
-    app.generate(:triangle, 10)      # => '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')
-
-You can also return meta data like name and format if you return an array from the generator
-
-    app.generator.add :triangle do |height|
-      [
-        SomeLibrary.create_triangle(height),
-        {:name => 'triangle.png', :format => :png}
-      ]
-    end

data/extra_docs/Heroku.md

@@ -1,50 +0,0 @@
-Heroku
-======
-
-The default configuration won't work out of the box for Heroku, because the platform doesn't allow saving files to the filesystem (although it does use tempfiles).
-
-Instead of the normal {file:DataStorage#File\_datastore FileDataStore}, we can use the {file:DataStorage#S3\_datastore S3DataStore}.
-
-Assuming you have an S3 account set up...
-
-Gem dependencies:
-
-    - fog
-    - dragonfly
-
-Initializer (e.g. config/initializers/dragonfly.rb in Rails):
-
-    require 'dragonfly'
-    app = Dragonfly[:images]
-
-    app.configure_with(:imagemagick)
-    app.configure_with(:rails)
-    if Rails.env.production?
-      app.configure do |c|
-        c.datastore = Dragonfly::DataStorage::S3DataStore.new(
-          :bucket_name => 'my-bucket-name',
-          :access_key_id => ENV['S3_KEY'],
-          :secret_access_key => ENV['S3_SECRET']
-        )
-      end
-    end
-
-    app.define_macro(ActiveRecord::Base, :image_accessor)
-
-The datastore remains as the {Dragonfly::DataStorage::FileDataStore FileDataStore} for non-production environments.
-
-application.rb if using with Rails:
-
-    config.middleware.insert 1, '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:
-
-    heroku config:add S3_KEY=XXXXXXXXX S3_SECRET=XXXXXXXXXX
-
-Replace 'XXXXXXXXX' with your access key and secret.
-
-If this is an issue, you may want to look into storing thumbnails on S3 (see {file:ServingRemotely}), or maybe generating thumbnails _on upload_ (see {file:Models#Up-front_thumbnailing}), 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.

data/extra_docs/ImageMagick.md

@@ -1,136 +0,0 @@
-ImageMagick
-===========
-Either `require 'dragonfly/rails/images'` or `Dragonfly[:images].configure_with(:imagemagick)`
-gives us an ImageMagick {Dragonfly::ImageMagick::Processor Processor}, {Dragonfly::ImageMagick::Encoder Encoder},
-{Dragonfly::ImageMagick::Analyser Analyser} and {Dragonfly::ImageMagick::Generator Generator}.
-
-Given a {Dragonfly::Job Job} object
-
-    image = app.fetch('some/uid')
-
-...OR a Dragonfly model accessor...
-
-    image = @album.cover_image
-
-we have the following:
-
-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.strip                       # same as image.process(:strip)
-    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.
-Bang methods like `image.thumb!('40x30')`, `image.png!` etc. will operate on `self`.
-
-Below are some examples of geometry strings for `thumb`:
-
-    '400x300'            # resize, maintain aspect ratio
-    '400x300!'           # force resize, don't maintain aspect ratio
-    '400x'               # resize width, maintain aspect ratio
-    'x300'               # resize height, maintain aspect ratio
-    '400x300>'           # resize only if the image is larger than this
-    '400x300<'           # resize only if the image is smaller than this
-    '50x50%'             # resize width and height to 50%
-    '400x300^'           # resize width, height to minimum 400,300, maintain aspect ratio
-    '2000@'              # resize so max area in pixels is 2000
-    '400x300#'           # resize, crop if necessary to maintain aspect ratio (centre gravity)
-    '400x300#ne'         # as above, north-east gravity
-    '400x300se'          # crop, with south-east gravity
-    '400x300+50+100'     # crop from the point 50,100 with width, height 400,300
-
-Processor
----------
-
-    image.process(:crop, :width => 40, :height => 50, :x => 20, :y => 30)
-    image.process(:crop, :width => 40, :height => 50, :gravity => 'ne')
-
-    image.process(:flip)                         # flips it vertically
-    image.process(:flop)                         # flips it horizontally
-
-    image.process(:greyscale, :depth => 128)     # default depth 256
-
-    image.process(:resize, '40x40')
-    image.process(:resize_and_crop, :width => 40, :height=> 50, :gravity => 'ne')
-
-    image.process(:rotate, 45, :background_colour => 'transparent')   # default bg black
-
-The method `thumb` takes a geometry string and calls `resize`, `resize_and_crop` or `crop` accordingly.
-
-    image.process(:thumb, '400x300')             # calls resize
-
-Encoder
--------
-The {Dragonfly::ImageMagick::Encoder ImageMagick Encoder} gives us:
-
-    image.encode(:jpg)
-    image.encode(:gif)
-    image.encode(:png)
-    image.encode(:tiff)
-
-and various other formats (see {Dragonfly::ImageMagick::Encoder ImageMagick Encoder}).
-
-You can also pass additional options to the imagemagick command line:
-
-    image.encode(:jpg, '-quality 10')
-
-Analyser
---------
-The {Dragonfly::ImageMagick::Analyser ImageMagick Analyser} gives us these methods:
-
-    image.width               # => 280
-    image.height              # => 355
-    image.aspect_ratio        # => 0.788732394366197
-    image.portrait?           # => true
-    image.landscape?          # => false
-    image.depth               # => 8
-    image.number_of_colours   # => 34703
-    image.format              # => :png
-    image.image?              # => true - will return true or false for any content
-
-Generator
----------
-The {Dragonfly::ImageMagick::Generator ImageMagick Generator} gives us these methods:
-
-    image = app.generate(:plain, 600, 400, 'rgba(40,200,30,0.5)')
-    image = app.generate(:plain, 600, 400, '#ccc', :format => :gif)
-                                                        # generate a 600x400 plain image
-                                                        # any css-style colour should work
-
-    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 text generation 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 the imagemagick docs}), which could be a complete filename.
-Available fonts are those available on your system.
-
-Configuration
--------------
-There are some options that can be set, e.g. if the imagemagick convert command can't be found:
-
-    app.configure do |c|
-      c.convert_command = "/opt/local/bin/convert"          # defaults to "convert"
-      c.identify_command = "/opt/local/bin/identify"        # defaults to "identify"
-      c.log_commands = true                                 # defaults to false
-    end