| 1 | <?xml version="1.0" encoding="iso-8859-1"?> |
|---|
| 2 | <!DOCTYPE html |
|---|
| 3 | PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
|---|
| 4 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
|---|
| 5 | |
|---|
| 6 | <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
|---|
| 7 | <head> |
|---|
| 8 | <title>Module: FileColumn::ClassMethods</title> |
|---|
| 9 | <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
|---|
| 10 | <meta http-equiv="Content-Script-Type" content="text/javascript" /> |
|---|
| 11 | <link rel="stylesheet" href="../.././rdoc-style.css" type="text/css" media="screen" /> |
|---|
| 12 | <script type="text/javascript"> |
|---|
| 13 | // <![CDATA[ |
|---|
| 14 | |
|---|
| 15 | function popupCode( url ) { |
|---|
| 16 | window.open(url, "Code", "resizable=yes,scrollbars=yes,toolbar=no,status=no,height=150,width=400") |
|---|
| 17 | } |
|---|
| 18 | |
|---|
| 19 | function toggleCode( id ) { |
|---|
| 20 | if ( document.getElementById ) |
|---|
| 21 | elem = document.getElementById( id ); |
|---|
| 22 | else if ( document.all ) |
|---|
| 23 | elem = eval( "document.all." + id ); |
|---|
| 24 | else |
|---|
| 25 | return false; |
|---|
| 26 | |
|---|
| 27 | elemStyle = elem.style; |
|---|
| 28 | |
|---|
| 29 | if ( elemStyle.display != "block" ) { |
|---|
| 30 | elemStyle.display = "block" |
|---|
| 31 | } else { |
|---|
| 32 | elemStyle.display = "none" |
|---|
| 33 | } |
|---|
| 34 | |
|---|
| 35 | return true; |
|---|
| 36 | } |
|---|
| 37 | |
|---|
| 38 | // Make codeblocks hidden by default |
|---|
| 39 | document.writeln( "<style type=\"text/css\">div.method-source-code { display: none }</style>" ) |
|---|
| 40 | |
|---|
| 41 | // ]]> |
|---|
| 42 | </script> |
|---|
| 43 | |
|---|
| 44 | </head> |
|---|
| 45 | <body> |
|---|
| 46 | |
|---|
| 47 | |
|---|
| 48 | |
|---|
| 49 | <div id="classHeader"> |
|---|
| 50 | <table class="header-table"> |
|---|
| 51 | <tr class="top-aligned-row"> |
|---|
| 52 | <td><strong>Module</strong></td> |
|---|
| 53 | <td class="class-name-in-header">FileColumn::ClassMethods</td> |
|---|
| 54 | </tr> |
|---|
| 55 | <tr class="top-aligned-row"> |
|---|
| 56 | <td><strong>In:</strong></td> |
|---|
| 57 | <td> |
|---|
| 58 | <a href="../../files/lib/file_column_rb.html"> |
|---|
| 59 | lib/file_column.rb |
|---|
| 60 | </a> |
|---|
| 61 | <br /> |
|---|
| 62 | </td> |
|---|
| 63 | </tr> |
|---|
| 64 | |
|---|
| 65 | </table> |
|---|
| 66 | </div> |
|---|
| 67 | <!-- banner header --> |
|---|
| 68 | |
|---|
| 69 | <div id="bodyContent"> |
|---|
| 70 | |
|---|
| 71 | |
|---|
| 72 | |
|---|
| 73 | <div id="contextContent"> |
|---|
| 74 | |
|---|
| 75 | <div id="description"> |
|---|
| 76 | <p> |
|---|
| 77 | The FileColumn module allows you to easily handle file uploads. You can |
|---|
| 78 | designate one or more columns of your model’s table as "file |
|---|
| 79 | columns" like this: |
|---|
| 80 | </p> |
|---|
| 81 | <pre> |
|---|
| 82 | class Entry < ActiveRecord::Base |
|---|
| 83 | |
|---|
| 84 | file_column :image |
|---|
| 85 | end |
|---|
| 86 | </pre> |
|---|
| 87 | <p> |
|---|
| 88 | Now, by default, an uploaded file "test.png" for an entry object |
|---|
| 89 | with primary key 42 will be stored in in |
|---|
| 90 | "public/entry/image/42/test.png". The filename |
|---|
| 91 | "test.png" will be stored in the record’s <tt>image</tt> |
|---|
| 92 | column. |
|---|
| 93 | </p> |
|---|
| 94 | <p> |
|---|
| 95 | The methods of this module are automatically included into |
|---|
| 96 | ActiveRecord::Base as class methods, so that you can use them in your |
|---|
| 97 | models. |
|---|
| 98 | </p> |
|---|
| 99 | <h2>Generated Methods</h2> |
|---|
| 100 | <p> |
|---|
| 101 | After calling "<tt><a href="ClassMethods.html#M000003">file_column</a> |
|---|
| 102 | :image</tt>" as in the example above, a number of instance methods |
|---|
| 103 | will automatically be generated, all prefixed by "image": |
|---|
| 104 | </p> |
|---|
| 105 | <ul> |
|---|
| 106 | <li><tt>Entry#image=(uploaded_file)</tt>: this will handle a newly uploaded |
|---|
| 107 | file (see below). Note that you can simply call your upload field |
|---|
| 108 | "entry[image]" in your view (or use the helper). |
|---|
| 109 | |
|---|
| 110 | </li> |
|---|
| 111 | <li><tt>Entry#image(suffix=nil)</tt>: This will return an absolute path (as a |
|---|
| 112 | string) to the currently uploaded file or nil if no file has been uploaded |
|---|
| 113 | |
|---|
| 114 | </li> |
|---|
| 115 | <li><tt>Entry#image_relative_path(suffix)</tt>: This will return a path |
|---|
| 116 | relative to this file column’s base directory as a string or nil if |
|---|
| 117 | no file has been uploaded. This would be "42/test.png" in the |
|---|
| 118 | example. |
|---|
| 119 | |
|---|
| 120 | </li> |
|---|
| 121 | <li><tt>Entry#image_just_uploaded?</tt>: Returns true if a new file has been |
|---|
| 122 | uploaded to this instance. You can use this in <tt>before_validation</tt> |
|---|
| 123 | to resize images on newly uploaded files, for example. |
|---|
| 124 | |
|---|
| 125 | </li> |
|---|
| 126 | </ul> |
|---|
| 127 | <p> |
|---|
| 128 | You can access the raw value of the "image" column (which will |
|---|
| 129 | contain the filename) via the <tt>ActiveRecord::Base#attributes</tt> or |
|---|
| 130 | <tt>ActiveRecord::Base#[]</tt> methods like this: |
|---|
| 131 | </p> |
|---|
| 132 | <pre> |
|---|
| 133 | entry['image'] # e.g."test.png" |
|---|
| 134 | </pre> |
|---|
| 135 | <h2>Storage of uploaded file</h2> |
|---|
| 136 | <p> |
|---|
| 137 | For a model class <tt>Entry</tt> and a column <tt>image</tt>, all files |
|---|
| 138 | will be stored under "public/entry/image". A sub-directory named |
|---|
| 139 | after the primary key of the object will be created, so that files can be |
|---|
| 140 | stored using their real filename. For example, a file "test.png" |
|---|
| 141 | stored in an Entry object with id 42 will be stored in |
|---|
| 142 | </p> |
|---|
| 143 | <pre> |
|---|
| 144 | public/entry/image/42/test.png |
|---|
| 145 | </pre> |
|---|
| 146 | <p> |
|---|
| 147 | Files will be moved to this location in an <tt>after_save</tt> callback. |
|---|
| 148 | They will be stored in a temporary location previously as explained in the |
|---|
| 149 | next section. |
|---|
| 150 | </p> |
|---|
| 151 | <h2>Handling of form redisplay</h2> |
|---|
| 152 | <p> |
|---|
| 153 | Suppose you have a form for creating a new object where the user can upload |
|---|
| 154 | an image. The form may have to be re-displayed because of validation |
|---|
| 155 | errors. The uploaded file has to be stored somewhere so that the user does |
|---|
| 156 | not have to upload it again. FileColumn will store these in a temporary |
|---|
| 157 | directory (called "tmp" and located under the column’s base |
|---|
| 158 | directory by default) so that it can be moved to the final location if the |
|---|
| 159 | object is successfully created. If the form is never completed, though, you |
|---|
| 160 | can easily remove all the images in this "tmp" directory once per |
|---|
| 161 | day or so. |
|---|
| 162 | </p> |
|---|
| 163 | <p> |
|---|
| 164 | So in the example above, the image "test.png" would first be |
|---|
| 165 | stored in |
|---|
| 166 | "public/entry/image/tmp/<some_random_key>/test.png" and be |
|---|
| 167 | moved to "public/entry/image/<primary_key>/test.png". |
|---|
| 168 | </p> |
|---|
| 169 | <p> |
|---|
| 170 | This temporary location of newly uploaded files has another advantage when |
|---|
| 171 | updating objects. If the update fails for some reasons (e.g. due to |
|---|
| 172 | validations), the existing image will not be overwritten, so it has a kind |
|---|
| 173 | of "transactional behaviour". |
|---|
| 174 | </p> |
|---|
| 175 | <h2>Suffixes</h2> |
|---|
| 176 | <p> |
|---|
| 177 | FileColumn allows you to keep more than one file in a directory and will |
|---|
| 178 | move/delete all the files it finds in a model object’s directory when |
|---|
| 179 | necessary. You can access these files via the optional suffix parameter |
|---|
| 180 | that some of the generated methods accept (see above). This suffix is |
|---|
| 181 | inserted into the filename before the extension, separated by a dash. |
|---|
| 182 | </p> |
|---|
| 183 | <p> |
|---|
| 184 | Suppose your uploaded file is named "vancouver.jpg" and you want |
|---|
| 185 | to create a thumb-nail and store it in the same directory. If you cal |
|---|
| 186 | <tt>image("thumb")</tt>, you will receive an absolute path for |
|---|
| 187 | the file "vancouver-thumb.jpg" in the same directory |
|---|
| 188 | "vancouver.jpg" is stored. Look at the documentation of <a |
|---|
| 189 | href="Magick.html">FileColumn::Magick</a> for more examples. |
|---|
| 190 | </p> |
|---|
| 191 | <h2>File Extensions</h2> |
|---|
| 192 | <p> |
|---|
| 193 | FileColumn will try to fix the file extension of uploaded files, so that |
|---|
| 194 | the files are served with the correct mime-type by your web-server. Most |
|---|
| 195 | web-servers are setting the mime-type based on the file’s extension. |
|---|
| 196 | You can disable this behaviour by passing the <tt>:fix_file_extensions</tt> |
|---|
| 197 | option with a value of <tt>nil</tt> to <tt><a |
|---|
| 198 | href="ClassMethods.html#M000003">file_column</a></tt>. |
|---|
| 199 | </p> |
|---|
| 200 | <p> |
|---|
| 201 | In order to set the correct extension, FileColumn tries to determine the |
|---|
| 202 | files mime-type first. It then uses the <tt>MIME_EXTENSIONS</tt> hash to |
|---|
| 203 | choose the corresponding file extension. You can override this hash by |
|---|
| 204 | passing in a <tt>:mime_extensions</tt> option to <tt><a |
|---|
| 205 | href="ClassMethods.html#M000003">file_column</a></tt>. |
|---|
| 206 | </p> |
|---|
| 207 | <p> |
|---|
| 208 | The mime-type of the uploaded file is determined with the following steps: |
|---|
| 209 | </p> |
|---|
| 210 | <ol> |
|---|
| 211 | <li>Run the external "file" utility. You can specify the full path to |
|---|
| 212 | the executable in the <tt>:file_exec</tt> option or set this option to |
|---|
| 213 | <tt>nil</tt> to disable this step |
|---|
| 214 | |
|---|
| 215 | </li> |
|---|
| 216 | <li>If the file utility couldn’t determine the mime-type or the utility |
|---|
| 217 | was not present, the content-type provided by the user’s browser is |
|---|
| 218 | used as a fallback. |
|---|
| 219 | |
|---|
| 220 | </li> |
|---|
| 221 | </ol> |
|---|
| 222 | |
|---|
| 223 | </div> |
|---|
| 224 | |
|---|
| 225 | |
|---|
| 226 | </div> |
|---|
| 227 | |
|---|
| 228 | <div id="method-list"> |
|---|
| 229 | <h3 class="section-bar">Methods</h3> |
|---|
| 230 | |
|---|
| 231 | <div class="name-list"> |
|---|
| 232 | <a href="#M000003">file_column</a> |
|---|
| 233 | </div> |
|---|
| 234 | </div> |
|---|
| 235 | |
|---|
| 236 | </div> |
|---|
| 237 | |
|---|
| 238 | |
|---|
| 239 | <!-- if includes --> |
|---|
| 240 | |
|---|
| 241 | <div id="section"> |
|---|
| 242 | |
|---|
| 243 | |
|---|
| 244 | <div id="constants-list"> |
|---|
| 245 | <h3 class="section-bar">Constants</h3> |
|---|
| 246 | |
|---|
| 247 | <div class="name-list"> |
|---|
| 248 | <table summary="Constants"> |
|---|
| 249 | <tr class="top-aligned-row context-row"> |
|---|
| 250 | <td class="context-item-name">MIME_EXTENSIONS</td> |
|---|
| 251 | <td>=</td> |
|---|
| 252 | <td class="context-item-value">{ "image/gif" => "gif", "image/jpeg" => "jpg", "image/pjpeg" => "jpg", "image/x-png" => "png", "image/jpg" => "jpg", "image/png" => "png", "application/x-shockwave-flash" => "swf", "application/pdf" => "pdf", "application/pgp-signature" => "sig", "application/futuresplash" => "spl", "application/msword" => "doc", "application/postscript" => "ps", "application/x-bittorrent" => "torrent", "application/x-dvi" => "dvi", "application/x-gzip" => "gz", "application/x-ns-proxy-autoconfig" => "pac", "application/x-shockwave-flash" => "swf", "application/x-tgz" => "tar.gz", "application/x-tar" => "tar", "application/zip" => "zip", "audio/mpeg" => "mp3", "audio/x-mpegurl" => "m3u", "audio/x-ms-wma" => "wma", "audio/x-ms-wax" => "wax", "audio/x-wav" => "wav", "image/x-xbitmap" => "xbm", "image/x-xpixmap" => "xpm", "image/x-xwindowdump" => "xwd", "text/css" => "css", "text/html" => "html", "text/javascript" => "js", "text/plain" => "txt", "text/xml" => "xml", "video/mpeg" => "mpeg", "video/quicktime" => "mov", "video/x-msvideo" => "avi", "video/x-ms-asf" => "asf", "video/x-ms-wmv" => "wmv"</td> |
|---|
| 253 | <td width="3em"> </td> |
|---|
| 254 | <td class="context-item-desc"> |
|---|
| 255 | default mapping of mime-types to file extensions. FileColumn will try to |
|---|
| 256 | rename a file to the correct extension if it detects a known mime-type |
|---|
| 257 | |
|---|
| 258 | </td> |
|---|
| 259 | </tr> |
|---|
| 260 | <tr class="top-aligned-row context-row"> |
|---|
| 261 | <td class="context-item-name">EXTENSIONS</td> |
|---|
| 262 | <td>=</td> |
|---|
| 263 | <td class="context-item-value">Set.new MIME_EXTENSIONS.values</td> |
|---|
| 264 | </tr> |
|---|
| 265 | <tr class="top-aligned-row context-row"> |
|---|
| 266 | <td class="context-item-name">DEFAULT_OPTIONS</td> |
|---|
| 267 | <td>=</td> |
|---|
| 268 | <td class="context-item-value">{ :root_path => File.join(RAILS_ROOT, "public"), :web_root => "", :mime_extensions => MIME_EXTENSIONS, :extensions => EXTENSIONS, :fix_file_extensions => true, # path to the unix "file" executbale for # guessing the content-type of files :file_exec => "file"</td> |
|---|
| 269 | <td width="3em"> </td> |
|---|
| 270 | <td class="context-item-desc"> |
|---|
| 271 | default options. You can override these with <tt><a |
|---|
| 272 | href="ClassMethods.html#M000003">file_column</a></tt>’s |
|---|
| 273 | <tt>options</tt> parameter |
|---|
| 274 | |
|---|
| 275 | </td> |
|---|
| 276 | </tr> |
|---|
| 277 | </table> |
|---|
| 278 | </div> |
|---|
| 279 | </div> |
|---|
| 280 | |
|---|
| 281 | |
|---|
| 282 | |
|---|
| 283 | |
|---|
| 284 | |
|---|
| 285 | |
|---|
| 286 | <!-- if method_list --> |
|---|
| 287 | <div id="methods"> |
|---|
| 288 | <h3 class="section-bar">Public Instance methods</h3> |
|---|
| 289 | |
|---|
| 290 | <div id="method-M000003" class="method-detail"> |
|---|
| 291 | <a name="M000003"></a> |
|---|
| 292 | |
|---|
| 293 | <div class="method-heading"> |
|---|
| 294 | <a href="ClassMethods.src/M000003.html" target="Code" class="method-signature" |
|---|
| 295 | onclick="popupCode('ClassMethods.src/M000003.html');return false;"> |
|---|
| 296 | <span class="method-name">file_column</span><span class="method-args">(attr, options={})</span> |
|---|
| 297 | </a> |
|---|
| 298 | </div> |
|---|
| 299 | |
|---|
| 300 | <div class="method-description"> |
|---|
| 301 | <p> |
|---|
| 302 | handle the <tt>attr</tt> attribute as a "file-upload" column, |
|---|
| 303 | generating additional methods as explained above. You should pass the |
|---|
| 304 | attribute’s name as a symbol, like this: |
|---|
| 305 | </p> |
|---|
| 306 | <pre> |
|---|
| 307 | file_column :image |
|---|
| 308 | </pre> |
|---|
| 309 | <p> |
|---|
| 310 | You can pass in an options hash that overrides the options in |
|---|
| 311 | <tt>DEFAULT_OPTIONS</tt>. |
|---|
| 312 | </p> |
|---|
| 313 | </div> |
|---|
| 314 | </div> |
|---|
| 315 | |
|---|
| 316 | |
|---|
| 317 | </div> |
|---|
| 318 | |
|---|
| 319 | |
|---|
| 320 | </div> |
|---|
| 321 | |
|---|
| 322 | |
|---|
| 323 | <div id="validator-badges"> |
|---|
| 324 | <p><small><a href="http://validator.w3.org/check/referer">[Validate]</a></small></p> |
|---|
| 325 | </div> |
|---|
| 326 | |
|---|
| 327 | </body> |
|---|
| 328 | </html> |
|---|
