shrine 2.11.0 → 2.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e062b548ed3da3330604b991144e1fa8bb44c547be9d68f04994056e123c3d7f
-  data.tar.gz: e4c52f36474a8a66ed3270d70b91ac4302ef0a1c60fc88381bcdfa037ef8c434
+  metadata.gz: e4876f91bcf2a7fc1c06f6eba68fda62e450a6363f0948387e91f48988a0b295
+  data.tar.gz: 514cd9b743ae1d574ba60f16d842a9c3dd14190b56091bd6df1f45d244c9ad7e
 SHA512:
-  metadata.gz: 3ab3db221bd573ef0d7fcdd3a766a9e93b7b384cadb37668fc6406977875c584caae77eaae01ba8e20902a70e75d2d7218c90f54215db6b47288fe43b7a3857a
-  data.tar.gz: 64198d22c129df0cc41e602108fca768d141f4223b806e2272b52e15991e0895b14ae9dbb555e7f3e391840b4c0cbd0dc515d1e8a747d8572c7181af4077bda9
+  metadata.gz: 6132a5c6c94a7913b1093af118870ac3b9e7e7a35fffabc6e2aec7d58884cad5b3020a7500d755907b7e456e73ce4ba618443bd3a3013ffb0e9ed57149f500f3
+  data.tar.gz: 2e788af689a199e722eec66caedf6eb263fe6f2854fa039cc3c55b20d937faf18ee0bd758cb1e1b9ecb774a09c8e9f7dbe366ea143f4992129e500cc9f10a9ba

data/CHANGELOG.md

@@ -1,3 +1,31 @@
+## 2.12.0 (2018-08-22)
+
+* Ignore nil values when assigning files from a remote URL (@janko-m)
+
+* Ignore nil values when assigning files from a data URI (@GeekOnCoffee)
+
+* Raise `Shrine::Error` when child process failed to be spawned in `:file` MIME type analyzer (@hmistry)
+
+* Use the appropriate unit in error messages of filesize validators in `validation_helpers` plugin (@hmistry)
+
+* Fix subclassing not inheriting storage resolvers from superclass in `dynamic_storage` plugin (@janko-m)
+
+* Un-deprecate assigning cached versions (@janko-m)
+
+* Add `Attacher#assign_remote_url` which allows dynamically passing downloader options (@janko-m)
+
+* Deprecate `:storages` option in `download_endpoint` plugin in favour of `UploadedFile#download_url` (@janko-m)
+
+* Add `:redirect` option to `download_endpoint` plugin for redirecting to the uploaded file (@janko-m)
+
+* Fix encoding issues when uploading IO object with unknown size to S3 (@janko-m)
+
+* Accept additional `File.open` arguments in `FileSystem#open` (@janko-m)
+
+* Add `:rewindable` option to `S3#open` for disabling caching of read content to disk (@janko-m)
+
+* Make `UploadedFile#open` always open a new IO object and close the previous one (@janko-m)
+
 ## 2.11.0 (2018-04-28)
 
 * Add `Shrine.with_file` for temporarily converting an IO-like object into a file (@janko-m)

data/README.md

@@ -9,7 +9,7 @@ Shrine is a toolkit for file attachments in Ruby applications. Some highlights:
 * **Flexible processing** – generate thumbnails with [ImageMagick] or [libvips] using the [ImageProcessing][image_processing] gem
 * **Metadata validation** – [validate files][validation_helpers plugin] based on [extracted metadata][Extracting Metadata]
 * **Direct uploads** – upload asynchronously [to your app][upload_endpoint plugin] or [to the cloud][presign_endpoint plugin] using [Uppy]
-* **Resumable uploads** – make large file uploads [resumable][tus] by pointing [Uppy][uppy tus plugin] to a [resumable endpoint][tus-ruby-server]
+* **Resumable uploads** – make large file uploads [resumable][tus] by pointing [Uppy][uppy tus] to a [resumable endpoint][tus-ruby-server]
 * **Background jobs** – built-in support for [background processing][backgrounding plugin] that supports [any backgrounding library][backgrounding libraries]
 
 If you're curious how it compares to other file attachment libraries, see the [Advantages of Shrine].
