shrine 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 06b571aff1653427247e09a1ec98f9e11a10eb34
-  data.tar.gz: cbdd5d75713e42ea5aa449eb1c0a604b2eae35a9
+  metadata.gz: ed4ba1e9f5dafe48af21c7f80039ca3d0014e600
+  data.tar.gz: 2f8f7903b3032d8ef43508a0e7259ab5deaedb25
 SHA512:
-  metadata.gz: 44c88e4f5bb848bc8854cde7ff4eb0fd3209f3b829998cad60377bb975816d94fce356ed8728f1ff86152523aa0e735e07dd6c9d1e008000170d312565e799d1
-  data.tar.gz: 056383f1b82fb43ecd62d3a43923c9864323c8c70ace4532ee35e293d94c74ae86b190d83f2870b4b44f7ee005d7688e443bb783b34cc38a8976bfdb5b6c5fe3
+  metadata.gz: 3d9200a6bfc5fe5705272a4d01a2e62a7146e869c53ede22534ec9043fa87e7c9566b58b5a7cf10f9667de47a9e91d468e34dae146b8cc8526f94cdcbe0f4404
+  data.tar.gz: 3c9673213a120a2d8427a9bee3280bccb97819154f1bd5bc7bc548f3a70274891133c4c86151b52bd8f94bdc158a4f8be84adf364edd2fd3488f7df98b75d5ef

data/README.md

@@ -1,6 +1,6 @@
 # Shrine
 
-Shrine is a toolkit for handling file uploads in Ruby applications.
+Shrine is a toolkit for file attachments in Ruby applications.
 
 If you're new, you're encouraged to read the [introductory blog post] which
 explains the motivation behind Shrine.
@@ -59,7 +59,8 @@ class Photo < Sequel::Model # ActiveRecord::Base
 end
 ```
 
-And add attachment fields to the Photo form:
+This creates an `image` attachment attribute which accepts files. Let's now
+add the form fields needed for attaching files:
 
 ```erb
 <form action="/photos" method="post" enctype="multipart/form-data">
@@ -68,15 +69,23 @@ And add attachment fields to the Photo form:
 </form>
 
 <!-- Rails: -->
-
 <%= form_for @photo do |f| %>
   <%= f.hidden_field :image, value: @photo.cached_image_data %>
   <%= f.file_field :image %>
 <% end %>
 ```
 
-Now when a Photo is created with the image attached, you can get the URL to
-the image:
+Now assigning the request parameters in your router/controller will
+automatically handle the image attachment:
+
+```rb
+post "/photos" do
+  Photo.create(params[:photo])
+end
+```
+
+When a Photo is created with the image attached, you can display the image via
+its URL:
 
 ```erb
 <img src="<%= @photo.image_url %>">
@@ -86,8 +95,8 @@ the image:
 
 When we assign an IO-like object to the record, Shrine will upload it to the
 registered `:cache` storage, which acts as a temporary storage, and write the
-location/storage/metadata of the uploaded file to a single `<attachment>_data`
-column:
+location, storage, and metadata of the uploaded file to a single
+`<attachment>_data` column:
 
 ```rb
 photo = Photo.new
@@ -105,7 +114,8 @@ The Shrine attachment module added the following methods to the `Photo` model:
 * `#image_url` – calls `image.url` if attachment is present, otherwise returns nil
 * `#image_attacher` - instance of `Shrine::Attacher` which handles attaching
 
-In addition to assigning new files, you can also assign already uploaded files:
+In addition to assigning new files, you can also assign already cached files
+using their JSON representation:
 
 ```rb
 photo.image = '{"storage":"cache","id":"9260ea09d8effd.jpg","metadata":{...}}'
@@ -114,9 +124,9 @@ photo.image = '{"storage":"cache","id":"9260ea09d8effd.jpg","metadata":{...}}'
 This allows Shrine to retain uploaded files in case of validation errors, and
 handle [direct uploads], via the hidden form field.
 
-The ORM plugin that we loaded will upload the attachment to permanent storage
-(`:store`) when the record is saved, and delete the attachment when record
-is destroyed:
+The ORM plugin that we loaded adds appropriate callbacks, so when record is
+saved the attachment is uploaded to permanent storge (`:store`), and when
+record is destroyed the attachment is destroyed as well:
 
 ```rb
 photo.image = File.open("waterfall.jpg")
