netguru / paperclip-extended

Extension to Paperclip plugin for Ruby on Rails. It adds some possibly useful functionalities that original plugin lacks.

This URL has Read+Write access

paperclip-extended / README.rdoc
raw normal view history
8a4baa99 » netguru 2008-07-30 first commit 1 =PaperclipExtended
2
0d1034fe » netguru 2008-09-15 typo 3 PaperclipExtended extends Paperclip plugin by Jon Yurek and thoughtbot. It adds some possibly useful functionalities that original plugin lacks.
8a4baa99 » netguru 2008-07-30 first commit 4
5 Note that PaperclipExtended plugin is not a replacement for Paperclip. It requires that you have Paperclip plugin already installed.
6
7 PaperclipExtended is known to work with Paperclip 2.1.2 (current version at the time of development). Note that extensions provided by PaperclipExtended may be included in Paperclip in future, so this plugin will not be needed anymore.
8
1bb3dddf » netguru 2008-09-15 :normalized_basename interp... 9 ==Functionalities provided by PaperclipExtended
10
11 * Custom commands
12 Enables user to define additional options that will be passed to ImageMagick convert command after thumbnail generation by Paperclip.
13
14 * File name normalization
15 You can use :normalized_basename string in attachment's :path or :url definition, which is later interpolated. It works just like :basename, but it is normalized by substituting unusual characters with underscores.
16
919ae567 » netguru 2008-10-24 Now can upload to different... 17 * Multiple S3 buckets
18 Enables you to upload attachments to different S3 buckets. Modern web browsers are limited to download 2-4 files from one host at the same time, so placing your files in 4 different buckets (hosts) will let browsers download 8-16 files simultaneously.
19
8a4baa99 » netguru 2008-07-30 first commit 20 ==Usage
21
1bb3dddf » netguru 2008-09-15 :normalized_basename interp... 22 ===Custom commands
23
8a4baa99 » netguru 2008-07-30 first commit 24 In your model:
25
26 class User < ActiveRecord::Base
27 has_attached_file :avatar, :styles => { :medium => "300x300>", :thumb => "100x100>" }, :commands => { :medium => "-background white -gravity center -extent 300x300 +repage" }
28 end
29
30 The string you pass in commands hash will be attached to convert command after usual thumbnail generation by Paperclip.
31
32 The result convert command will be now:
33 convert -scale "300x300>" -background white -gravity center -extent 300x300 +repage
34
35 Instead of just:
36 convert -scale "300x300>"
37
38 The commands parameter is optional, also you can define it only for certain styles as above.
39
40 Read ImageMagick Command Line Options documentation for information on what can be put in commands parameter (http://www.imagemagick.org/script/command-line-options.php).
41
1bb3dddf » netguru 2008-09-15 :normalized_basename interp... 42 ===File name normalization
43
44 In your model:
45
46 class User < ActiveRecord::Base
47 has_attached_file :avatar,
48 :styles => { :thumb => "80x80#" },
49 :path => "#{RAILS_ROOT}/public/avatars/:id/:normalized_basename_:style.:extension",
50 :url => "/avatars/:id/:normalized_basename_:style.:extension"
51 end
52
0d1034fe » netguru 2008-09-15 typo 53 :normalized_basename works just like :basename, the only difference is that file's basename is normalized by substituting unusual chars with underscores. By "unusual characters" are those that are not matched by /[A-Za-z0-9_-]/ regular expression. For example if "my avatar.jpg" file is uploaded it's normalized basename would be "my_avatar.jpg". Such normalization may be useful in situations where you normally would url_encode the filename or something like that.
1bb3dddf » netguru 2008-09-15 :normalized_basename interp... 54
919ae567 » netguru 2008-10-24 Now can upload to different... 55 ===Multiple S3 buckets
56
57 Modern web browsers are limited to download 2-4 files from one host at the same time, so placing your files in 4 different buckets (hosts) will let browsers download 8-16 files simultaneously.
58
59 In your model:
60 class User < ActiveRecord::Base
61 has_attached_file :avatar,
62 :storage => :s3,
63 :s3_credentials => "#{RAILS_ROOT}/config/s3.yml",
64 :path => "avatars/:id/:style_:extension",
65 :bucket => lambda do |attachment|
66 i = attachment.instance.id % 4
67 "bucket_#{i}"
68 end
69 end
70
71 This will place each avatar in one of four buckets: bucket_0, bucket_1, bucket_2 or bucket_3. The exact bucket is chosen at runtime and in this case it's based on models id.
72
73 Getting attachment's path:
74 puts User.find(1).avatar.url(:original)
75 # => http://bucket_1.s3.amazonaws.com/avatars/1/original.jpg
1bb3dddf » netguru 2008-09-15 :normalized_basename interp... 76
919ae567 » netguru 2008-10-24 Now can upload to different... 77 If your attachments are images and you display many of them on the same page, now you should see them loading much faster.
1bb3dddf » netguru 2008-09-15 :normalized_basename interp... 78
8fe9f7ce » netguru 2008-07-30 copyrights update 79 Copyright (c) 2008 Michal Szajbe (http://codetunes.com) and netguru (http://netguru.pl), released under the MIT license