@@ -51,8 +52,37 @@ you want to do transformations of a given `Blob`, the idea is that you'll simply
create a new one, rather than attempt to mutate the existing one (though of
course you can delete the previous version later if you don't need it).
## Setup
To setup an existing application after upgrading to Rails 5.2, run `rails active_storage:install`. If you're creating a new project with Rails 5.2, ActiveStorage will be installed by default. This generates the tables for the
`Attachment` and `Blob` models.
Inside a Rails application, you can set-up your services through the
generated `config/storage.yml` file and reference one
of the aforementioned constant under the +service+ key. For example:
``` yaml
local:
service:Disk
root:<%= Rails.root.join("storage") %>
```
NOTE: Should we include the required keys for all the supported services?
NOTE: Should we mention the mirror service and how to set it up?
In your application's configuration, specify the service to
use like this:
``` ruby
config.active_storage.service=:local
```
Like other configuration options, you can set this application wide, or per
environment.
Attach Files to a Model
--------------------------
One or more files can be attached to a model.
One attachment:
...
...
@@ -115,6 +145,9 @@ end
Remove File Attached to Model
-------------------------------
To remove an attachment from a model, call `purge` on the attachment. Removal
can be done in the background if your application is setup to use ActiveJob.
```ruby
# Synchronously destroy the avatar and actual resource files.
user.avatar.purge
...
...
@@ -125,25 +158,37 @@ user.avatar.purge_later
Link to Attachments
----------------------
Generate a permanent URL for the blob that points to the application. Upon
access, a redirect to the actual service endpoint is returned. This indirection
decouples the public URL from the actual one, and allows for example mirroring
attachments in different services for high-availability. The redirection has an
HTTP expiration of 5 min.
```ruby
# Generate a permanent URL for the blob that points to the application.
# Upon access, a redirect to the actual service endpoint is returned.
# This indirection decouples the public URL from the actual one, and
# allows for example mirroring attachments in different services for
# high-availability. The redirection has an HTTP expiration of 5 min.
url_for(user.avatar)
```
Create Variations of Attached Image
-----------------------------------
Sometimes your application will require images in a different format than
what was uploaded. To create variation of the image, call `variant` on the Blob.
You can pass any [MiniMagick](https://github.com/minimagick/minimagick)
supported transformation.
When the browser hits the variant URL, ActiveStorage will lazy transform the
original blob into the format you specified and redirect to its new service
location.
```erb
<%# Hitting the variant URL will lazy transform the original blob and then redirect to its new service location %>