@@ -17,6 +17,7 @@ If you're curious how it compares to other file attachment libraries, see the [A
 ## Resources
 
 - Documentation: [shrinerb.com](https://shrinerb.com)
+- Demo code: [Roda][roda demo] / [Rails][rails demo]
 - Source: [github.com/shrinerb/shrine](https://github.com/shrinerb/shrine)
 - Bugs: [github.com/shrinerb/shrine/issues](https://github.com/shrinerb/shrine/issues)
 - Help & Discussion: [groups.google.com/group/ruby-shrine](https://groups.google.com/forum/#!forum/ruby-shrine)
@@ -81,7 +82,7 @@ uploads][direct S3 uploads guide].
 
 ```rb
 # with Forme:
-Forme.form(@photo, action: "/photos", method: "post", enctype: "multipart/form-data") do |f|
+form @photo, action: "/photos", enctype: "multipart/form-data" do |f|
   f.input :image, type: :hidden, value: @photo.cached_image_data
   f.input :image, type: :file
   f.button "Create"
@@ -140,10 +141,10 @@ gem "aws-sdk-s3", "~> 1.2" # for AWS S3 storage
 require "shrine/storage/s3"
 
 s3_options = {
+  bucket:            "my-bucket", # required
   access_key_id:     "abc",
   secret_access_key: "xyz",
   region:            "my-region",
-  bucket:            "my-bucket",
 }
 
 Shrine.storages = {
@@ -503,16 +504,17 @@ class ImageUploader < Shrine
   plugin :delete_raw # delete processed files after uploading
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::MiniMagick.source(original)
+    versions = { original: io } # retain original
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+    io.download do |original|
+      pipeline = ImageProcessing::MiniMagick.source(original)
 
-    original.close!
+      versions[:large]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: io, large: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```
@@ -696,9 +698,10 @@ demo app which implements multiple uploads directly to S3.
 ### Resumable uploads
 
 When your app is dealing with large uploads (e.g. videos), keep in mind that it
-can be challening for your users to upload these large files to your app,
-depending on their internet connection. If the connection breaks at any point
-during uploading, the upload needs to be restarted from the beginning.
+can be challening for your users to upload these large files to your app. Many
+users might not have a great internet connection, and if it happens to break at
+any point during uploading, they would need to restart the upload from the
+beginning.
 
 Luckily, there is a solution for this. **[Tus.io][tus]** is an open protocol
 for resumable file uploads, which enables the client and the server to achieve
@@ -706,11 +709,11 @@ reliable file uploads even on unstable connections, by enabling the upload to
 be resumed in case of interruptions, even after the browser was closed or the
 device was shut down.
 
-On the client side you can use [Uppy][uppy tus plugin] with [tus-js-client],
-have it upload files to a [tus-ruby-server], and finally attach the uploaded
-files with the help of [shrine-tus]. See [this walkthrough][resumable uploads
-walkthrough] that adds resumable uploads from scratch, as well as the [Roda
-demo][resumable demo] for a complete example.
+On the client side you can use [Uppy][uppy tus] with [tus-js-client], have it
+upload files to a [tus-ruby-server], and finally attach the uploaded files with
+the help of [shrine-tus]. See [this walkthrough][resumable uploads walkthrough]
+that adds resumable uploads from scratch, as well as the [Roda demo][resumable
+demo] for a complete example.
 
 ## Backgrounding
 
@@ -872,7 +875,7 @@ The gem is available as open source under the terms of the [MIT License].
 [presign_endpoint plugin]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/PresignEndpoint.html
 [Uppy]: https://uppy.io
 [tus]: https://tus.io
-[uppy tus plugin]: https://uppy.io/docs/tus/
+[uppy tus]: https://uppy.io/docs/tus/
 [tus-ruby-server]: https://github.com/janko-m/tus-ruby-server
 [backgrounding plugin]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/Backgrounding.html
 [Advantages of Shrine]: https://shrinerb.com/rdoc/files/doc/advantages_md.html
@@ -885,14 +888,14 @@ The gem is available as open source under the terms of the [MIT License].
 [Extracting Metadata]: https://shrinerb.com/rdoc/files/doc/metadata_md.html
 [File Processing]: https://shrinerb.com/rdoc/files/doc/processing_md.html
 [File Validation]: https://shrinerb.com/rdoc/files/doc/validation_md.html
-[direct uploads walkthrough]: https://gist.github.com/janko-m/9aea154d72eb85b1fbfa16e1d77946e5#adding-direct-uploads-to-a-roda--sequel-app-with-shrine
-[direct S3 uploads walkthrough]: https://gist.github.com/janko-m/9aea154d72eb85b1fbfa16e1d77946e5#adding-direct-s3-uploads-to-a-roda--sequel-app-with-shrine
+[direct uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-App-Uploads
+[direct S3 uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads<Paste>
 [direct S3 uploads guide]: https://shrinerb.com/rdoc/files/doc/direct_s3_md.html
 [roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
 [rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
 [tus-js-client]: https://github.com/tus/tus-js-client
 [shrine-tus]: https://github.com/shrinerb/shrine-tus
-[resumable uploads walkthrough]: https://gist.github.com/janko-m/f05188205cb9af75a27ead78d068b5d3#adding-resumable-uploads-to-a-roda--sequel-app-with-shrine
+[resumable uploads walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Resumable-Uploads
 [resumable demo]: https://github.com/shrinerb/shrine-tus-demo
 [backgrounding libraries]: https://github.com/shrinerb/shrine/wiki/Backgrounding-libraries
 [S3 lifecycle Console]: http://docs.aws.amazon.com/AmazonS3/latest/UG/lifecycle-configuration-bucket-no-versioning.html

data/doc/advantages.md

@@ -185,18 +185,23 @@ end
 ### On-the-fly processing
 
 Shrine is primarily designed for processing files on upload, since that's
-applicable to all types of files, while on-the-fly processing that [Dragonfly],
-[Refile], and [Active Storage] offer makes sense only for images.
+applicable to all types of files, though on-the-fly processing that [Dragonfly],
+[Refile], and [Active Storage] can make managing image thumbnails a lot easier.
 
 However, there are many specialized solutions that provide on-the-fly
 processing functionality, both open source and commercial, and it's fairly easy
 to apply them to files uploaded by Shrine.
 
 ```rb
-Dragonfly.app
-  .fetch_url(photo.image_url) # image uploaded by Shrine
-  .thumb("800x800")
-  .url #=> "/attachments/W1siZnUiLCJodHRwOi8vd3d3LnB1YmxpY2RvbWFpbn..."
+def thumbnail_url(uploaded_file, dimensions)
+  Dragonfly.app
+    .fetch(uploaded_file.url)
+    .thumb(dimensions)
+    .url
+end
+```
+```rb
+thumbnail_url(photo.image, "500x400") #=> "/attachments/W1siZnUiLCJodHRwOi8vd3d3LnB1YmxpY2RvbWFpbn..."
 ```
 
 ## Metadata
@@ -265,10 +270,13 @@ to upload them to your app, especially on flaky internet connections. With
 a simple HTTP request, should there be any interruption during the execution,
 the whole upload needs to be retried from the beginning.
 
-To fix this problem, the community has created an open HTTP-based protocol for
-resumable uploads – **[tus]**. There even exists a [Ruby server
-implementation][tus-ruby-server] for this protocol ready to use. Finally, for
-attaching files uploaded via the tus protocol you can use the [shrine-tus] gem.
+To fix this problem, [Transloadit] company has created an open HTTP-based
+protocol for resumable uploads – **[tus]**. To use it, you can choose from
+numerous client and server [implementations][tus implementations] of the
+protocol. In this case you would typically have a [JavaScript
+client][tus-js-client] (via [Uppy][uppy tus]) upload to a [Ruby
+server][tus-ruby-server], and then attach uploaded files using the handy
+[Shrine integration][shrine-tus].
 
 ## Security
 
@@ -340,7 +348,11 @@ limit.
 [background job]: http://shrinerb.com/rdoc/classes/Shrine/Plugins/Backgrounding.html
 [backgrounding libraries]: https://github.com/shrinerb/shrine/wiki/Backgrounding-libraries
 [Down streaming]: https://github.com/janko-m/down#streaming
+[Transloadit]: https://transloadit.com
 [tus]: https://tus.io
+[tus implementations]: https://tus.io/implementations.html
+[tus-js-client]: https://github.com/tus/tus-js-client
+[uppy tus]: https://uppy.io/docs/tus/
 [tus-ruby-server]: https://github.com/janko-m/tus-ruby-server
 [shrine-tus]: https://github.com/shrinerb/shrine-tus
 [ImageTragick]: https://imagetragick.com

data/doc/carrierwave.md

@@ -19,15 +19,17 @@ CarrierWave.configure do |config|
     provider:              "AWS",
     aws_access_key_id:     "abc",
     aws_secret_access_key: "xyz",
+    region:                "eu-west-1",
   }
   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",
+  bucket:            "my-bucket",
+  access_key_id:     "abc",
+  secret_access_key: "xyz",
+  region:            "eu-west-1",
 )
 ```
 
@@ -97,16 +99,17 @@ class ImageUploader < Shrine
   plugin :versions
 
   process(:store) do |io, context|
-    original = io.download
-    pipeline = ImageProcessing::MiniMagick.source(original)
+    versions = {}
 
-    size_800 = pipeline.resize_to_limit!(800, 800)
-    size_500 = pipeline.resize_to_limit!(500, 500)
-    size_300 = pipeline.resize_to_limit!(300, 300)
+    io.download do |original|
+      pipeline = ImageProcessing::MiniMagick.source(original)
 
-    original.close!
+      versions[:original]  = pipeline.resize_to_limit!(800, 800)
+      versions[:medium] = pipeline.resize_to_limit!(500, 500)
+      versions[:small]  = pipeline.resize_to_limit!(300, 300)
+    end
 
-    { original: size_800, medium: size_500, small: size_300 }
+    versions # return the hash of processed files
   end
 end
 ```

data/doc/creating_storages.md

@@ -52,7 +52,7 @@ end
 ```
 
 Unless you're already using a Ruby SDK, it's recommended to use [HTTP.rb] for
-uploading. It accepts any IO object that responds to `#read` (not just file
+uploading. It accepts any IO object that implements `IO#read` (not just file
 objects), and it streams the request body directly to the TCP socket, both for
 raw and multipart uploads, making it suitable for large uploads.
 

data/doc/direct_s3.md

@@ -35,9 +35,9 @@ gem "aws-sdk-s3", "~> 1.2"
 require "shrine/storage/s3"
 
 s3_options = {
+  bucket:            "<YOUR BUCKET>", # required
   access_key_id:     "<YOUR KEY>",
   secret_access_key: "<YOUR SECRET>",
-  bucket:            "<YOUR BUCKET>",
   region:            "<REGION>",
 }
 
@@ -171,12 +171,12 @@ presigned_data = Shrine.storages[:cache].presign(
   success_action_redirect: new_album_url
 )
 
-Forme.form(action: presigned_data[:url], method: "post", enctype: "multipart/form-data") do |f|
+form action: presigned_data[:url], method: "post", enctype: "multipart/form-data" do |f|
   presigned_data[:fields].each do |name, value|
     f.input :hidden, name: name, value: value
   end
   f.input :file, name: "file"
-  f.input :submit, value: "Upload"
+  f.button "Submit"
 end
 ```
 
@@ -206,7 +206,7 @@ cached_file = {
   metadata: {},
 }
 
-Forme.form(@album, action: "/albums", method: "post") do |f|
+form @album, action: "/albums" do |f|
   f.input :image, type: :hidden, value: cached_file.to_json
   f.button "Save"
 end
@@ -362,8 +362,8 @@ setup] guide.
 
 [`Shrine::Storage::S3#presign`]: https://shrinerb.com/rdoc/classes/Shrine/Storage/S3.html#method-i-presign
 [`Aws::S3::PresignedPost`]: http://docs.aws.amazon.com/sdk-for-ruby/v3/api/Aws/S3/Bucket.html#presigned_post-instance_method
-[direct S3 upload walkthrough]: https://gist.github.com/janko-m/9aea154d72eb85b1fbfa16e1d77946e5#adding-direct-s3-uploads-to-a-roda--sequel-app-with-shrine
-[checksum walkthrough]: https://gist.github.com/janko-m/4470b5fb0737c5c1f8bcfe8cdc3fd296#using-checksums-to-verify-integrity-of-direct-uploads-with-shrine--uppy
+[direct S3 upload walkthrough]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads
+[checksum walkthrough]: https://github.com/shrinerb/shrine/wiki/Using-Checksums-in-Direct-Uploads
 [roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
 [rails demo]: https://github.com/erikdahlstrand/shrine-rails-example
 [Uppy]: https://uppy.io

data/doc/multiple_files.md

@@ -1,52 +1,78 @@
 # Multiple Files
 
-There are often times when you want to allow users to attach multiple files to
-a single resource. Some file attachment libraries provide a special interface
-for multiple attachments, but Shrine doesn't come with one, because it's much
-more robust and flexible to implement this using your ORM directly.
-
-The idea is to create a new table, and attach each uploaded file to a separate
-record on that table, while having a "many-to-one" relationship with the main
-table. That way a database record from the main table can implicitly have
+There are times when you want to allow users to attach multiple files to a
+single resource, like an album having many photos or a playlist having many
+songs. Some file attachment libraries provide a special interface for multiple
+attachments, but Shrine doesn't have one, because it's more flexible to use
+the "nested attributes" feature of your ORM directly to implement this.
+
+The basic idea is to create a separate table that will have a many-to-one
+relationship with the main table, and files will be attached on the records in
+the new table. That way each record from the main table can implicitly have
 multiple attachments through the associated records.
 
 ```
-album
+album1
   photo1
     - attachment1
   photo2
     - attachment2
   photo3
     - attachment3
+
+album2
+  photo4
+    - attachment4
+  photo5
+    - attachment5
+
+...
+```
+
+To illustrate, this code will create an album with three photos using nested
+attributes:
+
+```rb
+Album.create(
+  title: "My Album",
+  photos_attributes: [
+    { image: File.open("image1.jpg", "rb") },
+    { image: File.open("image2.jpg", "rb") },
+    { image: File.open("image3.jpg", "rb") },
+  ]
+)
 ```
 
-This design gives you great flexibility, allowing you to support:
+This design gives you the greatest flexibility, allowing you to support:
 
 * adding new attachments
 * updating existing attachments
 * removing existing attachments
-* sorting attachments
-* having additional fields on attachments (captions, votes, number of downloads etc.)
+* sorting attachments (via a separate position column)
+* having additional fields on attachments (e.g. captions, votes, number of downloads etc.)
+* expanding this to be "many-to-many" relation (e.g. create different playlists from a list of songs, etc)
 * ...
 
-If you're using Sequel or ActiveRecord, the easiest way to implement this is
-via nested attributes, which you would in general use for any dynamic
-"one-to-many" association. The examples will be using Sequel, but with
-ActiveRecord it's very similar, here are the docs:
+## How to Implement
 
-* [`Sequel::Model.nested_attributes`]
-* [`ActiveRecord::Base.accepts_nested_attributes_for`]
-
-For simplicity, for the rest of this guide we will assume that we have "albums"
-that can have multiple "photos".
+For the rest of this guide, we will use the example where we have "albums" that
+can have multiple "photos" in it. The main table is the albums table and the
+files (or attachments) table will be the photos table.
 
-## 1. Attachments table
+### 1. Create the main resource and attachment table
 
-Let's create a table for our attachments, and add a foreign key for the main table:
+Let's create a table for the main resource and attachments, and add a foreign
+key in the attachment table for the main table:
 
 ```rb
+# Sequel
 Sequel.migration do
   change do
+    create_table :albums do
+      primary_key :id
+      column      :title, :text
+    end
+
     create_table :photos do
       primary_key :id
       foreign_key :album_id, :albums
@@ -54,63 +80,181 @@ Sequel.migration do
     end
   end
 end
+
+# Active Record
+class CreateAlbumsAndPhotos < ActiveRecord::Migration
+  def change
+    create_table :albums do |t|
+      t.string     :title
+      t.timestamps
+    end
+
+    create_table :photos do |t|
+      t.references :album, foreign_key: true
+      t.text       :image_data
+      t.timestamps
+    end
+  end
+end
 ```
 
-In our new model we can create a Shrine attachment attribute:
+In the Photo model, create a Shrine attachment attribute named `image`
+(`:image` matches the `_data` column prefix above):
 
 ```rb
+# Sequel
 class Photo < Sequel::Model
   include ImageUploader::Attachment.new(:image)
 end
+
+# Active Record
+class Photo < ActiveRecord::Base
+  include ImageUploader::Attachment.new(:image)
+end
 ```
 
-## 2. Nested attributes
+### 2. Declare nested attributes
 
-In our main model we can now declare the association to the new table, and
-allow it to directly accept attributes for the associated records:
+Using nested attributes is the easiest way to implement any dynamic
+"one-to-many" association. In the Album model we'll declare a one-to-many
+relationship to the photos table, and allow it to directly accept attributes
+for the associated photo records by enabling nested attributes:
 
 ```rb
+# Sequel
 class Album < Sequel::Model
   one_to_many :photos
+  plugin :association_dependencies, photos: :destroy # destroy photos when album is destroyed
+
+  plugin :nested_attributes
+  nested_attributes :photos, destroy: true
+end
+
+# Active Record
+class Album < ActiveRecord::Base
+  has_many :photos, dependent: :destroy
+  accepts_nested_attributes_for :photos, allow_destroy: true
+end
+```
+
+Documentation on nested attributes:
+
+* [`Sequel::Model.nested_attributes`]
+* [`ActiveRecord::Base.accepts_nested_attributes_for`]
+
+### 3. Create the View
 
-  plugin :nested_attributes # load the plugin
-  nested_attributes :photos
+Create a form like you normally do to create the album. To this form we'll add
+a file field for selecting photos, which will have `multiple` attribute to
+allow the user to select multiple files. We'll also display nested fields for
+already created photos, so that the same form can be used for updating the
+album/photos as well (they will be submitted under the
+`album[photos_attributes]` parameter).
+
+```rb
+# with Forme:
+form @album, action: "/photos", enctype: "multipart/form-data" do |f|
+  f.input :title
+  f.subform :photos do # adds new `album[photos_attributes]` parameter
+    f.input :image,   type: :hidden, value: f.obj.cached_image_data
+    f.input :image,   type: :file
+    f.input :_delete, type: :checkbox unless f.obj.new?
+  end
+  f.input "files[]", type: :file, attr: { multiple: true }, obj: nil
+  f.button "Create"
+end
+
+# with Rails form builder:
+form_for @album do |f|
+  f.text_field :title
+  f.fields_for :photos do |p| # adds new `album[photos_attributes]` parameter
+    p.hidden_field :image, value: p.object.cached_image_data
+    p.file_field   :image
+    p.check_box    :_destroy unless p.object.new_record?
+  end
+  file_field_tag "files[]", multiple: true
+  f.submit "Create"
 end
 ```
 
-## 3. View
+In your controller you should still be able to assign all the attributes to the
+album, just remember to whitelist the new parameter for the nested attributes,
+in this case `photos_attributes`.
 
-In order to allow the user to select multiple files in the form, we just need
-to add the `multiple` attribute to the file field.
+### 4. Direct Upload
+
+On the client side, you can asynchronously upload each of the files to a direct
+upload endpoint as soon as they're selected. There are two methods of
+implementing direct uploads: upload to your app using the [`upload_endpoint`]
+plugin or upload to directly to storage like S3 using the [`presign_endpoint`]
+plugin. It's recommended to use [Uppy] to handle the uploads on the client side.
+
+Once files are uploaded asynchronously, you can dynamically insert photo
+attachment fields for the `image` attribute to the form filled with uploaded
+file data, so that the corresponding photo records are automatically created
+after form submission. The hidden attachment fields should contain uploaded
+file data in JSON format, just like when doing single direct uploads. The
+attachment field names should be namespaced according to the convention that
+the nested attributes feature expects. In this case it should be
+`album[photos_attributes][<idx>]`, where `<idx>` is any incrementing integer
+(e.g. you can use the current UNIX timestamp).
 
 ```rb
-f.input :file, name: :file, multiple: true
-# <input type="file" name="file" multiple />
+# naming format in which photos fields should be generated and submitted
+album[photos_attributes][11111][image] = '{"id":"38k25.jpg","storage":"cache","metadata":{...}}'
+album[photos_attributes][29323][image] = '{"id":"sg0fg.jpg","storage":"cache","metadata":{...}}'
+album[photos_attributes][34820][image] = '{"id":"041jd.jpg","storage":"cache","metadata":{...}}'
+# ...
 ```
 
-On the client side you can then asynchronously upload each of the selected
-files to a direct upload endpoint. See documenation for the `upload_endpoint`
-and `presign_endpoint` plugins, as well as the [Direct Uploads to S3] guide for
-more details.
+See the walkthroughs for setting up simple [direct app uploads] and
+[direct S3 uploads], and the [Roda][roda demo] or [Rails][rails demo] demo app
+which implements multiple file uploads.
+
+### 5. Adding Validations
 
-After each upload finishes, you can generate a nested hash for the new
-associated record, and write the uploaded file JSON to the attachment field:
+You can add file validations to the `Photo` model using the
+`validation_helpers` plugin. You just need to make sure that your ORM is
+configured to automatically validate associated records.
 
 ```rb
-album[photos_attributes][0][image] = '{"id":"38k25.jpg","storage":"cache","metadata":{...}}'
-album[photos_attributes][1][image] = '{"id":"sg0fg.jpg","storage":"cache","metadata":{...}}'
-album[photos_attributes][2][image] = '{"id":"041jd.jpg","storage":"cache","metadata":{...}}'
+class ImageUploader < Shrine
+  plugin :validation_helpers
+  plugin :determine_mime_type
+
+  Attacher.validate do
+    validate_max_size 10*1024*1024
+    validate_mime_type_inclusion %w[image/jpeg image/png]
+  end
+end
+```
+```rb
+# Sequel
+class Album < Sequel::Model
+  # ... (nested_attributes already enables validating associated photos) ...
+end
+
+# ActiveRecord
+class Album < ActiveRecord::Base
+  # ...
+  validates_associated :photos
+end
 ```
 
-Once you submit this to the app, the ORM's nested attributes behaviour will
-create the associated records, and assign the Shrine attachments.
+### 6. Conclusion
 
-Now you can manage adding new, or updating and deleting existing attachments,
-just by using your ORM's nested attributes behaviour, the same way that you
-would do with any other dynamic one-to-many association. The callbacks that
-are added by including the Shrine module to the associated model will
-automatically take care of the attachment management.
+Now we have a simple interface for accepting multiple attachments, which
+internally uses nested attributes to create multiple associated records, each
+with a single attachment. After creation you can also add new attachments, or
+update and delete existing ones, which the nested attributes feature gives you
+for free.
 
 [`Sequel::Model.nested_attributes`]: http://sequel.jeremyevans.net/rdoc-plugins/classes/Sequel/Plugins/NestedAttributes.html
 [`ActiveRecord::Base.accepts_nested_attributes_for`]: http://api.rubyonrails.org/classes/ActiveRecord/NestedAttributes/ClassMethods.html
-[Direct Uploads to S3]: https://shrinerb.com/rdoc/files/doc/direct_s3_md.html
+[`upload_endpoint`]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/UploadEndpoint.html
+[`presign_endpoint`]: https://shrinerb.com/rdoc/classes/Shrine/Plugins/PresignEndpoint.html
+[Uppy]: https://uppy.io
+[direct app uploads]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-App-Uploads
+[direct S3 uploads]: https://github.com/shrinerb/shrine/wiki/Adding-Direct-S3-Uploads
+[roda demo]: https://github.com/shrinerb/shrine/tree/master/demo
+[rails demo]: https://github.com/erikdahlstrand/shrine-rails-example