README.rdoc in papermill-0.14.3 vs README.rdoc in papermill-0.16.0
- old
+ new
@@ -1,126 +1,172 @@
= Papermill
-Asset management made easy.
+Asset management made easy. Now in pre-1.0.0 release!
-== Install the gem
+== Install the gems
- $ gem source -a http://gemcutter.org # Needed for paperclip (installed as a dependency) : Rubyforge's version is too old..
+ $ gem source -a http://gemcutter.org
$ sudo gem install papermill
== Try the demo
$ sudo gem install sqlite3-ruby
$ rails -m http://github.com/bbenezech/papermill/raw/master/installation-template.txt papermill-example
- $ cd papermill-example
- $ ./script/server
- Open localhost:3000 in your browser and try to create an article with assets but without title
-
+
+== Features
+
+Loads of them
+
+=== Ajax uploading form helpers through SWFUpload:
+
+* image_upload => unique image upload field, with preview
+* images_upload => sortable image gallery upload field
+* asset_upload => simple one asset field
+* assets_upload => sortable asset list field
+
+=== 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
+
+* :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.
+* and use them when you need them : my_asset.url(:big_alias)
+
== Papermill comes in 2 flavors:
=== Generic catch-all declaration
- papermill my_option_hash # in your papermilled assetable model
- assets_upload(:my_key, my_option_hash) # form helper call
- f.input :my_key, :as => :assets_upload, my_option_hash # if you are using formtastic
- @assetable.assets(:my_key) # data access in your view
+ papermill {options} # in your papermilled assetable model
+ @article.assets(:any_key, options_hash) # data access
=== Association specific declaration
- papermill :my_association, my_option_hash # in your papermilled assetable model
- assets_upload(:my_association, my_option_hash) # form helper call
- @assetable.my_association # data access in your view
+ papermill :my_association, options_hash # in your papermilled assetable model
+ @article.my_association # data access
+== Usage:
-In both case, you can specify a PapermillAsset subclass to use with :class_name => MyPapermillAssetSubclass in the option hash.
+=== Model declaration
-You can have a catch-all declaration and as many specific association as you want in your model (as long as they use different keys).
+You can have a generic association and as many declarative associations as you want in your model. Papermill will always use specific if found.
-It's up to you. You can use the first one only, the second only or both.
+article.rb
+ class Article < ActiveRecord::Base
+ papermill :class_name => ColorAsset, other_options..
+ end
-See papermill_module.rb for the complete list of options.
+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
+
+=== Resources access
+
+With generic papermill association, Papermill generates an #assets(:key, *args) named_scope
+ @article.assets(:illustrations)
+ @article.assets(:illustrations, :order => "created_at DESC")
+ @article.illustrations.red.first
+ @article.assets(:illustrations, :order => "created_at DESC").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.all(:conditions => { :assetable_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 in your environment.rb
+ @asset.name
+ @asset.content_type
+ @asset.path # original
+ @asset.path("100x>")
+ # etc.
+
== Installation
-=== Once you've installed the gem, generate a migration and copy a couple of static assets:
+=== Once gem is installed :
- # Generate the migration and migrate:
+ # Generate migration :
$ ./script/generate papermill_table PapermillMigration
$ rake db:migrate
- # copy some needed static assets to your public directory:
+ # 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
-
- # You can set application-wide options inside or before Rails::Initializer :
- module Papermill
- OPTIONS = {
- :thumbnail => {
- :width => 150,
- :height => 100
- },
- :aliases => {
- :big => "500x500>",
- :small => "100x100>"
- },
- :public_root => ":rails_root/public", # already a default
- :papermill_prefix => "system/papermill" # already a default
- }
- end
- # see lib/papermill/papermill_module.rb
-
- # You can use stringex's String#to_url (papermill will use its own String#to_url if none exists)
- config.gem 'stringex'
- ...
- # You can use Mime-Type to get the correct mime type from upload - flash garbles it.. (default is a UNIX call to "file --mime")
- # needed for Windows OS
+ # Needed for Windows OS (mime type from file extension):
config.gem "mime-types", :lib => "mime/types"
end
-
-=== In your assetable model:
-
- # You can set a catch-all papermill association :
- papermill :class_name => MyAssetClass
-
- # or create an association for the specific :my_gallery key
- papermill :my_gallery_assets, :class_name => MyGalleryAsset
=== In your layout:
<%= papermill_stylesheet_tag %>
<%= papermill_javascript_tag :with_jquery => "no_conflict" %>
- # you won't need :with_jquery if you have it already.
-
-=== In your edit form:
-
- f.images_upload(:my_gallery) # use specific papermill :my_gallery declaration
- f.assets_upload(:my_assets) # use catch-all
- f.asset_upload(:my_other_asset) # use catch-all
-
-=== Access them with:
-
- @assetable.my_gallery_assets.each{ |image| image_tag image.url("100x100") }
- # equivalent to:
- @assetable.assets(:my_gallery_assets).each{ |image| image_tag image.url("100x100") }
- # also equivalent to:
- @assetable.assets(:conditions => {:assetable_key => 'my_gallery_assets'}).each{ |image| image_tag image.url("100x100") }
-
- @assetable.assets(:my_assets).each{ |asset| asset.url }
- # if your association name is singularizable, you can do smtg like :
- @assetable.asset(:my_other_asset).try(:url)
- # equivalent to:
- @assetable.assets(:my_other_asset).first.try(:url)
-
- # You can change assets/asset with :base_association_name in Papermill::OPTIONS (choose a plural word and you'll get singular association for free)
-
-Also see http://github.com/bbenezech/papermill/raw/master/installation-template.txt
-Have a look at the API here http://rdoc.info/projects/bbenezech/papermill
+ # 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.
\ No newline at end of file