From d2b6fc6e6d80e05797aa3eb8a2cc882e750f95b1 Mon Sep 17 00:00:00 2001 From: Alex Ghiculescu Date: Sun, 29 Nov 2020 21:42:20 -0600 Subject: [PATCH] [docs] Mention `previewable?` and `variable?` in Activestorage guide While experimenting with ActiveStorage, we had a few issues come up because people did write sufficiently safe code in cases where they didn't know the exact content type of the file they were working with. Thus, calls to `variant` or `preview` might raise ([here](https://github.com/rails/rails/blob/v6.0.3.4/activestorage/app/models/active_storage/blob/representable.rb#L32) and [here](https://github.com/rails/rails/blob/v6.0.3.4/activestorage/app/models/active_storage/blob/representable.rb#L60)). I think this is a pretty common mistake to make (particularly for beginners) that warrants a mention in the guide. I've added a note about calling `variable?` before `variant`, and `previewable?` before `preview`. --- guides/source/active_storage_overview.md | 68 +++++++++++++++++------- 1 file changed, 49 insertions(+), 19 deletions(-) diff --git a/guides/source/active_storage_overview.md b/guides/source/active_storage_overview.md index 28eb25ce7e..26d5fba6d8 100644 --- a/guides/source/active_storage_overview.md +++ b/guides/source/active_storage_overview.md @@ -533,7 +533,7 @@ It's important to know that the file is not yet available in the `after_create` Analyzing Files --------------- -Active Storage [analyzes](https://api.rubyonrails.org/classes/ActiveStorage/Blob/Analyzable.html#method-i-analyze) files once they've been uploaded by queuing a job in Active Job. Analyzed files will store additional information in the metadata hash, including `analyzed: true`. You can check whether a blob has been analyzed by calling [`analyzed?`][] on it. +Active Storage analyzes files once they've been uploaded by queuing a job in Active Job. Analyzed files will store additional information in the metadata hash, including `analyzed: true`. You can check whether a blob has been analyzed by calling [`analyzed?`][] on it. Image analysis provides `width` and `height` attributes. Video analysis provides these, as well as `duration`, `angle`, and `display_aspect_ratio`. @@ -541,37 +541,69 @@ Analysis requires the `mini_magick` gem. Video analysis also requires the [FFmpe [`analyzed?`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Analyzable.html#method-i-analyzed-3F -Transforming Images -------------------- +Displaying Images, Videos, and PDFs +--------------- +Active Storage supports representing a variety of files. You can call +[`representation`][] on an attachment to display an image variant, or a +preview of a video or PDF. Before calling `representation`, check if the +attachment can be represented by calling [`representable?`]. Some file formats +can't be previewed by ActiveStorage out of the box (eg. Word documents); if +`representable?` returns false you may want to [link to](#linking-to-files) +the file instead. + +```erb + +``` + +Internally, `representation` calls `variant` for images, and `preview` for +previewable files. You can also call these methods directly. + +[`representable?`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-representable-3F +[`representation`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-representation + +### Transforming Images + +Transforming images allows you to display the image at your choice of dimensions. To enable variants, add the `image_processing` gem to your `Gemfile`: ```ruby gem 'image_processing' ``` -To create a variation of an image, call [`variant`][] on the attachment. You can pass any transformation to the method supported by the processor. The default processor for Active Storage is MiniMagick, but you can also use [Vips](https://www.rubydoc.info/gems/ruby-vips/Vips/Image). - -When the browser hits the variant URL, Active Storage will lazily transform the -original blob into the specified format and redirect to its new service +To create a variation of an image, call [`variant`][] on the attachment. You +can pass any transformation supported by the variant processor to the method. +When the browser hits the variant URL, Active Storage will lazily transform +the original blob into the specified format and redirect to its new service location. ```erb <%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %> ``` -To switch to the Vips processor, you would add the following to -`config/application.rb`: +The default processor for Active Storage is MiniMagick, but you can also use +[Vips][]. To switch to Vips, add the following to `config/application.rb`: ```ruby -# Use Vips for processing variants. config.active_storage.variant_processor = :vips ``` [`variant`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-variant +[Vips]: https://www.rubydoc.info/gems/ruby-vips/Vips/Image -Previewing Files ----------------- +### Previewing Files Some non-image files can be previewed: that is, they can be presented as images. For example, a video file can be previewed by extracting its first frame. Out of @@ -579,15 +611,12 @@ the box, Active Storage supports previewing videos and PDF documents. To create a link to a lazily-generated preview, use the attachment's [`preview`][] method: ```erb - +<%= image_tag message.video.preview(resize_to_limit: [100, 100]) %> ``` +To add support for another format, add your own previewer. See the +[`ActiveStorage::Preview`][] documentation for more information. + WARNING: Extracting previews requires third-party applications: FFmpeg v3.4+ for video and muPDF for PDFs, and on macOS also XQuartz and Poppler. These libraries are not provided by Rails. You must install them yourself to @@ -595,6 +624,7 @@ use the built-in previewers. Before you install and use third-party software, make sure you understand the licensing implications of doing so. [`preview`]: https://api.rubyonrails.org/classes/ActiveStorage/Blob/Representable.html#method-i-preview +[`ActiveStorage::Preview`]: https://api.rubyonrails.org/classes/ActiveStorage/Preview.html Direct Uploads --------------