Skip to content
This repository
Newer
Older
100644 131 lines (76 sloc) 6.001 kb
23435784 » Keith Bingman
2009-04-29 added s3 configuration
1 Paperclipped
2 ---
3
4 Paperclip is a new file management plugin from Thoughtbot which has a few advantages over attachment_fu: it doesn't use RMagick, which uses a lot of RAM and is a bit of overkill for just making thumbnails. Instead it directly uses ImageMagick, making it much easier to install.
5
6 This version of paperclipped adds:
7
8 * error reports if inline file uploads fail (eg they exceed the file size limit)
9
10 ###Installation
11
12 To install paperclipped, just run
13
14 rake production db:migrate:extensions
15 rake production radiant:extensions:paperclipped:update
16
17 This runs the database migrations and installs the javascripts, images and css.
18
19 ###Configuration
20
21 If you install the Settings Extension (highly recommended), you can also easily adjust both the sizes of any additional thumbnails and which thumbnails are displayed in the image edit view. The default is the original file, but any image size can be used by giving in the name of that size.
22
23 If you do install the Settings Extension you should be sure to add a config.exetensions line to your environment.rb file:
24
25 config.extensions = [ :settings, :all ]
26
27 Also the Settings Extension migration should be run before Paperclipped's migration.
28
29 You also need the ImageSize gem required in `environment.rb`:
30
31 config.gem 'imagesize', :lib => 'image_size'
32
33 The configuration settings also enable a list of the allowed file types, maximum file size and should you need it, the path to your installation of Image Magick (this should not be needed, but I sometimes had a problem when using mod_rails).
34
35 ###Using Paperclipped
36
37 Once installed, you get a new Tab with the entire assets library, a Bucket à la Mephisto (though only the concept is stolen) and a search. You can also easily attach assets to any page and directly upload them to a page.
38
39 ###Asset Tags
40
41 There are a veriety of new tags. The basic tag is the <code><r:assets /></code> tag, which can be used either alone or as a double tag. This tag requires the "title" attribute, which references the asset. If you use the drag and drop from the asset bucket, this title will be added for you.
42
43 The <code><r:assets /></code> tag can be combined with other tags for a variety of uses:
44
45 <r:assets:image title="foo" /> will return <img src="/path/to/foo" alt="foo" />
46
47 <r:assets:link title="foo" /> will return <a href="/path/to/foo">foo</a>
48
49 You could also use:
50
51 <r:assets:link title="foo" text="This is the link to foo" /> will return <a href="/path/to/foo">This is the link to foo</a>
52
53 or
54
55 <r:assets:link title="foo">This is another link</r:link>
56
57 Asset links are also available, such as content_type, file_size, and url.
58
59 Another important tag is the <code><r:assets:each>...</r:assets:each></code>. If a page has attached assets, the assets:each tag will cycle through each asset. You can then use an image, link or url tag to display or connect your assets. Usage:
60
17ffece0 » Keith Bingman
2009-04-29 Updated Readme to include info about Amazon s3
61 <r:assets:each [limit=0] [offset=0] [order="asc|desc"] [by="position|title|..."] [extensions="png|pdf|doc"]>
62 ...
63 </r:assets:each>
23435784 » Keith Bingman
2009-04-29 added s3 configuration
64
65 `<r:assets:each>` parameters:
66
67 * `limit` and `offset` let you specify a range of assets;
68 * `order` and `by` lets you control sorting;
69 * `extensions` allows you to filter assets by file extensions; you can specify multiple extensions separated by `|`.
70
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
71 <code><pre>`<r:if_assets [min_count="0"]>` and `<r:unless_assets [min_count="0"]>`
72 </code></pre>
17ffece0 » Keith Bingman
2009-04-29 Updated Readme to include info about Amazon s3
73
74 conditional tags let you optionally render content based on the existance of tags. They accept the same options as `<r:assets:each>`.
23435784 » Keith Bingman
2009-04-29 added s3 configuration
75
76 Thumbnails are automatically generated for images when the images are uploaded. By default, two sizes are made for use within the extension itself. These are "icon" 42px by 42px and "thumbnail" which is fit into 100px, maintaining its aspect ratio.
77
78 You can access sizes of image assets for various versions with the tags `<r:assets:width [size="original"]/>` and `<r:assets:height [size="original"]/>`.
79
80 Also, for vertical centering of images, you have the handy `<r:assets:top_padding container="<container height>" [size="icon"]/>` tag. Working example:
81
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
82
23435784 » Keith Bingman
2009-04-29 added s3 configuration
83 <ul>
84 <r:assets:each>
85 <li style="height:140px">
86 <img style="padding-top:<r:top_padding size='category' container='140' />px"
87 src="<r:url />" alt="<r:title />" />
88 </li>
89 </r:assets:each>
90 </ul>
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
91
92
93 ###Using Amazon s3
94 Everything works as before, but now if you want to add S3 support, you simply set the storage setting to "s3".
95
96 <pre><code>Radiant::Config[assets.storage] = "s3"</code></pre>
97
98 Then add 3 new settings with your Amazon credentials, either in the console or with the [Settings](http://github.com/Squeegy/radiant-settings/tree/master) extension:
99
100 <pre><code>Radiant::Config[assets.s3.bucket] = "my_supercool_bucket"
101 Radiant::Config[assets.s3.key] = "123456"
102 Radiant::Config[assets.s3.secret] = "123456789ABCDEF"
103 </code></pre>
104
105 and finally the path you want to use within your bucket, which uses the same notation as the Paperclip plugin.
106
107 <pre><code>Radiant::Config[assets.s3.path] = :class/:id/:basename_:style.:extension
108 </code></pre>
109
110 The path setting, along with a new <code>url</code> setting can be used with the file system to customize both the path and url of your assets.
23435784 » Keith Bingman
2009-04-29 added s3 configuration
111
112 ###Migrating from the page_attachments extension
113
092483e2 » Keith Bingman
2009-04-29 minor change in the url_additions
114 If you're moving from page_attachments to paperclipped, here's how to migrate smoothly:
23435784 » Keith Bingman
2009-04-29 added s3 configuration
115
116 First, remove or disable the page_attachments extension, and install the paperclipped extension.
117 For example:
118
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
119 <pre><code>rake ray:dis name=page_attachments
120 rake ray:assets
121 </code></pre>
17ffece0 » Keith Bingman
2009-04-29 Updated Readme to include info about Amazon s3
122
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
123
23435784 » Keith Bingman
2009-04-29 added s3 configuration
124 The migration has now copied your original `page_attachments` table to `old_page_attachments`.
125
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
126 <pre><code>rake radiant:extensions:paperclipped:migrate_from_page_attachments
127 </code></pre>
23435784 » Keith Bingman
2009-04-29 added s3 configuration
128
129 This rake task will create paperclipped-style attachments for all `OldPageAttachments`. It will also ask you if you want to clean up the old table and thumbnails in `/public/page_attachments`.
130
cd2c1dc1 »
2009-05-12 cleaning up model, starting to move js out of views
131 Done!
Something went wrong with that request. Please try again.