classiccms 0.2.4.pre → 0.3.0

data/vendor/bundle/gems/dragonfly-0.9.12/extra_docs/DataStorage.md

@@ -0,0 +1,226 @@
+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:
+
+    # Can pass in a String, Pathname, File or Tempfile
+    uid = app.store('SOME CONTENT')
+
+We can also save metadata at the same time, and any other options the configured datastore accepts
+
+    uid = app.store('SOME CONTENT',
+      :meta => {:time => Time.now, :name => 'content.txt'},
+      :some => 'option'
+    )
+
+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, :name => 'content.txt'}
+    content.name         # 'content.txt'
+
+We can destroy it with
+
+    app.destroy(uid)
+
+Serving directly from the datastore
+-----------------------------------
+Datastores can optionally serve data directly too, by implementing `url_for`
+
+    app.datastore.url_for(uid, :some => 'option')   # ---> "http://some.url/thing.txt"
+
+or (the same)
+
+    app.remote_url_for(uid, :some => 'option')
+
+or
+
+    my_model.attachment.remote_url(:some => 'option')
+
+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 = '/filesystem/path/public/place'   # defaults to /var/tmp/dragonfly
+      d.server_root = '/filesystem/path/public'       # filesystem root for serving from - default to nil
+      d.store_meta = false                            # default to true - can be switched off to avoid
+                                                      #  saving an extra .meta file if meta not needed
+    end
+
+You can serve directly from the FileDataStore if the `server_root` is set.
+
+To customize the storage path (and therefore the uid), use the `:path` option on store
+
+    app.store("SOME CONTENT", :path => 'some/path.txt')
+
+To do this on a per-model basis see {file:Models#Storage_options}.
+
+**BEWARE!!!!** you must make sure the path (which will become the uid for the content) is unique and changes each time the content
+is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
+
+S3 datastore
+------------
+To configure with the {Dragonfly::DataStorage::S3DataStore S3DataStore}:
+
+    app.datastore = Dragonfly::DataStorage::S3DataStore.new
+
+    app.datastore.configure do |c|
+      c.bucket_name = 'my_bucket'
+      c.access_key_id = 'salfjasd34u23'
+      c.secret_access_key = '8u2u3rhkhfo23...'
+      c.region = 'eu-west-1'                        # defaults to 'us-east-1'
+      c.storage_headers = {'some' => 'thing'}       # defaults to {'x-amz-acl' => 'public-read'}
+      c.url_scheme = 'https'                        # defaults to 'http'
+      c.url_host = 'some.custom.host'               # defaults to "<bucket_name>.s3.amazonaws.com"
+    end
+
+You can also pass these options to `S3DataStore.new` as an options hash.
+
+You can serve directly from the S3DataStore using e.g.
+
+    my_model.attachment.remote_url
+
+or with an expiring url:
+
+    my_model.attachment.remote_url(:expires => 3.days.from_now)
+
+or with an https url:
+
+    my_model.attachment.remote_url(:scheme => 'https')   # also configurable for all urls with 'url_scheme'
+
+or with a custom host:
+
+    my_model.attachment.remote_url(:host => 'custom.domain')   # also configurable for all urls with 'url_host'
+
+Extra options you can use on store are `:path` and `:headers`
+
+    app.store("SOME CONTENT", :path => 'some/path.txt', :headers => {'x-amz-acl' => 'public-read-write'})
+
+To do this on a per-model basis see {file:Models#Storage_options}.
+
+**BEWARE!!!!** you must make sure the path (which will become the uid for the content) is unique and changes each time the content
+is changed, otherwise you could have caching problems, as the generated urls will be the same for the same uid.
+
+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
+      c.connection_opts = {:name => 'prod'}             # arg gets passed to Mongo::Connection
+                                                        #  or Mongo::ReplSetConnection initializer - see http://api.mongodb.org/ruby/current
+      
+      c.hosts = ['localhost:30000', 'localhost:30001']  # will use Mongo::ReplSetConnection instead of Mongo::Connection
+    end
+
+If you already have a mongo database or connection available, you can skip setting these and set `db` or `connection` instead.
+
+You can also pass any options to `MongoDataStore.new` as an options hash.
+
+You can't serve directly from the mongo datastore.
+
+You can optionally pass in a `:content_type` option to `store` to tell it the content's MIME type.
+
+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.
+
+You can serve directly from the couch datastore.
+
+You can optionally pass in a `:content_type` option to `store` to tell it what to use for its 'Content-Type' header.
+
+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.
+        # ... also we can use temp_object.meta and store it ...
+        
+        # store and return the uid
+        'return_some_unique_uid'
+      end
+
+      def retrieve(uid)
+        # return an array containing
+        [
+          content,          # either a File, String or Tempfile
+          meta_data         # Hash - :name and :format are treated specially,
+        ]                   #  e.g. job.name is taken from job.meta[:name]
+      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, get passed here.
+`:meta` is treated specially and is accessible inside `MyDataStore#store` as `temp_object.meta`
+
+    uid = app.store('SOME CONTENT',
+      :meta => {:name => 'great_content.txt'},
+      :some_other => :option
+    )
+
+    # ...
+
+You can also optionally serve data directly from the datastore if it implements `url_for`:
+
+    class MyDataStore
+
+      # ...
+
+      def url_for(uid, opts={})
+        "http://some.domain/#{uid}"
+      end
+
+    end

data/vendor/bundle/gems/dragonfly-0.9.12/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/vendor/bundle/gems/dragonfly-0.9.12/extra_docs/ExampleUseCases.md

@@ -0,0 +1,116 @@
+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/vendor/bundle/gems/dragonfly-0.9.12/extra_docs/GeneralUsage.md

@@ -0,0 +1,105 @@
+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/vendor/bundle/gems/dragonfly-0.9.12/extra_docs/Generators.md

@@ -0,0 +1,68 @@
+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/vendor/bundle/gems/dragonfly-0.9.12/extra_docs/Heroku.md

@@ -0,0 +1,57 @@
+Heroku
+======
+
+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)
+- If on Heroku {http://devcenter.heroku.com/articles/stack Aspen/Bamboo stacks}, we won't need {http://tomayko.com/src/rack-cache/ Rack::Cache},
+because it already uses the caching proxy {http://varnish.projects.linpro.no/ Varnish}, which we can make use of.
+We will still need it on {http://devcenter.heroku.com/articles/cedar Heroku Cedar}, however, as it doesn't include Varnish.
+
+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.
+
+**NOTE**: HEROKU'S VARNISH CACHE IS CLEARED EVERY TIME YOU DEPLOY!!! (DOESN'T APPLY TO CEDAR STACK)
+
+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.