= Papermill 



* Asset management made easy, 10 minutes integration.
* All-you-can-eat glue around Polymorphic Paperclip table, SWFUpload & JQuery. 
* Associate any image or list of images with any model and any key. 

== Install the gem
  
  sudo gem install papermill
 
== Try the demo
  
  rails -m http://github.com/bbenezech/papermill/raw/master/demo.txt papermill-example

=== Out-of-the-box compatibility with : 

* Formtastic          # use :as => :[image|asset](s)_upload
* JGrowl              # for notifications (included)
* FaceBox             # for popups (included)
* Stringex            # (or any String#to_url) for asset filename/url generation

=== Navigator minimal requirements: 

* IE6+
* Flash 9+
* Javascript ON

Check your audience.

=== Server requirements:

* Makes internal use of JQuery (but loaded in compatibility mode by default, compatible with Prototype/whatever... JRails not needed.)
* Rails 2.3.4 min (rail's I18n, engine. older 2.3.x have issues with CRSF or try to check for CRSF stamp against AJAX request, useless with AJAX same origin policy, fixed with 2.3.4)
* Paperclip 2.3 branch (installed by default as a gem dependency, will be loaded internally if needed => You can require your own version of Paperclip if you want to)
* Front web server serving static assets if present, and forwarding demand to rails if not. (Usually a no-brainer on any classic installation. Works with Webrick)
 
== Features

=== Ajax uploading form helpers through SWFUpload => [image|asset](s)_upload

See the demo to get an idea: 

* image_upload => one image, with thumbnail preview
* images_upload => sortable image thumbnail gallery
* asset_upload => one asset
* assets_upload => sortable asset list

=== Asset edit form: 

* double-click on any asset in any helper to access & edit his properties

=== Lazy created thumbnails

* thumbnails are generated the first time they are asked-for, and only in the requested size. 
* no need to register thumbnail size anywhere: my_asset.url("100x100>")
* .. but you can use application-wide aliases, see below : 

=== Alias handling, declaration application-wide (in config/initializers/papermill.rb, do a ./script/generate papermill_initializer)

* :big_alias => {:geometry => "1000x>"}
* :other_alias => "100x>"
* :third_alias => {:geometry => '100:122', :my_other_keys => 'blblabla'}  # if you have a customed Paperclip::Thumbnail processor, you can pass any values you need.
* Use them when you need them : my_asset.url(:big_alias)

=== Model declaration

You can have a generic association and as many declarative associations as you want in your model. Papermill will always use specific if found.

article.rb

  class Article < ActiveRecord::Base
    papermill :class_name => ColorAsset, other_options..
  end

entry.rb

  class Entry < ActiveRecord::Base
    papermill :mug_shot, other_options..
    papermill :diaporama, :class_name => ColorAsset, other_options..
  end

color_asset.rb  # You should add columns to papermill_assets and use STI on PapermillAsset to extend defaults capabilities (or re-open PapermillAsset and monkey-patch it, or use a polymorphic association)

  class ColorAsset < PapermillAsset
    named_scope :red, :conditions => {:color => 'red'}
  end

=== Form helpers

FormHelpers

  form_for @article do 
    f.image_upload  :cover_image, options_hash
    f.images_upload :illustrations, options_hash
    f.asset_upload  :pdf, options_hash
    f.image_upload  :other_resources, options_hash
  end
  
Or with formtastic :

  semantic_form_for @article do |f|
    f.input @article, :cover_image, options_hash, :as => :image_upload
    f.input @article, :illustrations, options_hash, :as => :images_upload
    f.input @article, :pdf, options_hash, :as => :asset_upload
    f.input @article, :other_resources, options_hash, :as => :image_upload
  end

FormTagHelpers

  image_upload_tag  @article, :cover_image, options_hash
  images_upload_tag @article, :illustrations, options_hash
  asset_upload_tag  @article, :pdf, options_hash
  image_upload_tag  @article, :other_resources, options_hash

For resources not linked to any assetable model :
  image_upload_tag "#{current_organization.name}_logo", options_hash

=== Resource access

Papermill generates an #assets(:key, *args) named_scope
  @article.assets(:illustrations)
  @article.assets(:illustrations, :order => "created_at DESC")
  @article.assets(:illustrations).red.first
  # etc.

With declarative papermill associations, Papermill also generates an #<association_key>(*args) named_scope
  @entry.mug_shot.first
  @entry.diaporama
  @entry.diaporama(:order => "created_at DESC")
  @entry.diaporama.red
  # === @entry.diaporama(:conditions => {:color => "red"}) 
  # === @entry.assets(:diaporama, :conditions => {:color => "red"})
  # etc.

Or for non-assetable resources : 
  PapermillAsset.key("#{current_organization.name}_logo").first
  ColorAsset.all.red

=== Using PapermillAsset

  @asset = @entry.mug_shot.first
  image_tag @asset.url              # original
  image_tag @asset.url("100x>")     # assuming asset is an image
  image_tag @asset.url(:big)        # assuming you have a :big alias
  @asset.name
  @asset.content_type
  @asset.path
  @asset.path("100x>")
  # etc.

== Installation

=== Once gem is installed :

Generate the migration :
  ./script/generate papermill_table PapermillMigration

Edit its fields and migrate :
  rake db:migrate

Copy static assets to your public directory:
  ./script/generate papermill_assets
  
Create the option file config/initializers/papermill.rb
  ./script/generate papermill_initializer

=== environment.rb:

  ...
  Rails::Initializer.run do |config|
    ...
    config.gem papermill
    config.gem "mime-types", :lib => "mime/types"  # required for windows OS
  end

=== In your layout:

  <%= papermill_stylesheet_tag %>
  <%= papermill_javascript_tag :with_jquery => "no_conflict" %>
  # you don't need :with_jquery if you already had it loaded.

=== Translations:

Papermill is fully I18n-able, except for javascript error messages. (coming)
Copy config/locales/papermill.yml to your root config/locale folder to modify any wording in a any locale.
  
Copyright (c) 2009 Benoit Bénézech, released under the MIT license
  
http://rubyonrails.org/images/rails.png