= 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 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.4 (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)
* 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)


=== Windows environnement :

  # Mime/Types library. Ex:
  config.gem "mime-types", :lib => "mime/types"
 
== 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)

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

  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 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>")
  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 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 hash in config/initializers/papermill.rb
  ./script/generate papermill_initializer

Then see config/initializers/papermill.rb for the option hash.

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