shrine 2.19.3 → 3.6.0

data/doc/plugins/data_uri.md

@@ -1,4 +1,6 @@
-# Data URI
+---
+title: Data URI
+---
 
 The [`data_uri`][data_uri] plugin enables you to upload files as [data URIs].
 This plugin is useful for example when using [HTML5 Canvas].
@@ -7,23 +9,24 @@ This plugin is useful for example when using [HTML5 Canvas].
 plugin :data_uri
 ```
 
-If your attachment is called "avatar", this plugin will add `#avatar_data_uri`
-and `#avatar_data_uri=` methods to your model.
+## Usage
 
-```rb
-user.avatar #=> nil
-user.avatar_data_uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
-user.avatar #=> #<Shrine::UploadedFile>
+The plugin will add the `#<name>_data_uri` writer to your model, which parses
+the given data URI string and uploads it to temporary storage:
 
-user.avatar.mime_type         #=> "image/png"
-user.avatar.size              #=> 43423
+```rb
+photo.image_data_uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
+photo.image.mime_type #=> "image/png"
+photo.image.size      #=> 43423
 ```
 
-You can also use `#data_uri=` and `#data_uri` methods directly on the
-`Shrine::Attacher` (which the model methods just delegate to):
+If you're using `Shrine::Attacher` directly, you can use
+`Attacher#assign_data_uri`:
 
 ```rb
-attacher.data_uri = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA"
+attacher.assign_data_uri("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA")
+attacher.file.mime_type #=> "image/png"
+attacher.file.size      #=> 43423
 ```
 
 ## Errors
@@ -36,13 +39,13 @@ plugin :data_uri, error_message: "data URI was invalid"
 plugin :data_uri, error_message: ->(uri) { I18n.t("errors.data_uri_invalid") }
 ```
 
-## Upload options
+## Uploader options
 
-If you want to pass additional options for `Shrine#upload`, you can use
-`#assign_data_uri`:
+Any options passed to `Attacher#assign_data_uri` will be forwarded to
+`Attacher#assign` (and `Shrine#upload`):
 
 ```rb
-attacher.assign_data_uri(uri, metadata: { "mime_type" => "text/plain" })
+attacher.assign_data_uri(uri, metadata: { "filename" => "nature.jpg" })
 ```
 
 ## File extension
@@ -56,16 +59,14 @@ load the `infer_extension` plugin to infer it from the MIME type.
 plugin :infer_extension
 ```
 
-## API
-
-### `Shrine.data_uri`
+## Parsing data URI
 
 If you just want to parse the data URI and create an IO object from it, you can
 do that with `Shrine.data_uri`. If the data URI cannot be parsed, a
 `Shrine::Plugins::DataUri::ParseError` will be raised.
 
 ```rb
-# or YourUploader.data_uri("...")
+# or YourUploader.data_uri(...)
 io = Shrine.data_uri("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA")
 io.content_type #=> "image/png"
 io.size         #=> 21
@@ -90,7 +91,7 @@ io = Shrine.data_uri("data:,content", filename: "foo.txt")
 io.original_filename #=> "foo.txt"
 ```
 
-### `UploadedFile#data_uri` and `UploadedFile#base64`
+## Generating data URI
 
 This plugin also adds `UploadedFile#data_uri` method, which returns a
 base64-encoded data URI of the file content, and `UploadedFile#base64`, which
@@ -143,6 +144,6 @@ Or disable logging altogether:
 plugin :data_uri, log_subscriber: nil
 ```
 
-[data_uri]: /lib/shrine/plugins/data_uri.rb
+[data_uri]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/data_uri.rb
 [data URIs]: https://tools.ietf.org/html/rfc2397
 [HTML5 Canvas]: https://developer.mozilla.org/en-US/docs/Web/API/Canvas_API

data/doc/plugins/default_storage.md

@@ -1,19 +1,45 @@
-# Default Storage
+---
+title: Default Storage
+---
 
-The [`default_storage`][default_storage] plugin enables you to change which
-storages are going to be used for this uploader's attacher (the default is
-`:cache` and `:store`).
+The [`default_storage`][default_storage] plugin allows you to change the
+default temporary and permanent storage a `Shrine::Attacher` object will use
+(the default is `:cache` and `:store`).
 
 ```rb
