Class: Scrivito::Binary

Inherits:
Object
  • Object
show all
Defined in:
app/cms/scrivito/binary.rb

Overview

The Binary class represents the data stored in a binary attribute of an Obj or a Widget.

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.upload(file_or_path, options = {}) ⇒ Scrivito::FutureBinary

Uploads a local file to the CMS.

Examples:

Upload a single file

@obj.update(blob: Scrivito::Binary.upload("./kitten.jpg"))

# Is equivalent to
@obj.update(blob: File.new("./kitten.jpg"))

Upload a file with a different filename and content_type

@obj.update(blob: Scrivito::Binary.upload("./rick_astley",
  filename: "ufo_landing.m4v", content_type: "video/mp4"))

Upload a tempfile

# Downloads an image to a local Tempfile
require 'open-uri'
tempfile = open("https://imgur.com/download/LK84SWc/Skynet's%20most%20terrifying%20creation")

# Uploads the local Tempfile to scrivito
@obj.update(blob: tempfile)

Parameters:

  • file_or_path (File, Tempfile, String) —

    the file to be uploaded or the path of the file to be uploaded.

  • options (Hash) (defaults to: {})

Options Hash (options):

  • filename (String) —

    the desired filename. Defaults to the name of the given file.

  • content_type (String) —

    the desired content type. By default, the content type is calculated based on the extension of the filename.

Returns:

Raises:

  • ArgumentError if given filename or content_type is blank.



58
59
60
61
62
63
64
65
66
67
68
69
70
 
# File 'app/cms/scrivito/binary.rb', line 58

def self.upload(file_or_path, options = {})
  assert_valid_options(options)

  file_to_upload = case file_or_path
    when File, Tempfile then file_or_path
    else File.new(file_or_path)
    end

  FutureBinary.new(options.reverse_merge(
    filename: File.basename(file_or_path),
    file_to_upload: file_to_upload,
  ))
end

Instance Method Details

#content_length ⇒ Integer

The length of this binary data, in bytes.

Returns:

  • (Integer) —

    number of bytes

Raises:



170
171
172
173
 
# File 'app/cms/scrivito/binary.rb', line 170

def content_length
  raise_field_not_available('Content length') if transformed?
  meta_data[:content_length]
end

#content_type ⇒ String

The content type of this binary data, for example “image/jpeg”.

Returns:

  • (String) —

    content type

Raises:



160
161
162
163
 
# File 'app/cms/scrivito/binary.rb', line 160

def content_type
  raise_field_not_available('Content type') if transformed?
  meta_data[:content_type]
end

#copy(options = {}) ⇒ Scrivito::FutureBinary

Create a copy of this Binary with a different filename and/or content type.

Examples:

Change filename and content_type of an existing binary. Binary content remains the same.

@obj.update(blob: @obj.blob.copy(filename: "cute_kitten.jpg", content_type: "video/mp4"))

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • filename (String) —

    the desired filename. Defaults to the filename of the original binary.

  • content_type (String) —

    the desired content type. By default, the content type is calculated based on the extension of the filename.

Returns:

Raises:

  • ArgumentError if given filename or content_type is blank.



91
92
93
94
 
# File 'app/cms/scrivito/binary.rb', line 91

def copy(options = {})
  self.class.assert_valid_options(options)
  FutureBinary.new(options.reverse_merge(filename: self.filename, id_to_copy: id))
end

#filename ⇒ String

The filename of this binary data, for example “my_image.jpg”.

Returns:

  • (String) —

    the filename of the binary



151
152
153
 
# File 'app/cms/scrivito/binary.rb', line 151

def filename
  File.basename(URI(url).path)
end

#meta_data ⇒ Scrivito::MetaDataCollection

Returns the meta data for the given binary.

Examples:

Accessing meta data

@obj.blob.meta_data['width'] # => 150
@obj.blob.meta_data['content_type'] # => 'image/jpeg'

Returns:

  • (Scrivito::MetaDataCollection) —

    meta data collection

Raises:

See Also:

  • List of available meta data attributes.


318
319
320
321
322
323
324
325
 
# File 'app/cms/scrivito/binary.rb', line 318

def meta_data
  raise_field_not_available('Meta data') if transformed?

  @meta_data ||= begin
    deserialized_meta_data = deserialize_meta_data(CmsBackend.find_binary_meta_data(id))
    MetaDataCollection.new(deserialized_meta_data)
  end
end

#original ⇒ Scrivito::Binary

Returns the original version of a transformed binary.

If a binary is the result of a transformation, the original version of the binary is returned. Otherwise self.

Returns:



301
302
303
 
# File 'app/cms/scrivito/binary.rb', line 301

def original
  @original || self
end

#private? ⇒ Boolean

Some Scrivito data is considered private, i.e. it is not currently intended for the general public, for example content in a workspace that has not been published yet.

Returns:

  • (Boolean) 


101
102
103
 
# File 'app/cms/scrivito/binary.rb', line 101

def private?
  !@is_public
end

#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:

See Also:



277
278
279
280
281
282
 
# 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

#transformed? ⇒ Boolean

Returns whether a binary has been transformed.

Returns:

  • (Boolean) 


288
289
290
 
# File 'app/cms/scrivito/binary.rb', line 288

def transformed?
  !!transformation_definition
end

#url ⇒ String

Note:

The URL is calculated on demand, i.e. if the URL has not been cached yet, this method calls the Scrivito API to retrieve the URL. If you want to link to a Binary, consider using ControllerHelper#scrivito_url instead. This is generally much faster, as it performs the Scrivito API call asynchronously.

Note:

URLs for private content have an expiration time in order to protect them. Therefore, the URL should be accessed immediately after it has been returned (i.e. within a couple of minutes). Accessing it after expiration causes an error.

The URL for accessing the binary data and downloading it using an HTTP GET request.

The URLs should not be used for long-term storage since they are no longer accessible hours or days after they have been generated.

Returns:

  • (String) —

    the URL at which this content is available.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'app/cms/scrivito/binary.rb', line 125

def url
  blob_data = CmsBackend.find_blob_data(id, access_type, 'get',
    transformation_definition: transformation_definition)
  blob_data['url']
rescue ClientError => e
  case e.backend_code
  when /\Abinary\.unprocessable\.image\.transform\.source\./
    raise TransformationSourceError.new(e.message, e.backend_code)
  when 'binary.unprocessable.image.transform.config.invalid'
    raise TransformationDefinitionError.new(e.message, e.backend_code)
  else
    raise e
  end
end