optimizeFor(definition)

Selects a version of an image based on the provided definition.

This method returns the best matching version of the source image based on the passed-in definition. Usually, applications do not need to use this method because Scrivito.ImageTag and Scrivito.BackgroundImageTag automatically deliver optimized images. Only applicable to a Binary if it represents an image.

This method does not change the binary. Instead, it instructs Scrivito to select an image from a pool of resized versions. The selected version is the one that best matches the provided definition.

The optimizeFor method returns a Binary instance in which the definition passed to the method is stored. The image version that fits best is only determined as this instance’s data is accessed, for example via binary.url.

The image version that fits best is selected at best effort, meaning:

  • Scrivito examines the requested dimensions and chooses a down-scaled image that provides a sufficiently high resolution for that size.
  • The returned image may be larger or smaller than requested but is approximately of the requested size, so it may be twice as large in one dimension but not 10 times as large.
  • A requested fit with crop causes an image version to be returned which is most suitable for applying the cropping, e.g. using CSS.

Params

definition (Object) – Specifies the desired dimensions of the returned image and the operation to be applied to the source.

Properties
  • width (Number or String) – The desired width of the output image in pixels. Must be a positive integer. If only this dimension has been specified, the height is calculated automatically to preserve the aspect ratio of the input image.
  • height (Number or String) – The height of the output image in pixels. The same rules as for width apply analogously. If neither width nor height is given, the width and height of the input image are used.
  • fit (String) – Specifies how to resize the image to yield the requested dimensions, width and height. Valid values are resize and crop. The default value is resize.
    • With resize, the image version is selected that fits best within the width and height boundaries without causing it to be cropped or distorted by the browser. The resulting image is assured to approximately match one of the constraining dimensions, while the other dimension may be changed to preserve the aspect ratio of the input image. The maximum size of the output image is limited to 4096 × 4096 pixels. The specified 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.
    • With crop, the image version is selected that yields the best possible result that allows for cropping the image to the given width and height. As a default, the image is assumed to be cropped centered, i.e. preserving the middle part of the image. The area to preserve can be specified using the crop parameter.
      Since the image selection process is a best effort, the layout must be able to handle images of all dimensions robustly, e.g. by leveraging CSS like max-width or background-image. For rendering a background image with Scrivito, see Scrivito.BackgroundImageTag.
  • crop (String) – Specifies the area assumed to be preserved when cropping is performed. Only applicable if fit is set to crop. Valid values are center, top, left, right, and bottom.

Returns

Binary

Examples

Determine the image version that is best suited for being displayed at 30 pixels width and 50 pixels height. The grey area indicates the requested size. The selected image is less high than this area.

Determine the image version that is best suited for being displayed at 50 pixels width and 25 pixels height. The grey area indicates the requested size. The selected image is less wide than this area.

Determine the image version that is best suited for being displayed at 50 pixels width and 25 pixels height, filling the area entirely with image data. The selected image is larger than the requested size. The top and bottom parts of the image must be made invisible by the app.

Determine the image version that is best suited for being displayed at 30 pixels width and 50 pixels height, filling the area entirely with image data. The selected image is larger than the requested size. The left and right parts of the image must be made invisible by the app.