shrine 3.0.0.rc → 3.0.0

data/doc/plugins/processing.md

@@ -1,4 +1,6 @@
-# Processing
+---
+title: Processing
+---
 
 Shrine uploaders can define the `#process` method, which will get called
 whenever a file is uploaded. It is given the original file, and is expected to
@@ -65,5 +67,5 @@ uploader.process(file, action: :store) # only process
 If you want the result of processing to be multiple files, use the `versions`
 plugin.
 
-[processing]: /lib/shrine/plugins/processing.rb
+[processing]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/processing.rb
 [image_processing]: https://github.com/janko/image_processing

data/doc/plugins/rack_file.md

@@ -1,4 +1,6 @@
-# Rack File
+---
+title: Rack File
+---
 
 The [`rack_file`][rack_file] plugin enables uploaders to accept Rack uploaded
 file hashes for uploading.
@@ -7,6 +9,8 @@ file hashes for uploading.
 plugin :rack_file
 ```
 
+## Usage
+
 When a file is uploaded to your Rack application using the
 `multipart/form-data` parameter encoding, Rack converts the uploaded file to a
 hash.
@@ -33,6 +37,8 @@ user.avatar = file_hash
 attacher.assign(file_hash)
 ```
 
+## API
+
 Internally the Rack uploaded file hash will be converted into an IO object
 using `Shrine.rack_file`, which you can also use directly:
 
@@ -48,4 +54,4 @@ Note that this plugin is not needed in Rails applications, as Rails already
 wraps the Rack uploaded file hash into an `ActionDispatch::Http::UploadedFile`
 object.
 
-[rack_file]: /lib/shrine/plugins/rack_file.rb
+[rack_file]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/rack_file.rb

data/doc/plugins/rack_response.md

@@ -1,4 +1,6 @@
-# Rack Response
+---
+title: Rack Response
+---
 
 The [`rack_response`][rack_response] plugin allows you to convert an
 `UploadedFile` object into a triple consisting of status, headers, and body,
@@ -8,6 +10,8 @@ suitable for returning as a response in a Rack-based application.
 plugin :rack_response
 ```
 
+## Usage
+
 To convert a `Shrine::UploadedFile` into a Rack response, simply call
 `#to_rack_response`:
 