-plugin :default_storage, cache: :special_cache, store: :special_store
+plugin :default_storage, cache: :other_cache, store: :other_store
 ```
 
-You can also pass a block and choose the values depending on the record values
-and the name of the attachment. This is useful if you're using the
-`dynamic_storage` plugin. Example:
+If you want the storage to be dynamic based on `Attacher` data, you can use a
+block, and it will be evaluated in context of the `Attacher` instance:
 
 ```rb
-plugin :default_storage, store: ->(record, name) { :"store_#{record.username}" }
+plugin :default_storage, store: -> {
+  if record.is_a?(Photo)
+    :photo_store
+  else
+    :store
+  end
+}
 ```
 
-[default_storage]: /lib/shrine/plugins/default_storage.rb
+You can also set default storage with `Attacher#default_cache` and
+`Attacher#default_store`:
+
+```rb
+# default temporary storage
+Attacher.default_cache :other_cache
+# or
+Attacher.default_cache { :other_cache }
+
+# default permanent storage
+Attacher.default_store :other_store
+# or
+Attacher.default_store { :other_store }
+```
+
+The dynamic block is useful in combination with the
+[`dynamic_storage`][dynamic_storage] plugin.
+
+[default_storage]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/default_storage.rb
+[dynamic_storage]: https://shrinerb.com/docs/plugins/dynamic_storage

data/doc/plugins/default_url.md

@@ -1,34 +1,51 @@
-# Default URL
+---
+title: Default URL
+---
 
 The [`default_url`][default_url] plugin allows setting the URL which will be
-returned when the attachment is missing.
+returned when there is no attached file.
 
 ```rb
 plugin :default_url
 
-Attacher.default_url do |options|
+Attacher.default_url do |**options|
   "/#{name}/missing.jpg"
 end
 ```
 
-`Attacher#url` returns the default URL when attachment is missing. Any passed
-in URL options will be present in the `options` hash.
+The `Attacher#url` method will return the default URL when attachment is
+missing:
 
 ```rb
-attacher.url #=> "/avatar/missing.jpg"
-# or
 user.avatar_url #=> "/avatar/missing.jpg"
+# or
+attacher.url #=> "/avatar/missing.jpg"
+```
+
+Any URL options passed will be available in the default URL block:
+
+```rb
+attacher.url(foo: "bar")
+```
+```rb
+Attacher.default_url do |**options|
+  options #=> { foo: "bar" }
+end
 ```
 
 The default URL block is evaluated in the context of an instance of
 `Shrine::Attacher`.
 
 ```rb
-Attacher.default_url do |options|
-  self #=> #<Shrine::Attacher>
+Attacher.default_url do |**options|
+  self    #=> #<Shrine::Attacher>
+
+  file    #=> #<Shrine::UploadedFile>
+  name    #=> :avatar
+  record  #=> #<User>
+  context #=> { ... }
 
-  name   #=> :avatar
-  record #=> #<User>
+  # ...
 end
 ```
 
@@ -41,7 +58,7 @@ option:
 plugin :default_url, host: "https://example.com"
 ```
 ```rb
-user.avatar_url #=> "https://example.com/avatar/missing.jpg"
+attacher.url #=> "https://example.com/avatar/missing.jpg"
 ```
 
-[default_url]: /lib/shrine/plugins/default_url.rb
+[default_url]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/default_url.rb

data/doc/plugins/delete_raw.md

@@ -1,4 +1,6 @@
-# Delete Raw
+---
+title: Delete Raw
+---
 
 The [`delete_raw`][delete_raw] plugin will automatically delete raw files that
 have been uploaded. This is especially useful when doing processing, to ensure
@@ -22,4 +24,4 @@ to the uploader:
 uploader.upload(file, delete: false)
 ```
 
-[delete_raw]: /lib/shrine/plugins/delete_raw.rb
+[delete_raw]: https://github.com/shrinerb/shrine/blob/master/lib/shrine/plugins/delete_raw.rb