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.

Instance Method Summary collapse

Instance Method Details

#content_length ⇒ Integer

The length of this binary data, in bytes.

Returns:

  • (Integer) —

    number of bytes



74
75
76
 
# File 'lib/scrivito/binary.rb', line 74

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



67
68
69
 
# File 'lib/scrivito/binary.rb', line 67

def content_type
  headers[:content_type]
end

#filename ⇒ String

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

Returns:

  • (String) —

    the filename of the binary



60
61
62
 
# File 'lib/scrivito/binary.rb', line 60

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:



193
194
195
 
# File 'lib/scrivito/binary.rb', line 193

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) 


21
22
23
 
# File 'lib/scrivito/binary.rb', line 21

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 tranformed image is fitted to the given width and heigth. 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:



165
166
167
 
# File 'lib/scrivito/binary.rb', line 165

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

#transformed? ⇒ Boolean

Returns whether a binary has been transformed.

Returns:

  • (Boolean) 


173
174
175
 
# File 'lib/scrivito/binary.rb', line 173

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.



45
46
47
 
# File 'lib/scrivito/binary.rb', line 45

def url
  find_url('get')
end