Class: ActiveStorage::Preview

Inherits:
Object
  • Object
show all
Defined in:
app/models/active_storage/preview.rb

Overview

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. 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.

Defined Under Namespace

Classes: UnprocessedError

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(blob, variation_or_variation_key) ⇒ Preview

Returns a new instance of Preview.



35
36
37
 
# File '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 Attribute Details

#blob ⇒ Object (readonly)

Returns the value of attribute blob.



33
34
35
 
# File 'app/models/active_storage/preview.rb', line 33

def blob
  @blob
end

#variation ⇒ Object (readonly)

Returns the value of attribute variation.



33
34
35
 
# File 'app/models/active_storage/preview.rb', line 33

def variation
  @variation
end

Instance Method Details

#image ⇒ Object

Returns the blob's attached preview image.



51
52
53
 
# File 'app/models/active_storage/preview.rb', line 51

def image
  blob.preview_image
end

#processed ⇒ Object

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.



45
46
47
48
 
# File 'app/models/active_storage/preview.rb', line 45

def processed
  process unless processed?
  self
end

#service_url(**options) ⇒ Object

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.



60
61
62
63
64
65
66
 
# File 'app/models/active_storage/preview.rb', line 60

def service_url(**options)
  if processed?
    variant.service_url(options)
  else
    raise UnprocessedError
  end
end