Class: Scrivito::Binary

Inherits:
Object
  • Object
show all
Defined in:
lib/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, filename: nil, content_type: nil) ⇒ Scrivito::FutureBinary

Uploads a local file to the CMS.

Examples:

Upload a single file

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

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

Upload a file with a different filename and content type

@obj.update(blob: Scrivito::Binary.upload(
    "/Desktop/rick_astley", content_type: "Video/MP4", filename: "ufo_landing.m4v"))

Parameters:

  • file_or_path (File, String) —

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

  • filename (String, Nil) (defaults to: nil) —

    the desired filename. If nil, the name of the given file is used.

  • content_type (String, Nil) (defaults to: nil) —

    the desired content type. If nil, the content type is calculated based on the extension of the filename.

Returns:



34
35
36
37
38
39
40
41
42
 
# File 'lib/scrivito/binary.rb', line 34

def self.upload(file_or_path, filename: nil, content_type: nil)
  if file_or_path.is_a?(File)
    file = file_or_path
  else
    file = File.new(file_or_path)
  end
  new_filename = filename || File.basename(file_or_path)
  FutureBinary.new(content_type: content_type, filename: new_filename, file_to_be_uploaded: file)
end

Instance Method Details

#content_length ⇒ Integer

The length of this binary data, in bytes.

Returns:

  • (Integer) —

    number of bytes



117
118
119
 
# File 'lib/scrivito/binary.rb', line 117

def content_length
  headers[:content_length].to_i
end

#content_type ⇒ String

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

Returns:

  • (String) —

    content type



110
111
112
 
# File 'lib/scrivito/binary.rb', line 110

def content_type
  headers[:content_type]
end

#copy(content_type: nil, filename: nil) ⇒ 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:

  • filename (String, Nil) (defaults to: nil) —

    the desired filename. If nil, the filename of the original binary is used.

  • content_type (String, Nil) (defaults to: nil) —

    the desired content type. If nil, the content type is calculated based on the extension of the filename.

Returns:

  • (Scrivito::FutureBinary) —

    the returned object should be inserted into the binary field of an Obj or Widget.



54
55
56
57
 
# File 'lib/scrivito/binary.rb', line 54

def copy(content_type: nil, filename: nil)
  new_filename = filename || self.filename
  FutureBinary.new(content_type: content_type, filename: new_filename, id_to_be_copied: id)
end

#filename ⇒ String

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

Returns:

  • (String) —

    the filename of the binary



103
104
105
 
# File 'lib/scrivito/binary.rb', line 103

def filename
  File.basename(URI(url).path)
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.

Examples:

@obj.blob.id # => "abc123"
@obj.blob.original.id # => "abc123"
@obj.blob.transform(width: 50).original.id # => "abc123"
@obj.blob.transform(width: 50).transform(height: 50).original.id # => "abc123"

Returns:



238
239
240
 
# File 'lib/scrivito/binary.rb', line 238

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) 


64
65
66
 
# File 'lib/scrivito/binary.rb', line 64

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.

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 (Fixnum, 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 :clip, 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 (Fixnum, 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 :clip, 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 :clip and :crop. The default value is :clip.

    If set to :clip, 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, i.e. the center of the image is preserved.

  • :quality (Fixnum, 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.

Returns:

See Also:



208
209
210
211
212
 
# File 'lib/scrivito/binary.rb', line 208

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

#transformed? ⇒ Boolean

Returns whether a binary has been transformed.

Returns:

  • (Boolean) 


218
219
220
 
# File 'lib/scrivito/binary.rb', line 218

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.



88
89
90
 
# File 'lib/scrivito/binary.rb', line 88

def url
  find_url('get')
end