edge badge

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 and ActiveStorage::Previewer::PDFPreviewer. 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::PDFPreviewer, ActiveStorage::Previewer::VideoPreviewer ]

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

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

The built-in previewers rely on third-party system libraries:

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
Methods
I
N
P
S
Attributes
[R] blob
[R] variation
Class Public methods
new(blob, variation_or_variation_key)
# File activestorage/app/models/active_storage/preview.rb, line 35
def initialize(blob, variation_or_variation_key)
  @blob, @variation = blob, ActiveStorage::Variation.wrap(variation_or_variation_key)
end
Instance Public methods
image()

Returns the blob's attached preview image.

# File activestorage/app/models/active_storage/preview.rb, line 51
def image
  blob.preview_image
end
processed()

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

blob.preview(resize: "100x100").processed.service_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.

# File activestorage/app/models/active_storage/preview.rb, line 45
def processed
  process unless processed?
  self
end
service_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 short-lived URL returned by this method.

# File activestorage/app/models/active_storage/preview.rb, line 60
def service_url(**options)
  if processed?
    variant.service_url(options)
  else
    raise UnprocessedError
  end
end