@@ -107,6 +111,6 @@ uploaded_file.open(
 uploaded_file.to_rack_response
 ```
 
-[rack_response]: /lib/shrine/plugins/rack_response.rb
+[rack_response]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/rack_response.rb
 [range requests]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests
 [Rack::Sendfile]: https://www.rubydoc.info/github/rack/rack/Rack/Sendfile

data/doc/plugins/recache.md

@@ -1,4 +1,6 @@
-# Re-cache
+---
+title: Re-cache
+---
 
 The [`recache`][recache] plugin allows you to process your attachment after
 validations succeed, but before the attachment is promoted. This is useful for
@@ -26,4 +28,4 @@ you're using the attacher directly, you can call it manually:
 attacher.recache if attacher.changed?
 ```
 
-[recache]: /lib/shrine/plugins/recache.rb
+[recache]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/recache.rb

data/doc/plugins/refresh_metadata.md

@@ -1,4 +1,6 @@
-# Refresh Metadata
+---
+title: Refresh Metadata
+---
 
 The [`refresh_metadata`][refresh_metadata] plugin allows you to re-extract
 metadata from an uploaded file.
@@ -66,5 +68,5 @@ Any options passed in will be forwarded to metadata extraction:
 uploaded_file.refresh_metadata!(foo: "bar") # passes `{ foo: "bar" }` options to metadata extraction
 ```
 
-[refresh_metadata]: /lib/shrine/plugins/refresh_metadata.rb
-[model]: /doc/plugins/model.md#readme
+[refresh_metadata]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/refresh_metadata.rb
+[model]: https://shrinerb.com/docs/plugins/model

data/doc/plugins/remote_url.md

@@ -1,4 +1,6 @@
-# Remote URL
+---
+title: Remote URL
+---
 
 The [`remote_url`][remote_url] plugin allows you to attach files from a remote
 location.
@@ -7,6 +9,8 @@ location.
 plugin :remote_url, max_size: 20*1024*1024
 ```
 
+## Usage
+
 The plugin will add the `#<name>_remote_url` writer to your model, which
 downloads the remote file and uploads it to temporary storage.
 
@@ -27,7 +31,7 @@ attacher.file.size              #=> 43423
 attacher.file.original_filename #=> "cool-image.png"
 ```
 
-## Downloading
+## Downloader
 
 By default, the file will be downloaded using `Down.download` from the [Down]
 gem. This will use the [Down::NetHttp] backend by default, which is a wrapper
@@ -70,6 +74,23 @@ plugin :remote_url, downloader: -> (url, **options) {
 }
 ```
 
+### Calling downloader
+
+You can call the downloader directly with `Shrine.remote_url`:
+
+```rb
+# or YourUploader.remote_url(...)
+file = Shrine.remote_url("https://example.com/image.jpg")
+file #=> #<Tempfile:...>
+```
+
+You can pass additional options as well:
+
+```rb
+# or YourUploader.remote_url(...)
+Shrine.remote_url("https://example.com/image.jpg", headers: { "Cookie" => "..." })
+```
+
 ## Uploader options
 
 Any additional options passed to `Attacher#assign_remote_url` will be forwarded
@@ -145,7 +166,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 Remote URL (1550ms) – {:remote_url=>"https://example.com/image.jpg",:download_options=>{},:uploader=>Shrine}
 ```
 
@@ -156,7 +177,7 @@ plugin :remote_url, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```
+```plaintext
 {"name":"remote_url","duration":5,"remote_url":"https://example.com/image.jpg","download_options":{},"uploader":"Shrine"}
 ```
 
@@ -166,7 +187,7 @@ Or disable logging altogether:
 plugin :remote_url, log_subscriber: nil
 ```
 
-[remote_url]: /lib/shrine/plugins/remote_url.rb
+[remote_url]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remote_url.rb
 [Down]: https://github.com/janko/down
 [Down::NetHttp]: https://github.com/janko/down#downnethttp
 [open-uri]: https://ruby-doc.org/stdlib/libdoc/open-uri/rdoc/OpenURI.html

data/doc/plugins/remove_attachment.md

@@ -1,4 +1,6 @@
-# Remove Attachment
+---
+title: Remove Attachment
+---
 
 The [`remove_attachment`][remove_attachment] plugin allows you to delete
 attachments through checkboxes on the web form.
@@ -34,4 +36,4 @@ attacher.remove = '1'
 attacher.file #=> nil
 ```
 
-[remove_attachment]: /lib/shrine/plugins/remove_attachment.rb
+[remove_attachment]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remove_attachment.rb

data/doc/plugins/remove_invalid.md

@@ -1,4 +1,6 @@
-# Remove Invalid
+---
+title: Remove Invalid
+---
 
 The [`remove_invalid`][remove_invalid] plugin automatically deletes and
 deassigns a new assigned file if it was invalid. If there was a previous file
@@ -8,4 +10,10 @@ attached, it will be assigned back.
 plugin :remove_invalid
 ```
 
-[remove_invalid]: /lib/shrine/plugins/remove_invalid.rb
+```rb
+photo.image = file # invalid file
+photo.valid?       #=> false
+photo.image        #=> nil
+```
+
+[remove_invalid]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/remove_invalid.rb

data/doc/plugins/restore_cached_data.md

@@ -1,4 +1,6 @@
-# Restore Cached Data
+---
+title: Restore Cached Data
+---
 
 The [`restore_cached_data`][restore_cached_data] plugin re-extracts metadata
 when assigning already cached files, i.e. when the attachment has been retained
@@ -10,9 +12,13 @@ extracted on the client side.
 ```rb
 plugin :restore_cached_data
 ```
+```rb
+photo.image = { "id" => "path/to/image.jpg", "storage" => "cache", "metadata" => {} }
+photo.image.metadata #=> { "size" => 4823763, "mime_type" => "image/jpeg", ... }
+```
 
 It uses the [`refresh_metadata`][refresh_metadata] plugin to re-extract
 metadata.
 
-[restore_cached_data]: /lib/shrine/plugins/restore_cached_data.rb
-[refresh_metadata]: /doc/plugins/refresh_metadata.md#readme
+[restore_cached_data]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/restore_cached_data.rb
+[refresh_metadata]: https://shrinerb.com/docs/plugins/refresh_metadata

data/doc/plugins/sequel.md

@@ -1,10 +1,12 @@
-# Sequel
+---
+title: Sequel
+---
 
 The [`sequel`][sequel] plugin adds [Sequel] integration to the attachment
 interface. It is built on top of the [`model`][model] plugin.
 
 ```rb
-plugin :sequel
+Shrine.plugin :sequel
 ```
 
 ## Attachment
@@ -71,6 +73,24 @@ photo.destroy
 photo.image.exists? #=> false
 ```
 
+#### Overriding hooks
+
+You can override any of the following attacher methods to modify callback
+behaviour:
+
+* `Attacher#sequel_before_save`
+* `Attacher#sequel_after_save`
+* `Attacher#sequel_after_destroy`
+
+```rb
+class Shrine::Attacher
+  def sequel_after_save
+    super
+    # ...
+  end
+end
+```
+
 #### Skipping Hooks
 
 If you don't want the attachment module to add any hooks to your model, you can
@@ -164,8 +184,8 @@ The following persistence methods are added to `Shrine::Attacher`:
 
 See [persistence] docs for more details.
 
-[sequel]: /lib/shrine/plugins/sequel.rb
+[sequel]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/sequel.rb
 [Sequel]: https://sequel.jeremyevans.net/
-[model]: /doc/plugins/model.md#readme
-[validation]: /doc/plugins/validation.md#readme
-[persistence]: /doc/plugins/persistence.md#readme
+[model]: https://shrinerb.com/docs/plugins/model
+[validation]: https://shrinerb.com/docs/plugins/validation
+[persistence]: https://shrinerb.com/docs/plugins/persistence

data/doc/plugins/signature.md

@@ -1,4 +1,6 @@
-# Signature
+---
+title: Signature
+---
 
 The [`signature`][signature] plugin provides the ability to calculate a hash
 from file content. This hash can be used as a checksum or just as a unique
@@ -74,7 +76,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 MIME Type (33ms) – {:io=>StringIO, :uploader=>Shrine}
 ```
 
@@ -85,7 +87,7 @@ plugin :signature, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```
+```plaintext
 {"name":"signature","duration":24,"io":"#<StringIO:0x00007fb7c5b08b80>","uploader":"Shrine"}
 ```
 
@@ -95,4 +97,4 @@ Or disable logging altogether:
 plugin :signature, log_subscriber: nil
 ```
 
-[signature]: /lib/shrine/plugins/signature.rb
+[signature]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/signature.rb

data/doc/plugins/store_dimensions.md

@@ -1,4 +1,6 @@
-# Store Dimensions
+---
+title: Store Dimensions
+---
 
 The [`store_dimensions`][store_dimensions] plugin extracts dimensions of
 uploaded images and stores them into the metadata hash (by default it uses the
@@ -108,7 +110,7 @@ following payload:
 
 A default log subscriber is added as well which logs these events:
 
-```
+```plaintext
 Image Dimensions (108ms) – {:io=>File, :uploader=>Shrine}
 ```
 
@@ -119,7 +121,7 @@ plugin :store_dimensions, log_subscriber: -> (event) {
   Shrine.logger.info JSON.generate(name: event.name, duration: event.duration, **event.payload)
 }
 ```
-```
+```plaintext
 {"name":"image_dimensions","duration":114,"io":"#<File:0x00007fc445371d90>","uploader":"Shrine"}
 ```
 
@@ -129,7 +131,7 @@ Or disable logging altogether:
 plugin :store_dimensions, log_subscriber: nil
 ```
 
-[store_dimensions]: /lib/shrine/plugins/store_dimensions.rb
+[store_dimensions]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/store_dimensions.rb
 [fastimage]: https://github.com/sdsykes/fastimage
 [mini_magick]: https://github.com/minimagick/minimagick
 [ruby-vips]: https://github.com/libvips/ruby-vips

data/doc/plugins/tempfile.md

@@ -1,4 +1,6 @@
-# Tempfile
+---
+title: Tempfile
+---
 
 The [`tempfile`][tempfile] plugin makes it easier to reuse a single copy of an
 uploaded file on disk.
@@ -39,4 +41,4 @@ when the given IO object is an open `UploadedFile`. Since `Shrine.with_file` is
 typically called on the `Shrine` class directly, it's recommended to load this
 plugin globally.
 
-[tempfile]: /lib/shrine/plugins/tempfile.rb
+[tempfile]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/tempfile.rb

data/doc/plugins/upload_endpoint.md

@@ -1,4 +1,6 @@
-# Upload Endpoint
+---
+title: Upload Endpoint
+---
 
 The [`upload_endpoint`][upload_endpoint] plugin provides a Rack endpoint which
 accepts file uploads and forwards them to specified storage. On the client side
@@ -8,6 +10,8 @@ it's recommended to use [Uppy] for asynchronous uploads.
 plugin :upload_endpoint
 ```
 
+## Setup
+
 The plugin adds a `Shrine.upload_endpoint` method which, given a storage
 identifier, returns a Rack application that accepts multipart POST requests,
 and uploads received files to the specified storage. You can run this Rack
@@ -173,5 +177,5 @@ and the endpoint will automatically use it to verify the uploaded data.
 
 If the checksums don't match, a `460 Checksum Mismatch` response is returned.
 
-[upload_endpoint]: /lib/shrine/plugins/upload_endpoint.rb
+[upload_endpoint]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/upload_endpoint.rb
 [Uppy]: https://uppy.io

data/doc/plugins/upload_options.md

@@ -1,4 +1,6 @@
-# Upload Options
+---
+title: Upload Options
+---
 
 The [`upload_options`][upload_options] plugin allows you to automatically pass
 additional upload options to storage on every upload:
@@ -11,8 +13,8 @@ Keys are names of the registered storages, and values are either hashes or
 blocks.
 
 ```rb
-plugin :upload_options, store: -> (io, context) do
-  if [:original, :thumb].include?(context[:version])
+plugin :upload_options, store: -> (io, **options) do
+  if options[:derivative]
     { acl: "public-read" }
   else
     { acl: "private" }
@@ -27,4 +29,4 @@ the uploader.
 uploader.upload(file, upload_options: { acl: "public-read" })
 ```
 
-[upload_options]: /lib/shrine/plugins/upload_options.rb
+[upload_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/upload_options.rb

data/doc/plugins/url_options.md

@@ -1,4 +1,6 @@
-# URL Options
+---
+title: URL Options
+---
 
 The [`url_options`][url_options] plugin allows you to specify
 URL options that will be applied by default for uploaded files of specified
@@ -22,4 +24,4 @@ In both cases the default options are merged with options passed to
 `UploadedFile#url`, and the latter will always have precedence over default
 options.
 
-[url_options]: /lib/shrine/plugins/url_options.rb
+[url_options]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/url_options.rb

data/doc/plugins/validation.md

@@ -1,4 +1,6 @@
-# Validation
+---
+title: Validation
+---
 
 The [`validation`][validation] plugin provides a framework for validating
 attached files. For some useful validators, see the
@@ -8,6 +10,8 @@ attached files. For some useful validators, see the
 plugin :validation
 ```
 
+## Usage
+
 The `Attacher.validate` method is used to register a validation block, which
 is called on attachment:
 
@@ -79,5 +83,5 @@ You can also skip validation by passing `validate: false`:
 attacher.assign(file, validate: false) # skips validation
 ```
 
-[validation]: /lib/shrine/plugins/validation.rb
-[validation_helpers]: /doc/plugins/validation_helpers.md#readme
+[validation]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/validation.rb
+[validation_helpers]: https://shrinerb.com/docs/plugins/validation_helpers