@@ -129,7 +139,15 @@ photo.destroy
 photo.image.exists? #=> false
 ```
 
-In these examples we used `image` as the name of the attachment, but we can
+The ORM plugin will also delete replaced attachments:
+
+```rb
+photo.update(image: new_file) # changes the attachment and deletes previous
+# or
+photo.update(image: nil)      # removes the attachment and deletes previous
+```
+
+In all these examples we used `image` as the name of the attachment, but we can
 create attachment modules for any kind of attachments:
 
 ```rb
@@ -143,6 +161,21 @@ class Movie < Sequel::Model
 end
 ```
 
+### Multiple files
+
+Sometimes we want to allow users to upload multiple files at once. This can be
+achieved with by adding a `multiple` HTML attribute to the file field: `<input
+type="file" multiple>`.
+
+Shrine doesn't accept multiple files on single a attachment attribute, but you
+can instead attach each file to a separate database record, which is a much
+more flexible solution.
+
+The best way is to [directly upload][direct uploads] selected files, and then
+send the data of uploaded files as nested attributes for associated records.
+Alternatively you can send all selected files at once, and then transform them
+into nested association attributes in the controller.
+
 ## Uploader
 
 "Uploaders" are subclasses of `Shrine`, and this is where we define all our
@@ -184,6 +217,24 @@ the record:
 photo.image #=> #<Shrine::UploadedFile>
 ```
 
+### Plugins
+
+Shrine comes with a small core which provides only the essential functionality,
+and any additional features are available via plugins. This way you can choose
+exactly what and how much Shrine does for you. See the [website] for a complete
+list of plugins.
+
+The plugin system respects inheritance, so you can choose which plugins will
+be applied to which uploaders:
+
+```rb
+Shrine.plugin :logging # enables logging for all uploaders
+
+class ImageUploader < Shrine
+  plugin :backup # stores backups only for this uploader and its descendants
+end
+```
+
 ## Processing
 
 Shrine allows you to perform file processing in functional style; you receive
@@ -233,7 +284,7 @@ we're uploading images, we might want to store various thumbnails alongside the
 original image. If we're uploading videos, we might want to save a screenshot
 or transcode it into different formats.
 
-To save multiple files, we just need to load the versions plugin, and then in
+To save multiple files, we just need to load the `versions` plugin, and then in
 `#process` we can return a Hash of files:
 
 ```rb
@@ -257,7 +308,7 @@ end
 Being able to define processing on instance-level like this provides a lot of
 flexibility. For example, you can choose to process files in a certain order
 for maximum performance, and you can also add parallelization. It is
-recommended to load the delete_raw plugin for automatically deleting processed
+recommended to load the `delete_raw` plugin for automatically deleting processed
 files after uploading.
 
 Each version will be saved to the attachment column, and the attachment getter
@@ -266,7 +317,7 @@ will simply return a Hash of `Shrine::UploadedFile` objects:
 ```rb
 photo.image #=> {large: ..., medium: ..., small: ...}
 
-# With the store_dimensions plugin
+# With the store_dimensions plugin (requires fastimage gem)
 photo.image[:large].width  #=> 700
 photo.image[:medium].width #=> 500
 photo.image[:small].width  #=> 300
@@ -309,8 +360,7 @@ end
 
 You may have noticed the `context` variable floating around as the second
 argument for processing. This variable is present all the way from input file
-to uploaded file, and contains any additional information that can affect the
-upload:
+to uploaded file, and can contain useful information depending on the situation:
 
 * `context[:record]` -- the model instance
 * `context[:name]` -- attachment name on the model
@@ -323,28 +373,50 @@ generating location etc, and it is also used by some plugins internally.
 
 ## Validation
 
