Module: DynamicImage::Helper

Includes:
Formats, Pictures
Defined in:
lib/dynamic_image/helper.rb,
lib/dynamic_image/helper/formats.rb,
lib/dynamic_image/helper/pictures.rb

Overview

DynamicImage Helper

Helper methods for rendering and linking to images.

Every URL is signed with an HMAC digest of the action, the record id and the size, and the controller rejects anything that doesn't match. URLs can only be built server-side.

_path returns a relative path and _url an absolute one. _tag renders an image tag, and is available for dynamic_image and uncropped_dynamic_image only. original and download point at the stored file, which is never rendered.

See Also:

Defined Under Namespace

Modules: Formats, Pictures

Instance Method Summary collapse

Methods included from Pictures

#dynamic_picture, #dynamic_picture_source_tag, #dynamic_picture_tag

Instance Method Details

#download_dynamic_image_path(record_or_array, options = {}) ⇒ String

Returns a path to the original uploaded file, served as an attachment so the browser downloads it. The file is not processed, and sizing options are ignored. The URL carries the stored format's extension, and :format has no effect.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    routing options

Returns:

  • (String) 


108
109
110
 
# File 'lib/dynamic_image/helper.rb', line 108

def download_dynamic_image_path(record_or_array, options = {})
  dynamic_image_path(record_or_array, { action: :download }.merge(options))
end

#download_dynamic_image_url(record_or_array, options = {}) ⇒ String

Same as #download_dynamic_image_path, but returns an absolute URL.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    routing options

Returns:

  • (String) 


117
118
119
 
# File 'lib/dynamic_image/helper.rb', line 117

def download_dynamic_image_url(record_or_array, options = {})
  dynamic_image_url(record_or_array, { action: :download }.merge(options))
end

#dynamic_image_path(record_or_array, options = {}) ⇒ String

Returns the path for a Model record. Takes the same options as #dynamic_image_url.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record, or an array of records for a nested route

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

    sizing and routing options

Returns:

  • (String) 


30
31
32
 
# File 'lib/dynamic_image/helper.rb', line 30

def dynamic_image_path(record_or_array, options = {})
  dynamic_image_url(record_or_array, { routing_type: :path }.merge(options))
end

#dynamic_image_tag(record_or_array, options = {}) ⇒ String

Returns an HTML image tag for the record, with width and height set to the rendered size. Without a size, it renders at the original size.

See #dynamic_image_url for sizing and cropping. Options supported by polymorphic_url are passed to the router, and any others are added as HTML attributes.

Unless an alt option is given, the alt text is resolved from Model#alt_text. Pass alt: "" to mark an image as decorative.

Examples:

image = Image.find(params[:id])

dynamic_image_tag(image)
# => <img src="..." width="320" height="200" />

dynamic_image_tag(image, size: "100x100", alt: "Avatar")
# => <img alt="Avatar" src="..." width="100" height="62" />

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record, or an array of records for a nested route

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

    sizing options, routing options and HTML attributes

Returns:

  • (String) 


55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/dynamic_image/helper.rb', line 55

def dynamic_image_tag(record_or_array, options = {})
  record = extract_dynamic_image_record(record_or_array)
  size = fit_size!(record_or_array, options)
  url_options = options.extract!(*allowed_dynamic_image_url_options)
  html_options = { size:, alt: record.alt_text }.merge(options)

  image_tag(dynamic_image_path_with_size(record_or_array,
                                         size,
                                         url_options),
            html_options)
end

#dynamic_image_url(record_or_array, options = {}) ⇒ String

Returns the URL for a Model record.

Any options supported by polymorphic_url are also accepted.

Examples:

image = Image.find(params[:id])

dynamic_image_url(image)
# => "http://example.com/images/96...d1/300x187/1-2014062020...00.jpg"

dynamic_image_url(image, size: '100x100')
# => "http://example.com/images/72...c2/100x62/1-2014062020...00.jpg"

dynamic_image_url(image, size: '100x100', crop: true)
# => "http://example.com/images/a4...6b/100x100/1-2014062020...00.jpg"

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record, or an array of records for a nested route

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

    sizing and routing options

Options Hash (options):

  • :size (String) —

    Desired image size, as "{width}x{height}". The image is scaled to fit. A partial size like "100x" or "x100" can be given for a fixed width or height.

  • :crop (Boolean) —

    Crop the image to the given size instead of fitting it. Both dimensions are required.

  • :upscale (Boolean) —

    By default images are only scaled down, never up. Pass true to force upscaling.

  • :format (Symbol, Array<Symbol>) —

    Render in a different format. A symbol forces that format, an array is negotiated against the image by FormatNegotiator. Defaults to DynamicImage#default_formats, or DynamicImage#mailer_formats in a mailer view.

Returns:

  • (String)

Raises:



96
97
98
99
 
# File 'lib/dynamic_image/helper.rb', line 96

def dynamic_image_url(record_or_array, options = {})
  size = fit_size!(record_or_array, options)
  dynamic_image_url_with_size(record_or_array, size, options)
end

#original_dynamic_image_path(record_or_array, options = {}) ⇒ String

Returns a path to the original uploaded file, exactly as it was uploaded. The file is not processed, and sizing options are ignored. The URL carries the stored format's extension, and :format has no effect.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    routing options

Returns:

  • (String) 


127
128
129
 
# File 'lib/dynamic_image/helper.rb', line 127

def original_dynamic_image_path(record_or_array, options = {})
  dynamic_image_path(record_or_array, { action: :original }.merge(options))
end

#original_dynamic_image_url(record_or_array, options = {}) ⇒ String

Same as #original_dynamic_image_path, but returns an absolute URL.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    routing options

Returns:

  • (String) 


136
137
138
 
# File 'lib/dynamic_image/helper.rb', line 136

def original_dynamic_image_url(record_or_array, options = {})
  dynamic_image_url(record_or_array, { action: :original }.merge(options))
end

#uncropped_dynamic_image_path(record_or_array, options = {}) ⇒ String

Same as #dynamic_image_path, but points to an image with any pre-cropping disabled.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    sizing and routing options

Returns:

  • (String) 


145
146
147
 
# File 'lib/dynamic_image/helper.rb', line 145

def uncropped_dynamic_image_path(record_or_array, options = {})
  dynamic_image_path(record_or_array, { action: :uncropped }.merge(options))
end

#uncropped_dynamic_image_tag(record_or_array, options = {}) ⇒ String

Same as #dynamic_image_tag, but renders an image with any pre-cropping disabled.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    sizing options, routing options and HTML attributes

Returns:

  • (String) 


154
155
156
 
# File 'lib/dynamic_image/helper.rb', line 154

def uncropped_dynamic_image_tag(record_or_array, options = {})
  dynamic_image_tag(record_or_array, { action: :uncropped }.merge(options))
end

#uncropped_dynamic_image_url(record_or_array, options = {}) ⇒ String

Same as #dynamic_image_url, but points to an image with any pre-cropping disabled.

Parameters:

  • record_or_array (DynamicImage::Model, Array) —

    the record

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

    sizing and routing options

Returns:

  • (String) 


163
164
165
 
# File 'lib/dynamic_image/helper.rb', line 163

def uncropped_dynamic_image_url(record_or_array, options = {})
  dynamic_image_url(record_or_array, { action: :uncropped }.merge(options))
end