= 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. 

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

Formtastic          # use :as => :[image|asset](s)_upload
JGrowl              # instead of alert for notifications
FaceBox/Shadowbox   # instead of a pop_up for edit form
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 (rail's I18n, engine)
Paperclip 2.3 branch (installed by default as a gem dependency, will be loaded internally if needed)
Windows environnement :
  # Mime/Types library. Ex:
  config.gem "mime-types", :lib => "mime/types"
 
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)

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

== Features

Loads of them

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

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

=== Choose thumbnail size for images previews : 

* {:thumbnail => {:width => 100, :height => 100}}
* {:thumbnail => {:style => "100x100>"}}
* {:thumbnail => {:width => 100, :aspect_ratio => 4.0/3.0 }}

=== Asset edit form: 

* double-click on any asset in any helper to access&edit his properties
* with pop-up/shadowbox/facebox, out of the box (or use your own pop-up system, dead-easy)

=== 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>")

=== Alias handling, declaration application-wide (in config/initializers/papermill.rb, after you 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)

== Papermill comes in 2 flavors:

=== Generic catch-all declaration

  papermill options_hash                                # in your papermilled assetable model
  @article.assets(:any_key, options_hash)               # data access

=== Association specific declaration

  papermill :my_association, options_hash               # in your papermilled assetable model
  @article.my_association                               # data access

== Usage:

=== 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.. # default class_name is built-in PapermillAsset
    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..)
  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_ressources, 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_ressources, 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_ressources, options_hash
  # For resources not linked to any assetable model :
  image_upload_tag #{current_organization.name}_logo
  
=== Resource access

With generic papermill association, 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 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"}) 
  # 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>")
  image_tag @asset.url(:big)        # assuming you have a :big alias
  @asset.name
  @asset.content_type
  @asset.path                       # original
  @asset.path("100x>")
  # etc.
  
== Installation

=== Once gem is installed :

  # Generate migration :
  $ ./script/generate papermill_table PapermillMigration
  $ rake db:migrate
  # copy static assets to your public directory:
  $ ./script/generate papermill_assets
  # create the option hash in config/initializers/papermill.rb
  $ ./script/generate papermill_initializer
  
=== Then in environment.rb:
  
  ...
  Rails::Initializer.run do |config|
    ...
    config.gem papermill
    config.gem "mime-types", :lib => "mime/types"  # required for windows only
  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.
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