-Validations are registered by calling `Attacher.validate`, and are best done
-with the validation_helpers plugin:
+Validations are registered inside a `Attacher.validate` block, and you can load
+the `validation_helpers` plugin to get some convenient file validation methods:
 
 ```rb
-class DocumentUploader < Shrine
+class VideoUploader < Shrine
   plugin :validation_helpers
 
   Attacher.validate do
-    # Evaluated inside an instance of Shrine::Attacher.
-    if record.resume?
-      validate_max_size 10*1024*1024, message: "is too large (max is 10 MB)"
-      validate_mime_type_inclusion ["application/pdf"]
-    end
+    validate_max_size 50*1024*1024, message: "is too large (max is 50 MB)"
+    validate_mime_type_inclusion ["video/mp4"]
+  end
+end
+```
+
+```rb
+trailer = Trailer.new
+trailer.video = File.open("matrix.mp4")
+trailer.valid? #=> false
+trailer.errors.to_hash #=> {video: ["is too large (max is 50 MB)"]}
+```
+
+You can also do custom validations:
+
+```rb
+class VideoUploader < Shrine
+  Attacher.validate do
+    errors << "is longer than 5 minutes" if get.duration > 300
   end
 end
 ```
 
+The `Attacher.validate` block is executed in context of a `Shrine::Attacher`
+instance:
+
 ```rb
-document = Document.new(resume: true)
-document.file = File.open("resume.pdf")
-document.valid? #=> false
-document.errors.to_hash #=> {file: ["is too large (max is 2 MB)"]}
+class VideoUploader < Shrine
+  Attacher.validate do
+    self   #=> #<Shrine::Attacher>
+
+    get    #=> #<Shrine::UploadedFile>
+    record # the model instance
+    errors # array of error messages for this file
+  end
+end
 ```
 
 ## Metadata
@@ -374,7 +446,7 @@ which is set from the "Content-Type" request header, which is determined by the
 browser solely based on the file extension. This means that by default Shrine's
 "mime_type" is *not* guaranteed to hold the actual MIME type of the file.
 
-To help with that Shrine provides the determine_mime_type plugin, which by
+To help with that Shrine provides the `determine_mime_type` plugin, which by
 default uses the UNIX [file] utility to determine the actual MIME type:
 
 ```rb
@@ -388,8 +460,8 @@ photo.image.mime_type #=> "text/x-php"
 
 ### Custom metadata
 
-You can also extract and store completely custom metadata with the metadata
-plugin:
+You can also extract and store completely custom metadata with the
+`add_metadata` plugin:
 
 ```rb
 require "mini_magick"
@@ -397,7 +469,7 @@ require "mini_magick"
 class ImageUploader < Shrine
   plugin :add_metadata
 
-  add_metadata "exif" do |io, context|
+  add_metadata :exif do |io, context|
     MiniMagick::Image.new(io.path).exif
   end
 end
@@ -413,7 +485,7 @@ photo.image.exif
 Before Shrine uploads a file, it generates a random location for it. By
 default the hierarchy is flat, all files are stored in the root of the storage.
 If you want that each attachment has its own directory, you can load the
-pretty_location plugin:
+`pretty_location` plugin:
 
 ```rb
 Shrine.plugin :pretty_location
@@ -489,7 +561,7 @@ website.
 ### Upload options
 
 Many storages accept additional upload options, which you can pass via the
-upload_options plugin, or manually when uploading:
+`upload_options` plugin, or manually when uploading:
 
 ```rb
 uploader = MyUploader.new(:store)
@@ -498,40 +570,40 @@ uploader.upload(file, upload_options: {acl: "private"})
 
 ## Direct uploads
 
-Shrine comes with a [direct_upload] plugin which provides a [Roda] endpoint that
-accepts file uploads. This allows you to asynchronously start caching the file
-the moment the user selects it via AJAX (e.g. using the [jQuery-File-Upload] JS
-library).
+Shrine comes with a `direct_upload` plugin for asynchronous uploads to your
+app or an external service. It provides a [Roda] endpoint which you can mount
+in your app:
 
 ```rb
-Shrine.plugin :direct_upload # Provides a Roda endpoint
+gem "roda"
+```
+```rb
+Shrine.plugin :direct_upload
 ```
 ```rb
 Rails.application.routes.draw do
-  mount VideoUploader::UploadEndpoint => "/videos"
+  mount ImageUploader::UploadEndpoint => "/images"
 end
 ```
