shrine 3.0.1 → 3.3.0

data/doc/external/extensions.md

@@ -4,44 +4,50 @@ title: Extensions
 
 ## Storages
 
-* [shrine-aliyun-oss](https://github.com/zillou/shrine-aliyun-oss)
-* [shrine-cloudinary](https://github.com/shrinerb/shrine-cloudinary)
-* [shrine-flickr](https://github.com/shrinerb/shrine-flickr)
-* [shrine-fog](https://github.com/shrinerb/shrine-fog)
-* [shrine-ftp](https://github.com/ProjectResound/shrine-ftp)
-* [shrine-google_cloud_storage](https://github.com/renchap/shrine-google_cloud_storage)
-* [shrine-gdrive_storage](https://github.com/edwardsharp/shrine-gdrive_storage)
-* [shrine-gridfs](https://github.com/shrinerb/shrine-gridfs)
-* [shrine-imgix](https://github.com/shrinerb/shrine-imgix)
-* [shrine-memory](https://github.com/shrinerb/shrine-memory)
-* [shrine-redis](https://github.com/dbongo/shrine-redis)
-* [shrine-scp](https://github.com/jordanandree/shrine-scp)
-* [shrine-sql](https://github.com/shrinerb/shrine-sql)
-* [shrine-thumbor](https://github.com/havran/shrine-thumbor)
-* [shrine-transloadit](https://github.com/shrinerb/shrine-transloadit)
-* [shrine-uploadcare](https://github.com/shrinerb/shrine-uploadcare)
-* [shrine-url](https://github.com/shrinerb/shrine-url)
-* [shrine-storage-you_tube](https://github.com/thedyrt/shrine-storage-you_tube)
-* [shrine-webdav](https://github.com/funbox/shrine-webdav)
+| Gem                                                                                   | Description                                                                 |
+| :----                                                                                 | :----------                                                                 |
+| [shrine-aliyun-oss](https://github.com/zillou/shrine-aliyun-oss)                      | Storage using [Alibaba Cloud OSS](https://www.alibabacloud.com/product/oss) |
+| [shrine-cloudinary](https://github.com/shrinerb/shrine-cloudinary)                    | Storage using [Cloudinary](https://cloudinary.com/)                         |
+| [shrine-flickr](https://github.com/shrinerb/shrine-flickr)                            | Storage using [Flickr](https://flickr.com/)                                 |
+| [shrine-fog](https://github.com/shrinerb/shrine-fog)                                  | Storage using [Fog](http://fog.io/)                                         |
+| [shrine-ftp](https://github.com/ProjectResound/shrine-ftp)                            | Storage using an FTP server                                                 |
+| [shrine-google_cloud_storage](https://github.com/renchap/shrine-google_cloud_storage) | Storage using [Google Cloud Storage](https://cloud.google.com/storage/)     |
+| [shrine-gdrive_storage](https://github.com/edwardsharp/shrine-gdrive_storage)         | Storage using [Google Drive](https://www.google.com/drive/)                 |
+| [shrine-gridfs](https://github.com/shrinerb/shrine-gridfs)                            | Storage using [Mongo GridFS](https://docs.mongodb.com/manual/core/gridfs/)  |
+| [shrine-redis](https://github.com/dbongo/shrine-redis)                                | Storage using [Redis](https://redis.io/)                                    |
+| [shrine-scp](https://github.com/jordanandree/shrine-scp)                              | Storage using `scp`                                                         |
+| [shrine-sql](https://github.com/shrinerb/shrine-sql)                                  | Storage using an SQL database                                               |
+| [shrine-uploadcare](https://github.com/shrinerb/shrine-uploadcare)                    | Storage using [Uploadcare](https://uploadcare.com)                          |
+| [shrine-url](https://github.com/shrinerb/shrine-url)                                  | Storage for handling remote URLs                                            |
+| [shrine-storage-you_tube](https://github.com/thedyrt/shrine-storage-you_tube)         | Storage using [YouTube](https://www.youtube.com/)                           |
+| [shrine-webdav](https://github.com/funbox/shrine-webdav)                              | Storage using a [WebDAV](https://en.wikipedia.org/wiki/WebDAV) server       |
 
 ## Plugins
 
-* [administrate-field-shrine](https://github.com/catsky/administrate-field-shrine)
-* [rails_admin_shrine](https://github.com/iquest/rails_admin_shrine)
-* [shrine-color](https://github.com/jnylen/shrine-color)
-* [shrine-configurable_storage](https://github.com/SleeplessByte/shrine-configurable_storage)
-* [shrine-content_addressable](https://github.com/SleeplessByte/shrine-content_addressable)
-* [shrine-lambda](https://github.com/texpert/shrine-lambda)
-* [hanami-shrine](https://github.com/katafrakt/hanami-shrine)
-* [shrine-mongoid](https://github.com/shrinerb/shrine-mongoid)
-* [shrine-rails](https://github.com/abepetrillo/shrine-rails)
-* [shrine-reform](https://github.com/shrinerb/shrine-reform)
-* [shrine-rom](https://github.com/shrinerb/shrine-rom)
-* [shrine-tus](https://github.com/shrinerb/shrine-tus)
+| Gem                                                                                         | Description                                                           |
+| :----                                                                                       | :--------                                                             |
+| [administrate-field-shrine](https://github.com/catsky/administrate-field-shrine)            | Plugin for [Administrate](https://github.com/thoughtbot/administrate) |
+| [rails_admin_shrine](https://github.com/iquest/rails_admin_shrine)                          | Plugin for [RailsAdmin](https://github.com/sferik/rails_admin)        |
+| [shrine-blurhash](https://github.com/renchap/shrine-blurhash)                               | Plugin for computing [Blurhash](https://blurha.sh/) on images         |
+| [shrine-cloudimage](https://github.com/janklimo/shrine-cloudimage)                          | Plugin for [Cloudimage](https://www.cloudimage.io/)                   |
+| [shrine-color](https://github.com/jnylen/shrine-color)                                      | Plugin for finding dominant color in an image                         |
+| [shrine-configurable_storage](https://github.com/SleeplessByte/shrine-configurable_storage) | Plugin for lazy storage registration                                  |
+| [shrine-content_addressable](https://github.com/SleeplessByte/shrine-content_addressable)   | Plugin for generating content addressable locations                   |
+| [shrine-imgix](https://github.com/shrinerb/shrine-imgix)                                    | Plugin for [Imgix](https://www.imgix.com/)                            |
+| [shrine-transloadit](https://github.com/shrinerb/shrine-transloadit)                        | Plugin for [Transloadit](https://transloadit.com/)                    |
+| [shrine-lambda](https://github.com/texpert/shrine-lambda)                                   | Plugin for [AWS Lambda](https://aws.amazon.com/lambda/)               |
+| [hanami-shrine](https://github.com/katafrakt/hanami-shrine)                                 | Plugin for [Hanami](https://hanamirb.org/)                            |
+| [shrine-mongoid](https://github.com/shrinerb/shrine-mongoid)                                | Plugin for [Mongoid](https://mongoid.org)                             |
+| [shrine-rails](https://github.com/abepetrillo/shrine-rails)                                 | Plugin for [Rails](https://rubyonrails.org/)                          |
+| [shrine-rom](https://github.com/shrinerb/shrine-rom)                                        | Plugin for [ROM](https://rom-rb.org/)                                 |
+| [shrine-tus](https://github.com/shrinerb/shrine-tus)                                        | Plugin for [tus](https://tus.io) server integration                   |
 
 ## Libraries
 
-* [ckeditor](https://github.com/galetahub/ckeditor)
-* [imgproxy](https://github.com/imgproxy/imgproxy.rb)
-* [rails_admin](https://github.com/sferik/rails_admin)
-* [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart)
+| Gem                                                             | Description                                                                     |
+| :-----                                                          | :-------                                                                        |
+| [ckeditor](https://github.com/galetahub/ckeditor)               | Integration for [CKEditor](https://ckeditor.com/ckeditor-4/)                    |
+| [faster_s3_url](https://github.com/jrochkind/faster_s3_url)     | Optimized generation of public and presigned AWS S3 GET URLs                    |
+| [imgproxy](https://github.com/imgproxy/imgproxy.rb)             | Integration for [imgproxy](https://github.com/imgproxy/imgproxy)                |
+| [rails_admin](https://github.com/sferik/rails_admin)            | Integration for [RailsAdmin](https://github.com/sferik/rails_admin)             |
+| [uppy-s3_multipart](https://github.com/janko/uppy-s3_multipart) | Integration for [Uppy AWS S3 Multipart](https://uppy.io/docs/aws-s3-multipart/) |

data/doc/external/misc.md

@@ -4,14 +4,29 @@ title: Miscellaneous
 
 ## Demos
 
-* [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)
-* [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)
-* [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)
-* [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)
-* [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)
-* [ROM & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)
-* [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo)
+| Demo                                                                                | Description                                      |
+| :---                                                                                | :----------                                      |
+| [Dropzone demo](https://github.com/codyeatworld/example-shrine-dropzone)            | Shows direct upload using [Dropzone.js]          |
+| [Hanami demo](https://github.com/katafrakt/hanami-shrine-example)                   | Shows file attachment in [Hanami]                |
+| [Crop demo](https://github.com/shrinerb/shrine-crop-example)                        | Shows image cropping using [Cropper.js]          |
+| [Rails demo](https://github.com/erikdahlstrand/shrine-rails-example)                | Shows direct upload in [Rails]                   |
+| [Resumable uploads demo](https://github.com/shrinerb/shrine-tus-demo)               | Shows resumable direct upload on [tus]           |
+| [Roda demo (official)](https://github.com/shrinerb/shrine/tree/master/demo)         | Shows direct upload in [Roda]                    |
+| [rom-rb & dry-rb demo](https://github.com/shrinerb/shrine-rom/tree/master/demo)     | Shows file attachment with [rom-rb] and [dry-rb] |
+| [Transloadit demo](https://github.com/shrinerb/shrine-transloadit/tree/master/demo) | Shows file processing using [Transloadit]        |
 
 ## Projects
 
-* [Cortex CMS](https://docs.cortexcms.org)
+| Project                                 | Description                                                             |
+| :------                                 | :----------                                                             |
+| [CortexCMS](https://docs.cortexcms.org) | An open source, enterprise content management and distribution platform |
+
+[Dropzone.js]: https://www.dropzonejs.com/
+[Hanami]: https://hanamirb.org/
+[Cropper.js]: https://github.com/fengyuanchen/cropperjs
+[Rails]: https://rubyonrails.org/
+[tus]: https://tus.io/
+[Roda]: https://roda.jeremyevans.net/
+[rom-rb]: https://rom-rb.org/
+[dry-rb]: https://dry-rb.org/
+[Transloadit]: https://transloadit.com/

data/doc/getting_started.md

@@ -50,7 +50,7 @@ class AddImageDataToPhotos < ActiveRecord::Migration
 end
 ```
 <!--Rails-->
-```sh
+```
 $ rails generate migration add_image_data_to_photos image_data:text
 ```
 <!--END_DOCUSAURUS_CODE_TABS-->
@@ -110,6 +110,14 @@ form @photo, action: "/photos", enctype: "multipart/form-data" do |f|
   f.button "Create"
 end
 ```
+<!--HTML-->
+```erb
+<form action="/photos" method="post" enctype="multipart/form-data">
+  <input name="photo[image]" type="hidden" value="<%= @photo.cached_image_data %>" />
+  <input name="photo[image] "type="file" />
+  <input type="submit" value="Create" />
+</form>
+```
 <!--END_DOCUSAURUS_CODE_TABS-->
 
 Note that the file field needs to go *after* the hidden field, so that
@@ -167,9 +175,13 @@ specific storage service, by implementing a common public interface. Storage
 instances are registered under an identifier in `Shrine.storages`, so that they
 can later be used by [uploaders][uploader].
 
-Previously we've shown the [FileSystem] storage which saves files to disk, but
-Shrine also ships with [S3] storage which stores files on [AWS S3] (or any
-S3-compatible service such as [DigitalOcean Spaces] or [MinIO]).
+Shrine ships with the following storages:
+
+* [`Shrine::Storage::FileSystem`][FileSystem] – stores files on disk
+* [`Shrine::Storage::S3`][S3] – stores files on [AWS S3] (or [DigitalOcean Spaces], [MinIO], ...)
+* [`Shrine::Storage::Memory`][Memory] – stores file in memory (convenient for [testing][Testing with Shrine])
+
+Here is how we might configure Shrine with S3 storage:
 
 ```rb
 # Gemfile
@@ -180,14 +192,14 @@ require "shrine/storage/s3"
 
 s3_options = {
   bucket:            "<YOUR BUCKET>", # required
+  region:            "<YOUR REGION>", # required
   access_key_id:     "<YOUR ACCESS KEY ID>",
   secret_access_key: "<YOUR SECRET ACCESS KEY>",
-  region:            "<YOUR REGION>",
 }
 
 Shrine.storages = {
-  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options),
-  store: Shrine::Storage::S3.new(**s3_options),
+  cache: Shrine::Storage::S3.new(prefix: "cache", **s3_options), # temporary
+  store: Shrine::Storage::S3.new(**s3_options),                  # permanent
 }
 ```
 
@@ -196,9 +208,9 @@ suitable for [direct uploads][presigned upload]. The `:cache` and `:store`
 names are special only in terms that the [attacher] will automatically pick
 them up, you can also register more storage objects under different names.
 
-See the [FileSystem] and [S3] storage docs for more details. There are [many
-more Shrine storages][storages] provided by external gems, and you can also
-[create your own storage][Creating Storages].
+See the [FileSystem]/[S3]/[Memory] storage docs for more details. There are
+[many more Shrine storages][storages] provided by external gems, and you can
+also [create your own storage][Creating Storages].
 
 ## Uploader
 
@@ -254,15 +266,17 @@ uploader.upload(io, upload_options: { acl: "public-read" }) # add options to Sto
 
 Shrine is able to upload any IO-like object that implement methods [`#read`],
 [`#rewind`], [`#eof?`] and [`#close`] whose behaviour matches the [`IO`] class.
-This includes built-in IO and IO-like objects like File, Tempfile and StringIO.
+This includes but is not limited to the following objects:
 
-When a file is uploaded to a Rails app, in request params it will be
-represented by an `ActionDispatch::Http::UploadedFile` object, which is also an
-IO-like object accepted by Shrine. In other Rack applications the uploaded file
-will be represented as a Hash, but it can be converted into an IO-like object
-with the [`rack_file`][rack_file plugin] plugin.
-
-Here are some examples of various IO-like objects that can be uploaded:
+* [`File`](https://ruby-doc.org/core/File.html)
+* [`Tempfile`](https://ruby-doc.org/stdlib/libdoc/tempfile/rdoc/Tempfile.html)
+* [`StringIO`](https://ruby-doc.org/stdlib/libdoc/stringio/rdoc/StringIO.html)
+* [`ActionDispatch::Http::UploadedFile`](https://api.rubyonrails.org/classes/ActionDispatch/Http/UploadedFile.html)
+* [`Shrine::RackFile`](https://shrinerb.com/docs/plugins/rack_file)
+* [`Shrine::DataFile`](https://shrinerb.com/docs/plugins/data_uri)
+* [`Shrine::UploadedFile`](#uploaded-file)
+* [`Down::ChunkedIO`](https://github.com/janko/down#streaming)
+* ...
 
 ```rb
 uploader.upload File.open("/path/to/file", binmode: true)   # upload from disk
@@ -278,7 +292,15 @@ uploader.upload Shrine::UploadedFile.new(...)               # upload from Shrine
 
 The `Shrine::UploadedFile` object represents the file that was uploaded to a
 storage, and it's what's returned from `Shrine#upload` or when retrieving a
-record [attachment]. It contains the following data:
+record [attachment].
+
+```rb
+uploader.upload(file) #=> #<Shrine::UploadedFile ...>  (uploader)
+photo.image           #=> #<Shrine::UploadedFile ...>  (attachment)
+attacher.file         #=> #<Shrine::UploadedFile ...>  (attacher)
+```
+
+An uploaded file object contains the following data:
 
 | Key        | Description                                        |
 | :-------   | :----------                                        |
@@ -287,13 +309,12 @@ record [attachment]. It contains the following data:
 | `metadata` | file [metadata] that was extracted before upload   |
 
 ```rb
-uploaded_file = uploader.upload(file)
 uploaded_file #=> #<Shrine::UploadedFile id="949sdjg834.jpg" storage=:store metadata={...}>
 
-uploaded_file.id          # => "949sdjg834.jpg"
-uploaded_file.storage_key # => :store
-uploaded_file.storage     # => #<Shrine::Storage::S3>
-uploaded_file.metadata    # => {...}
+uploaded_file.id          #=> "949sdjg834.jpg"
+uploaded_file.storage_key #=> :store
+uploaded_file.storage     #=> #<Shrine::Storage::S3>
+uploaded_file.metadata    #=> {...}
 ```
 
 It comes with many convenient methods that delegate to the storage:
@@ -341,7 +362,7 @@ The easiest way to attach files is with the `Shrine::Attachment` module:
 ```rb
 class Photo < Sequel::Model # ActiveRecord::Base
   include ImageUploader::Attachment.new(:image) #
-  include ImageUploader::Attachment[:image]     # use a preferred syntax
+  include ImageUploader::Attachment[:image]     # use your preferred syntax
   include ImageUploader::Attachment(:image)     #
 end
 ```
@@ -364,7 +385,7 @@ that attachments are deleted when the record is destroyed.
 photo.image #=> nil
 
 # the assigned file is cached to temporary storage and written to `image_data` column
-photo.image = File.open("waterfall.jpg")
+photo.image = File.open("waterfall.jpg", "rb")
 photo.image      #=> #<Shrine::UploadedFile ...>
 photo.image_url  #=> "/uploads/cache/0sdfllasfi842.jpg"
 photo.image_data #=> '{"id":"0sdfllasfi842.jpg","storage":"cache","metadata":{...}}'
@@ -408,38 +429,36 @@ attacher.url          # equivalent to `photo.image_url`
 ```
 
 The attacher is what drives attaching files to model instances; you can use it
-as a more explicit alternative to models' attachment interface, or simply when
-you need something that's not available through the attachment methods.
+as a more explicit alternative to models' attachment interface, or when you
+need something that's not available through the attachment methods.
 
-You can do things such as change the temporary and permanent storage the
-attacher uses, or upload files directly to permanent storage. See the [Using
-Attacher] guide for more details.
+See [Using Attacher] guide for more details.
 
 ### Temporary storage
 
-Shrine uses temporary storage to support retaining uploaded files across form
-redisplays and [direct uploads]. But you can disable this behaviour, and have
-files go straight to permanent storage:
+Shrine uses temporary storage to support [file validation][validation] and
+[direct uploads]. If you don't need these features, you can tell Shrine to
+upload files directly to permanent storage:
 
 ```rb
 Shrine.plugin :model, cache: false
 ```
-<!--DOCUSAURUS_CODE_TABS-->
-<!--Attachment-->
 ```rb
-photo.image = File.open("waterfall.jpg")
+photo.image = File.open("waterfall.jpg", "rb")
 photo.image.storage_key #=> :store
 ```
-<!--Attacher-->
+
+If you're using the attacher directly, you can just use `Attacher#attach`
+instead of `Attacher#assign`:
+
 ```rb
-attacher.attach File.open("waterfall.jpg")
+attacher.attach File.open("waterfall.jpg", "rb")
 attacher.file.storage_key #=> :store
 ```
-<!--END_DOCUSAURUS_CODE_TABS-->
 
 ## Plugin system
 
-By default Shrine comes with a small core which provides only the essential
+By default, Shrine comes with a small core which provides only the essential
 functionality. All additional features are available via [plugins], which also
 ship with Shrine. This way you can choose exactly what and how much Shrine does
 for you, and you load the code only for features that you use.
@@ -497,7 +516,7 @@ gem "marcel", "~> 0.3"
 Shrine.plugin :determine_mime_type, analyzer: :marcel
 ```
 ```rb
-photo = Photo.create(image: StringIO.new("<?php ... ?>"))
+photo = Photo.new(image: StringIO.new("<?php ... ?>"))
 photo.image.mime_type #=> "application/x-php"
 ```
 
@@ -510,36 +529,38 @@ the [Extracting Metadata] guide for more details.
 
 ## Processing
 
-Shrine allows you to process attached files up front or on-the-fly. For
-example, if your app is accepting image uploads, you can generate a predefined
-set of of thumbnails when the image is attached to a record, or you can have
-thumbnails generated dynamically as they're needed.
+Shrine allows you to process attached files both "eagerly" and "on-the-fly".
+For example, if your app is accepting image uploads, you can generate a
+predefined set of of thumbnails when the image is attached to a record, or you
+can have thumbnails generated dynamically as they're needed.
 
 For image processing, it's recommended to use the **[ImageProcessing]** gem,
 which is a high-level wrapper for processing with
 [MiniMagick][ImageProcessing::MiniMagick] and [libvips][ImageProcessing::Vips].
 
-```sh
+```
 $ brew install imagemagick vips
 ```
 
-### Processing up front
+### Eager processing
 
-You can use the [`derivatives`][derivatives plugin] plugin to generate a set of
-pre-defined processed files:
+We can use the [`derivatives`][derivatives plugin] plugin to generate a
+pre-defined set of processed files (e.g. image thumbnails). We do this by
+registering a derivatives processor block and then explicitly triggering
+creation:
 
 ```rb
 # Gemfile
 gem "image_processing", "~> 1.8"
 ```
 ```rb
-Shrine.plugin :derivatives
+Shrine.plugin :derivatives, create_on_promote: true
 ```
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  Attacher.derivatives_processor do |original|
+  Attacher.derivatives do |original|
     magick = ImageProcessing::MiniMagick.source(original)
 
     {
@@ -552,40 +573,34 @@ end
 ```
 ```rb
 photo = Photo.new(image: file)
-photo.image_derivatives! # calls derivatives processor and uploads results
-photo.save
+photo.save # automatically creates derivatives on promotion
 ```
 
-If you're allowing the attached file to be updated later on, in your update
-route make sure to trigger derivatives creation for new attachments:
+You can then retrieve the URL of a processed derivative:
 
 ```rb
-photo.image_derivatives! if photo.image_changed?
+photo.image_url(:large) #=> "https://s3.amazonaws.com/path/to/large.jpg"
 ```
 
-After the processed files are uploaded, their data is saved into the
-`<attachment>_data` column. You can then retrieve the derivatives as
-[`Shrine::UploadedFile`][uploaded file] objects:
+The derivatives data is stored in the `<attachment>_data` column, and you can
+retrieve them as [`Shrine::UploadedFile`][uploaded file] objects:
 
 ```rb
-photo.image(:large)            #=> #<Shrine::UploadedFile ...>
-photo.image(:large).url        #=> "/uploads/store/lg043.jpg"
-photo.image(:large).size       #=> 5825949
-photo.image(:large).mime_type  #=> "image/jpeg"
+photo.image(:large)           #=> #<Shrine::UploadedFile id="path/to/large.jpg" storage=:store metadata={...}>
+photo.image(:large).url       #=> "https://s3.amazonaws.com/path/to/large.jpg"
+photo.image(:large).size      #=> 5825949
+photo.image(:large).mime_type #=> "image/jpeg"
 ```
 
-For more details, see the [`derivatives`][derivatives plugin] plugin
-documentation and the [File Processing] guide.
+For more details, see the [File Processing] guide and the
+[`derivatives`][derivatives plugin] plugin documentation.
 
-### Processing on-the-fly
+### On-the-fly processing
 
 On-the-fly processing is provided by the
-[`derivation_endpoint`][derivation_endpoint plugin] plugin. It comes with a
-[mountable][Mounting Endpoints] Rack app which applies processing on request
-and returns processed files.
-
-To set it up, we mount the Rack app in our router on a chosen path prefix,
-configure the plugin with a secret key and that path prefix, and define
+[`derivation_endpoint`][derivation_endpoint plugin] plugin. To set it up, we
+configure the plugin with a secret key and a path prefix, [mount][Mounting
+Endpoints] its Rack app in our routes on the configured path prefix, and define
 processing we want to perform:
 
 ```rb
@@ -593,19 +608,15 @@ processing we want to perform:
 gem "image_processing", "~> 1.8"
 ```
 ```rb
-# config/routes.rb (Rails)
-Rails.application.routes.draw do
-  # ...
-  mount ImageUploader.derivation_endpoint => "/derivations/image"
-end
+# config/initializers/rails.rb (Rails)
+# ...
+Shrine.plugin :derivation_endpoint, secret_key: "<YOUR_SECRET_KEY>"
 ```
 ```rb
 require "image_processing/mini_magick"
 
 class ImageUploader < Shrine
-  plugin :derivation_endpoint,
-    secret_key: "<YOUR SECRET KEY>",
-    prefix:     "derivations/image" # needs to match the mount point in routes
+  plugin :derivation_endpoint, prefix: "derivations/image" # matches mount point
 
   derivation :thumbnail do |file, width, height|
     ImageProcessing::MiniMagick
@@ -614,6 +625,13 @@ class ImageUploader < Shrine
   end
 end
 ```
+```rb
+# config/routes.rb (Rails)
+Rails.application.routes.draw do
+  # ...
+  mount ImageUploader.derivation_endpoint => "/derivations/image"
+end
+```
 
 Now we can generate URLs from attached files that will perform the desired
 processing:
@@ -658,36 +676,85 @@ For more details, see the [File Validation] guide and
 
 ## Location
 
-Shrine automatically generated random locations before uploading files. By
-default the hierarchy is flat, meaning all files are stored in the root
-directory of the storage. The [`pretty_location`][pretty_location plugin]
-plugin provides a good default hierarchy, but you can also override
-`#generate_location` with a custom implementation:
+Shrine automatically generates random locations before uploading files. By
+default, the hierarchy is flat, meaning all files are stored in the root
+directory of the storage.
+
+```
+024d9fe83bf4fafb.jpg
+768a336bf54de219.jpg
+adfaa363629f7fc5.png
+...
+```
+
+The [`pretty_location`][pretty_location plugin] plugin provides a good default
+hierarchy:
+
+```rb
+Shrine.plugin :pretty_location
+```
+```
+user/
+  564/
+    avatar/
+      aa3e0cd715.jpg
+      thumb-493g82jf23.jpg
+photo/
+  123/
+    image/
+      13f8a7bc18.png
+      thumb-9be62da67e.png
+...
+```
+
+But you can also override `Shrine#generate_location` with a custom
+implementation, for example:
 
 ```rb
 class ImageUploader < Shrine
   def generate_location(io, record: nil, derivative: nil, **)
-    type  = record.class.name.downcase if record
-    style = derivative ? "thumbs" : "originals"
-    name  = super # the default unique identifier
+    return super unless record
 
-    [type, style, name].compact.join("/")
+    table  = record.class.table_name
+    id     = record.id
+    prefix = derivative || "original"
+
+    "uploads/#{table}/#{id}/#{prefix}-#{super}"
   end
 end
 ```
-```plaintext
+```
 uploads/
   photos/
-    originals/
-      la98lda74j3g.jpg
-    thumbs/
-      95kd8kafg80a.jpg
-      ka8agiaf9gk4.jpg
+    123/
+      original-afe929b8b4.jpg
+      small-ad61f25883.jpg
+      medium-41b75c42bb.jpg
+      large-73e67abe50.jpg
+...
 ```
 
-Note that there should always be a random component in the location, so that
-the ORM dirty tracking is detected properly. Inside `#generate_location` you
-can also access the extracted metadata through the `:metadata` option.
+> There should always be a random component in the location, so that the ORM
+  dirty tracking is detected properly.
+
+The `Shrine#generate_location` method contains a lot of useful context for the
+upcoming upload:
+
+```rb
+class ImageUploader < Shrine
+  def generate_location(io, record: nil, name: nil, derivative: nil, metadata: {}, **options)
+    storage_key #=> :cache, :store, ...
+    io          #=> #<File>, #<Shrine::UploadedFile>, ...
+    record      #=> #<Photo>, #<User>, ...
+    name        #=> :image, :avatar, ...
+    derivative  #=> :small, :medium, :large, ... (derivatives plugin)
+    metadata    #=> { "filename" => "nature.jpg", "mime_type" => "image/jpeg", "size" => 18573, ... }
+    options     #=> { ... other uploader options ... }
+
+    # ...
+  end
+end
+```
 
 ## Direct uploads
 
@@ -722,7 +789,7 @@ Shrine.plugin :upload_endpoint
 # config/routes.rb (Rails)
 Rails.application.routes.draw do
   # ...
-  mount ImageUploader.upload_endpoint(:cache) => "/images/upload" # POST /images/upload
+  mount Shrine.upload_endpoint(:cache) => "/upload" # POST /upload
 end
 ```
 
@@ -832,7 +899,7 @@ resumable uploads from scratch, it includes a complete JavaScript example
 
 ## Backgrounding
 
-The [`backgrounding`][backgrounding plugin] allows you to move file promotion
+The [`backgrounding`][backgrounding plugin] plugin allows you to move file promotion
 and deletion into a background job, using the backgrounding library [of your
 choice][Backgrounding Libraries]:
 
@@ -849,7 +916,7 @@ end
 class PromoteJob
   include Sidekiq::Worker
 
-  def perform(attacher_class, record_class, record.id, name, file_data)
+  def perform(attacher_class, record_class, record_id, name, file_data)
     attacher_class = Object.const_get(attacher_class)
     record         = Object.const_get(record_class).find(record_id) # if using Active Record
 
@@ -893,6 +960,8 @@ s3 = Shrine.storages[:cache]
 s3.clear! { |object| object.last_modified < Time.now - 7*24*60*60 } # delete files older than 1 week
 ```
 
+For S3, it may be easier and cheaper to use [S3 bucket lifecycle expiration rules](http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html)  instead.
+
 ## Logging
 
 The [`instrumentation`][instrumentation plugin] plugin sends and logs events for
@@ -906,7 +975,7 @@ uploaded_file.exists?
 uploaded_file.download
 uploaded_file.delete
 ```
-```plaintext
+```
 Metadata (32ms) – {:storage=>:store, :io=>StringIO, :uploader=>Shrine}
 Upload (1523ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :io=>StringIO, :upload_options=>{}, :uploader=>Shrine}
 Exists (755ms) – {:storage=>:store, :location=>"ed0e30ddec8b97813f2c1f4cfd1700b4", :uploader=>Shrine}
@@ -943,7 +1012,6 @@ In tests you might want to tell Shrine to log only warnings:
 Shrine.logger.level = Logger::WARN
 ```
 
-[Advantages of Shrine]: https://shrinerb.com/docs/advantages
 [Creating Plugins]: https://shrinerb.com/docs/creating-plugins
 [Creating Storages]: https://shrinerb.com/docs/creating-storages
 [Direct Uploads to S3]: https://shrinerb.com/docs/direct-s3
@@ -954,24 +1022,19 @@ Shrine.logger.level = Logger::WARN
 [Using Attacher]: https://shrinerb.com/docs/attacher
 [FileSystem]: https://shrinerb.com/docs/storage/file-system
 [S3]: https://shrinerb.com/docs/storage/s3
+[Memory]: https://shrinerb.com/docs/storage/memory
+[Testing with Shrine]: https://shrinerb.com/docs/testing
 [`Shrine::UploadedFile`]: https://shrinerb.com/rdoc/classes/Shrine/UploadedFile/InstanceMethods.html
 
 [attacher]: #attacher
-[attachment]: #attachment
-[backgrounding]: #backgrounding
+[attachment]: #attaching
 [direct uploads]: #direct-uploads
 [io abstraction]: #io-abstraction
 [location]: #location
 [metadata]: #metadata
-[up front]: #processing-up-front
-[on-the-fly]: #processing-on-the-fly
-[plugin system]: #plugin-system
-[simple upload]: #simple-direct-upload
 [presigned upload]: #presigned-direct-upload
-[resumable upload]: #resumable-direct-upload
 [storage]: #storage
 [uploaded file]: #uploaded-file
-[uploading]: #uploading
 [uploader]: #uploader
 [validation]: #validation
 
@@ -1001,10 +1064,12 @@ Shrine.logger.level = Logger::WARN
 [ImageProcessing::MiniMagick]: https://github.com/janko/image_processing/blob/master/doc/minimagick.md#readme
 [ImageProcessing::Vips]: https://github.com/janko/image_processing/blob/master/doc/vips.md#readme
 [`file`]: http://linux.die.net/man/1/file
+[Down]: https://github.com/janko/down
 
 [activerecord plugin]: https://shrinerb.com/docs/plugins/activerecord
 [add_metadata plugin]: https://shrinerb.com/docs/plugins/add_metadata
 [backgrounding plugin]: https://shrinerb.com/docs/plugins/backgrounding
+[data_uri plugin]: https://shrinerb.com/docs/plugins/data_uri
 [derivation_endpoint plugin]: https://shrinerb.com/docs/plugins/derivation_endpoint
 [derivatives plugin]: https://shrinerb.com/docs/plugins/derivatives
 [determine_mime_type plugin]: https://shrinerb.com/docs/plugins/determine_mime_type