Methods
Instance Public methods
preview(transformations)
Returns an ActiveStorage::Preview
instance with the set of transformations
provided. A preview is an image generated from a non-image blob. Active Storage comes with built-in previewers for videos and PDF documents. The video previewer extracts the first frame from a video and the PDF previewer extracts the first page from a PDF document.
blob.preview(resize_to_limit: [100, 100]).processed.url
Avoid processing previews synchronously in views. Instead, link to a controller action that processes them on demand. Active Storage provides one, but you may want to create your own (for example, if you need authentication). Hereβs how to use the built-in version:
<%= image_tag video.preview(resize_to_limit: [100, 100]) %>
This method raises ActiveStorage::UnpreviewableError
if no previewer accepts the receiving blob. To determine whether a blob is accepted by any previewer, call ActiveStorage::Blob#previewable?
.
π Source code
# File activestorage/app/models/active_storage/blob/representable.rb, line 63
def preview(transformations)
if previewable?
ActiveStorage::Preview.new(self, transformations)
else
raise ActiveStorage::UnpreviewableError, "No previewer found for blob with ID=#{id} and content_type=#{content_type}"
end
end
π See on GitHub
previewable?()
Returns true if any registered previewer accepts the blob. By default, this will return true for videos and PDF documents.
π Source code
# File activestorage/app/models/active_storage/blob/representable.rb, line 72
def previewable?
ActiveStorage.previewers.any? { |klass| klass.accept?(self) }
end
π See on GitHub
representable?()
Returns true if the blob is variable or previewable.
π Source code
# File activestorage/app/models/active_storage/blob/representable.rb, line 97
def representable?
variable? || previewable?
end
π See on GitHub
representation(transformations)
Returns an ActiveStorage::Preview
for a previewable blob or an ActiveStorage::Variant
for a variable image blob.
blob.representation(resize_to_limit: [100, 100]).processed.url
Raises ActiveStorage::UnrepresentableError
if the receiving blob is neither variable nor previewable. Call ActiveStorage::Blob#representable?
to determine whether a blob is representable.
See ActiveStorage::Blob#preview
and ActiveStorage::Blob#variant
for more information.
π Source code
# File activestorage/app/models/active_storage/blob/representable.rb, line 85
def representation(transformations)
case
when previewable?
preview transformations
when variable?
variant transformations
else
raise ActiveStorage::UnrepresentableError, "No previewer found and can't transform blob with ID=#{id} and content_type=#{content_type}"
end
end
π See on GitHub
variable?()
Returns true if the variant processor can transform the blob (its content type is in ActiveStorage.variable_content_types
).
π Source code
# File activestorage/app/models/active_storage/blob/representable.rb, line 44
def variable?
ActiveStorage.variable_content_types.include?(content_type)
end
π See on GitHub
variant(transformations)
Returns an ActiveStorage::Variant
or ActiveStorage::VariantWithRecord
instance with the set of transformations
provided. This is only relevant for image files, and it allows any image to be transformed for size, colors, and the like. Example:
avatar.variant(resize_to_limit: [100, 100]).processed.url
This will create and process a variant of the avatar blob thatβs constrained to a height and width of 100px. Then itβll upload said variant to the service according to a derivative key of the blob and the transformations.
Frequently, though, you donβt actually want to transform the variant right away. But rather simply refer to a specific variant that can be created by a controller on-demand. Like so:
<%= image_tag Current.user.avatar.variant(resize_to_limit: [100, 100]) %>
This will create a URL for that specific blob with that specific variant, which the ActiveStorage::RepresentationsController can then produce on-demand.
Raises ActiveStorage::InvariableError
if the variant processor cannot transform the blob. To determine whether a blob is variable, call ActiveStorage::Blob#variable?
.
π Source code
# File activestorage/app/models/active_storage/blob/representable.rb, line 34
def variant(transformations)
if variable?
variant_class.new(self, ActiveStorage::Variation.wrap(transformations).default_to(default_variant_transformations))
else
raise ActiveStorage::InvariableError, "Can't transform blob with ID=#{id} and content_type=#{content_type}"
end
end
π See on GitHub