-```js
-$('[type="file"]').fileupload({
-  url:       '/videos/cache/upload',
-  paramName: 'file',
-  add:       function(e, data) { /* Disable the submit button */ },
-  progress:  function(e, data) { /* Add a nice progress bar */ },
-  done:      function(e, data) { /* Fill in the hidden field with the result */ }
-});
-```
 
-Along with the upload route, this endpoint also includes a route for generating
-presigns for direct uploads to 3rd-party services like Amazon S3. See the
-[direct_upload] plugin documentation for more details, as well as the
-[Roda](https://github.com/janko-m/shrine-example)/[Rails](https://github.com/erikdahlstrand/shrine-rails-example)
-example apps which demonstrate multiple uploads directly to S3.
+This endpoint provides the following routes:
+
+* `POST /images/cache/upload` - for direct uploads to your app
+* `GET /images/cache/presign` - for direct uploads to external service
+
+These routes can be used to asynchronously start caching the file the moment
+the user selects it, using JavaScript file upload libraries like
+[jQuery-File-Upload], [Dropzone] or [FineUploader].
+
+See the [direct_upload] plugin documentation and [Direct Uploads to S3] guide
+for more details, as well as the [Roda][roda_demo] and [Rails][rails_demo]
+demo apps which implement multiple uploads directly to S3.
 
 ## Backgrounding
 
 Shrine is the first file upload library designed for backgrounding support.
 Moving phases of managing attachments to background jobs is essential for
-scaling and good user experience, and Shrine provides a backgrounding plugin
+scaling and good user experience, and Shrine provides a `backgrounding` plugin
 which makes it really easy to plug in your favourite backgrounding library:
 
 ```rb
@@ -586,34 +658,16 @@ file_system = Shrine.storages[:cache]
 file_system.clear!(older_than: Time.now - 7*24*60*60) # delete files older than 1 week
 ```
 
-## Plugins
-
-Shrine comes with a small core which provides only the essential functionality,
-and any additional features are available via plugins. This way you can choose
-exactly what and how much Shrine does for you. Shrine itself [ships with over
-35 plugins], most of which I didn't cover here.
-
-The plugin system respects inheritance, so you can choose which plugins will
-be applied to which uploaders:
-
-```rb
-Shrine.plugin :logging # enables logging for all uploaders
-
-class ImageUploader < Shrine
-  plugin :store_dimensions # stores dimensions only for this uploader and its descendants
-end
-```
-
 ## On-the-fly processing
 
 Shrine allows you to define processing that will be performed on upload.
-However, what if want to perform processing on-the-fly, only when the URL is
-requested? Unlike Refile or Dragonfly, Shrine doesn't come with an image server
-built in, instead it expects you to integrate any of the existing generic image
-servers.
+However, what if you want to have processing performed on-the-fly when the URL
+is requested? Unlike Refile or Dragonfly, Shrine doesn't come with an image
+server built in; instead it expects you to integrate any of the existing
+generic image servers.
 
-Shrine has integrations for many commercial on-the-fly processing services, so
-you can use [shrine-cloudinary], [shrine-imgix] or [shrine-uploadcare].
+Shrine has integrations for many commercial on-the-fly processing services,
+including [Cloudinary], [Imgix] and [Uploadcare].
 
 If you don't want to use a commercial service, [Attache] is a great open-source
 image server. There isn't a Shrine integration written for it yet, but it
@@ -643,11 +697,12 @@ The gem is available as open source under the terms of the [MIT License].
 [image bombs]: https://www.bamsoftware.com/hacks/deflate.html
 [aws-sdk]: https://github.com/aws/aws-sdk-ruby
 [jQuery-File-Upload]: https://github.com/blueimp/jQuery-File-Upload
+[Dropzone]: https://github.com/enyo/dropzone
+[FineUploader]: https://github.com/FineUploader/fine-uploader
 [Roda]: https://github.com/jeremyevans/roda
 [Refile]: https://github.com/refile/refile
 [plugin system]: http://twin.github.io/the-plugin-system-of-sequel-and-roda/
 [MIT License]: http://opensource.org/licenses/MIT
-[example app]: https://github.com/janko-m/shrine-example
 [ships with over 35 plugins]: http://shrinerb.com#plugins
 [introductory blog post]: http://twin.github.io/introducing-shrine/
 [FileSystem]: http://shrinerb.com/rdoc/classes/Shrine/Storage/FileSystem.html
@@ -657,7 +712,11 @@ The gem is available as open source under the terms of the [MIT License].
 [direct uploads]: #direct-uploads
 [ffmpeg]: https://github.com/streamio/streamio-ffmpeg
 [direct_upload]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/DirectUpload.html
-[shrine-cloudinary]: https://github.com/janko-m/shrine-cloudinary
-[shrine-imgix]: https://github.com/janko-m/shrine-imgix
-[shrine-uploadcare]: https://github.com/janko-m/shrine-uploadcare
+[Cloudinary]: https://github.com/janko-m/shrine-cloudinary
+[Imgix]: https://github.com/janko-m/shrine-imgix
+[Uploadcare]: https://github.com/janko-m/shrine-uploadcare
 [Attache]: https://github.com/choonkeat/attache
+[roda_demo]: /demo
+[rails_demo]: https://github.com/erikdahlstrand/shrine-rails-example
+[Direct Uploads to S3]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[website]: http://shrinerb.com

data/doc/carrierwave.md

@@ -1,97 +1,236 @@
 # Shrine for CarrierWave Users
 
-This guide is aimed at helping CarrierWave users transition to Shrine. First it
-explains some key differences in the design between the two libraries.
-Afterwards it explains how you can transition an existing app that uses
-CarrierWave to Shrine. It then finishes off with an extensive reference of
-CarrierWave's interface and what is the equivalent in Shrine.
+This guide is aimed at helping CarrierWave users transition to Shrine, and it
+consists of three parts:
 
-## Uploaders
+1. Explanation of the key differences in design between CarrierWave and Shrine
+2. Instructions how to migrate and existing app that uses CarrierWave to Shrine
+3. Extensive reference of CarrierWave's interface with Shrine equivalents
 
-Shrine has a concept of uploaders similar to CarrierWave's, which allows you to
-have different uploading logic for different types of files:
+## Storage
+
+While in CarrierWave you configure storage in global configuration, in Shrine
+storage is a class which you can pass options to during initialization:
 
 ```rb
-class ImageUploader < Shrine
-  # uploading logic
+CarrierWave.configure do |config|
+  config.fog_provider = "fog/aws"
+  config.fog_credentials = {
+    provider:              "AWS",
+    aws_access_key_id:     "abc",
+    aws_secret_access_key: "xyz",
+  }
+  config.fog_directory = "my-bucket"
 end
 ```
+```rb
+Shrine.storages[:store] = Shrine::Storage::S3.new(
+  bucket:                "my-bucket",
+  aws_access_key_id:     "abc",
+  aws_secret_access_key: "xyz",
+)
+```
 
-While in CarrierWave you choose a storages for uploaders directly, in Shrine
-you first register storages globally (under a symbol name), and then you can
-instantiate uploaders with a specific storage.
+In CarrierWave temporary storage cannot be configured; it saves and retrieves
+files from the filesystem, you can only set the directory. With Shrine both
+temporary (`:cache`) and permanent (`:store`) storage are first-class citizens
+and fully configurable, so you can also have files *cached* on S3 (preferrably
+via [direct uploads]):
 
 ```rb
-require "shrine/storage/file_system"
-
 Shrine.storages = {
-  cache: Shrine::Storage::FileSystem.new("public", prefix: "uploads/cache"),
-  store: Shrine::Storage::FileSystem.new("public", prefix: "uploads/store"),
+  cache: Shrine::Storages::S3.new(prefix: "cache", **s3_options),
+  store: Shrine::Storages::S3.new(prefix: "store", **s3_options),
 }
 ```
+
+## Uploader
+
+Shrine shares CarrierWave's concept of *uploaders*, classes which encapsulate
+file attachment logic for different file types:
+
 ```rb
-cache_uploader = Shrine.new(:cache)
-store_uploader = Shrine.new(:store)
+class ImageUploader < Shrine
+  # attachment logic
+end
 ```
 
-CarrierWave uses symbols for referencing storages (`:file`, `:fog`, ...), but
-in Shrine storages are simple Ruby classes which you can instantiate directly.
-This makes storages much more flexible, because this way they can have their
-own options that are specific to them.
+However, uploaders in CarrierWave are very broad; in addition to uploading and
+deleting files, they also represent the uploaded file. Shrine has a separate
+`Shrine::UploadedFile` class which represents the uploaded file.
+
+```rb
+uploader = ImageUploader.new(:store)
+uploaded_file = uploader.upload(image)
+uploaded_file          #=> #<Shrine::UploadedFile>
+uploaded_file.url      #=> "https://my-bucket.s3.amazonaws.com/store/kfds0lg9rer.jpg"
+uploaded_file.download #=> #<Tempfile>
+```
 
 ### Processing
 
-In Shrine processing is defined and performed on the instance-level, which
-gives a lot of flexibility. You can return a single processed file or a hash of
-versions:
+In contrast to CarrierWave's class-level DSL, in Shrine processing is defined
+and performed on the instance-level. The result of processing can be a single
+file or a hash of versions:
 
 ```rb
-require "image_processing/mini_magick" # part of the "image_processing" gem
+class ImageUploader < CarrierWave::Uploader::Base
+  include CarrierWave::MiniMagick
+
+  process resize_to_limit: [800, 800]
+
+  version :medium do
+    process resize_to_limit: [500, 500]
+  end
 
+  version :small, from_version: :medium do
+    process resize_to_limit: [300, 300]
+  end
+end
+```
+
+```rb
 class ImageUploader < Shrine
   include ImageProcessing::MiniMagick
   plugin :processing
   plugin :versions
 
   process(:store) do |io, context|
-    thumbnail = resize_to_limit(io.download, 300, 300)
-    {original: io, thumbnail: thumbnail}
+    size_800 = resize_to_limit(io.download, 800, 800)
+    size_500 = resize_to_limit(size_800,    500, 500)
+    size_300 = resize_to_limit(size_500,    300, 300)
+
+    {original: size_800, medium: size_500, small: size_300}
+  end
+end
+```
+
+This allows you to fully optimize processing, because you can easily specify
+which files are processed from which, and even add parallelization.
+
+CarrierWave performs processing before validations, which is a huge security
+issue, as it allows users to give arbitrary files to your processing tool, even
+if you have validations. Shrine performs processing after validations.
+
+#### Reprocessing versions
+
+Shrine doesn't have a built-in way of regenerating versions, because that has
+to be written and optimized differently depending on whether you're adding or
+removing a version, what ORM are you using, how many records there are in the
+database etc. The [Reprocessing versions] guide provides some useful tips on
+this task.
+
+### Validations
+
+Like with processing, validations in Shrine are also defined and performed on
+instance-level:
+
+```rb
+class ImageUploader < CarrierWave::Uploader::Base
+  def extension_whitelist
+    %w[jpg jpeg gif png]
+  end
+
+  def content_type_whitelist
+    /image\//
+  end
+
+  def size_range
+    0..(10*1024*1024)
+  end
+end
+```
+
+```rb
+class ImageUploader < Shrine
+  plugin :validation_helpers
+
+  Attacher.validate do
+    validate_extension_inclusion [/jpe?g/, "gif", "png"]
+    validate_mime_type_inclusion %w[image/jpeg image/gif image/png]
+    validate_max_size 10*1024*1024 unless record.admin?
   end
 end
 ```
 
 ## Attachments
 
-Like CarrierWave, Shrine also provides integrations with ORMs, it ships with
-plugins for both Sequel and ActiveRecord (but it can also be used with simple
-PORO models).
+Like CarrierWave, Shrine also provides integrations with ORMs. It ships with
+plugins for both Sequel and ActiveRecord, but can also be used with just PORO
+models.
 
 ```rb
-Shrine.plugin :sequel       # If you're using Sequel
-Shrine.plugin :activerecord # If you're using ActiveRecord
+Shrine.plugin :sequel       # if you're using Sequel
+Shrine.plugin :activerecord # if you're using ActiveRecord
 ```
 
 Instead of giving you class methods for "mounting" uploaders, in Shrine you
-generate attachment modules which you simply include in your models:
+generate attachment modules which you simply include in your models, which
+gives your models similar set of methods that CarrierWave gives:
 
 ```rb
-class User < Sequel::Model
-  include ImageUploader[:avatar] # adds `avatar`, `avatar=` and `avatar_url` methods
+class Photo < ActiveRecord::Base
+  extend CarrierWave::ActiveRecord # done automatically by CarrierWave
+  mount_uploader :image, ImageUploader
 end
 ```
+```rb
+class Photo < ActiveRecord::Base
+  include ImageUploader[:avatar]
+end
+```
+
+### Attachment column
+
+You models are required to have the `<attachment>_data` column, which Shrine
+uses to save storage, location, and metadata of the uploaded file.
+
+```rb
+photo.image_data #=>
+# {
+#   "storage" => "store",
+#   "id" => "photo/1/image/0d9o8dk42.png",
+#   "metadata" => {
+#     "filename"  => "nature.png",
+#     "size"      => 49349138,
+#     "mime_type" => "image/png"
+#   }
+# }
+
+photo.image.original_filename #=> "nature.png"
+photo.image.size              #=> 49349138
+photo.image.mime_type         #=> "image/png"
+```
+
+This is much more powerful than storing only the filename like CarrierWave
+does, as it allows you to also store any additional metadata that you might
+want to extract.
+
+Unlike CarrierWave, Shrine will store this information for each processed
+version, making them first-class citizens:
+
+```rb
+photo.image[:original]       #=> #<Shrine::UploadedFile>
+photo.image[:original].width #=> 800
+
+photo.image[:thumb]          #=> #<Shrine::UploadedFile>
+photo.image[:thumb].width    #=> 300
+```
 
-You models are required to have the `<attachment>_data` column, in the above
-case `avatar_data`. Shrine stores storage, location, and additional metadata of
-the uploaded file to that column.
+Also, since CarrierWave stores only the filename, it has to recalculate the
+full location each time it wants to generate the URL. That makes it really
+difficult to move files to a new location, because changing how the location is
+generated will now cause incorrect URLs to be generated for all existing files.
+Shrine calculates the whole location only once and saves it to the column.
 
 ### Multiple uploads
 
 Shrine doesn't have support for multiple uploads like CarrierWave does, instead
-it expects that you will implement multiple uploads yourself using a separate
-model. This is a good thing, because the implementation is specific to the ORM
-you're using, and it's analogous to how you would implement adding items to any
-dynamic one-to-many relationship. Take a look at the [example app] which
-demonstrates how easy it is to implement multiple uploads.
+it expects that you will attach each file to a separate database record. This
+is a good thing, because the implementation is specific to the ORM you're
+using, and it's analogous to how you would implement any nested one-to-many
+associations. Take a look at the [demo app] which shows how easy it is to
+implement multiple uploads.
 
 ## Migrating from CarrierWave
 
@@ -509,6 +648,7 @@ No equivalent, it depends on your application whether you need the form to be
 multipart or not.
 
 [image_processing]: https://github.com/janko-m/image_processing
-[example app]: https://github.com/janko-m/shrine-example
-[Regenerating versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html
+[demo app]: https://github.com/janko-m/shrine/tree/master/demo
+[Reprocessing versions]: http://shrinerb.com/rdoc/files/doc/regenerating_versions_md.html
 [shrine-fog]: https://github.com/janko-m/shrine-fog
+[direct uploads]: http://shrinerb.com/rdoc/files/doc/direct_s3_md.html