Active Storage Preview

Some non-image blobs can be previewed: that is, they can be presented as images. A video blob can be previewed by extracting its first frame, and a PDF blob can be previewed by extracting its first page.

A previewer extracts a preview image from a blob. Active Storage provides previewers for videos and PDFs. ActiveStorage::Previewer::VideoPreviewer is used for videos whereas ActiveStorage::Previewer::PopplerPDFPreviewer and ActiveStorage::Previewer::MuPDFPreviewer are used for PDFs. Build custom previewers by subclassing ActiveStorage::Previewer and implementing the requisite methods. Consult the ActiveStorage::Previewer documentation for more details on whatโ€™s required of previewers.

To choose the previewer for a blob, Active Storage calls accept? on each registered previewer in order. It uses the first previewer for which accept? returns true when given the blob. In a Rails application, add or remove previewers by manipulating Rails.application.config.active_storage.previewers in an initializer:

Rails.application.config.active_storage.previewers
# => [ ActiveStorage::Previewer::PopplerPDFPreviewer, ActiveStorage::Previewer::MuPDFPreviewer, ActiveStorage::Previewer::VideoPreviewer ]

# Add a custom previewer for Microsoft Office documents:
Rails.application.config.active_storage.previewers << DOCXPreviewer
# => [ ActiveStorage::Previewer::PopplerPDFPreviewer, ActiveStorage::Previewer::MuPDFPreviewer, ActiveStorage::Previewer::VideoPreviewer, DOCXPreviewer ]

Outside of a Rails application, modify ActiveStorage.previewers instead.

The built-in previewers rely on third-party system libraries. Specifically, the built-in video previewer requires FFmpeg. Two PDF previewers are provided: one requires Poppler, and the other requires muPDF (version 1.8 or newer). To preview PDFs, install either Poppler or muPDF.

These libraries are not provided by Rails. You must install them yourself to use the built-in previewers. Before you install and use third-party software, make sure you understand the licensing implications of doing so.

Namespace

Class

Methods

Attributes

[R] blob
[R] variation

Class Public methods

new(blob, variation_or_variation_key)

๐Ÿ“ Source code 
# File activestorage/app/models/active_storage/preview.rb, line 38
  def initialize(blob, variation_or_variation_key)
    @blob, @variation = blob, ActiveStorage::Variation.wrap(variation_or_variation_key)
  end
๐Ÿ”Ž See on GitHub

Instance Public methods

download(&block)

Downloads the file associated with this previewโ€™s variant. If no block is given, the entire file is read into memory and returned. Thatโ€™ll use a lot of RAM for very large files. If a block is given, then the download is streamed and yielded in chunks. Raises ActiveStorage::Preview::UnprocessedError if the preview has not been processed yet.

๐Ÿ“ Source code 
# File activestorage/app/models/active_storage/preview.rb, line 85
  def download(&block)
    if processed?
      variant.download(&block)
    else
      raise UnprocessedError
    end
  end
๐Ÿ”Ž See on GitHub

image()

Returns the blobโ€™s attached preview image.

๐Ÿ“ Source code 
# File activestorage/app/models/active_storage/preview.rb, line 54
  def image
    blob.preview_image
  end
๐Ÿ”Ž See on GitHub

key()

Returns a combination key of the blob and the variation that together identifies a specific variant.

๐Ÿ“ Source code 
# File activestorage/app/models/active_storage/preview.rb, line 72
  def key
    if processed?
      variant.key
    else
      raise UnprocessedError
    end
  end
๐Ÿ”Ž See on GitHub

processed()

Processes the preview if it has not been processed yet. Returns the receiving Preview instance for convenience:

blob.preview(resize_to_limit: [100, 100]).processed.url

Processing a preview generates an image from its blob and attaches the preview image to the blob. Because the preview image is stored with the blob, it is only generated once.

๐Ÿ“ Source code 
# File activestorage/app/models/active_storage/preview.rb, line 48
  def processed
    process unless processed?
    self
  end
๐Ÿ”Ž See on GitHub

url(**options)

Returns the URL of the previewโ€™s variant on the service. Raises ActiveStorage::Preview::UnprocessedError if the preview has not been processed yet.

This method synchronously processes a variant of the preview image, so do not call it in views. Instead, generate a stable URL that redirects to the URL returned by this method.

๐Ÿ“ Source code 
# File activestorage/app/models/active_storage/preview.rb, line 63
  def url(**options)
    if processed?
      variant.url(**options)
    else
      raise UnprocessedError
    end
  end
๐Ÿ”Ž See on GitHub