Method: Scrivito::Binary#transform

Defined in:

app/cms/scrivito/binary.rb

#transform(definition) ⇒ Scrivito::Binary

Use this method to transform images, i.e. to scale down large images or to generate thumbnails of images. Only applicable if this Scrivito::Binary is an image.

This method does not change the binary. Instead, it returns a copy of it, transformed using the definition.

If the original binary has already been transformed, the returned binary will be a combination of the transformations. Thus, the transformations can be chained (see examples).

The transformed data is calculated “lazily”, so calling #transform does not trigger any calculation. The calculation is triggered only when data is accessed, for example via #url.

Note that transforming images is slow and therefore should not be carried out inside a request. The #scrivito_image_tag and #scrivito_path helpers transform images asynchronously and don’t place additional load onto requests.

Examples:

Crop image to fit into 50 x 50 pixel square.

@obj.blob.transform(width: 50, height: 50, fit: :crop)

Convert image to a low quality JPEG.

@obj.blob.transform(quality: 25)

Combine two transformations.

@obj.blob.transform(width: 50, height: 50, fit: :crop).transform(quality: 25)

Parameters:

• definition (Hash) —

  transformation definition

Options Hash (definition):

• :width (Integer, String) —

  The width in pixels of the output image. Must be a positive integer.

  If only this dimension has been specified, the other dimension is calculated automatically to preserve the aspect ratio of the input image.

  If the fit parameter is set to :resize, then either the actual output width or the output height may be less than the amount you specified to prevent distortion.

  If neither width nor height is given, the width and height of the input image is used.

  The maximum size of the output image is defined as width + height = 4096 pixels. The given width and height may be adjusted to accommodate this limit. The output image will never be larger than the source image, i.e. the given width and height may be adjusted to prevent the dimensions of the output image from exceeding those of the input image.

  If the given width and height are adjusted, the aspect ratio is preserved.

• :height (Integer, String) —

  The height in pixels of the output image. Must be a positive integer.

  If only this dimension has been specified, the other dimension is calculated automatically to preserve the aspect ratio of the input image.

  If the fit parameter is set to :resize, then either the actual output width or the output height may be less than the amount you specified to prevent distortion.

  If neither width nor height is given, the width and height of the input image is used.

  The maximum size of the output image is defined as width + height = 4096 pixels. The given width and height may be adjusted to accommodate this limit. The output image will never be larger than the source image, i.e. the given width and height may be adjusted to prevent the dimensions of the output image from exceeding those of the input image.

  If the given width and height are adjusted, the aspect ratio is preserved.

• :fit (Symbol, String) —

  Controls how the transformed image is fitted to the given width and height. Valid values are :resize: and :crop. The default value is :resize.

  If set to :resize, the image is resized so as to fit within the width and height boundaries without cropping or distorting the image. The resulting image is assured to match one of the constraining dimensions, while the other dimension is altered to maintain the same aspect ratio of the input image.

  If set to :crop, the image is resized so as to fill the given width and height, preserving the aspect ratio by cropping any excess image data. The resulting image will match both the given width and height without distorting the image. Cropping is done centered by default, i.e. the center of the image is preserved. The area to preserve can be configured using the crop parameter.

• :quality (Integer, String) —

  Controls the output quality of lossy file formats. Applies if the format is “jpg”. Valid values are in the range from 0 to 100. The default value is 75.

• :crop (Symbol, String) —

  Controls the area to preserve when cropping and is only applicable if fit is set to crop. Valid values are center, top, left, right, and bottom.

  For example, setting crop to left means that the left part of the image will be preserved when cropping, i.e. if necessary, cropping cuts away the right side of the image

Returns:

• (Scrivito::Binary) —

  transformed binary

See Also:

• Configuration
• ScrivitoHelper#scrivito_image_tag

# File 'app/cms/scrivito/binary.rb', line 277

def transform(definition)
  self.class.new(id, public?,
    transformation_definition: (transformation_definition || {}).merge(definition),
    original: original,
    obj_id: obj_id)
end