Module: DynamicImage::Helper::Pictures

Included in:
DynamicImage::Helper
Defined in:
lib/dynamic_image/helper/pictures.rb

Overview

DynamicImage Helper Pictures

Renders responsive images: a picture element with a WebP source covering a range of widths, and an img fallback in a format everything understands.

These helpers take an optional ratio instead of a size, leaving the width to the browser. #dynamic_image_tag renders at a size you pick; these render across a range of widths.

See Also:

Instance Method Summary collapse

Instance Method Details

#dynamic_picture(record_or_array, options = {}) ⇒ DynamicImage::Picture

Returns a Picture for the record, which is what the tag helpers render.

Examples:

picture = dynamic_picture(image, ratio: "16:9")
picture.srcset  # => "/images/… 420w, /images/… 590w, …"
picture.sources # => [{ type: "image/webp", srcset: "…" }]

Parameters:

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

  • (defaults to: {})

    sizing and routing options, as taken by Picture#initialize

Returns:



26
27
28
 
# File 'lib/dynamic_image/helper/pictures.rb', line 26

def dynamic_picture(record_or_array, options = {})
  DynamicImage::Picture.new(self, record_or_array, picture_options(options.symbolize_keys))
end

#dynamic_picture_source_tag(record_or_array, options = {}) ⇒ String?

Renders a single source element, for composing a picture by hand.

Use it for different crops per media query: several sources, each with its own crop and query. The browser takes the first one whose media matches and whose type it supports, so put the specific queries first and the unconditional one last.

Examples:

Different crops per media query

<picture>
  <%= dynamic_picture_source_tag(image, ratio: "21:9",
                                 media: "(min-width: 1000px)") %>
  <%= dynamic_picture_source_tag(image, ratio: "1:1") %>
  <%= dynamic_image_tag(image, size: "1200x1200", crop: true) %>
</picture>

A source for browsers without WebP

dynamic_picture_source_tag(image, ratio: "21:9",
                           format: DynamicImage::COMPATIBLE_FORMATS)

Parameters:

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

  • (defaults to: {})

    sizing and routing options

Options Hash (options):

  • :media (String) —

    The media query this source answers

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

    The format to render in. A symbol forces that format, an array is negotiated. Defaults to WebP.

Returns:

  • the source element



85
86
87
88
89
 
# File 'lib/dynamic_image/helper/pictures.rb', line 85

def dynamic_picture_source_tag(record_or_array, options = {})
  options = options.symbolize_keys

  picture_source_tag(dynamic_picture(record_or_array, options), options[:media])
end

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

Renders a responsive picture element.

The img carries the width and height of the fallback, which needn't match whichever candidate is chosen.

Any other options are passed on to DynamicImage::Helper#dynamic_image_tag.

Examples:

dynamic_picture_tag(image, sizes: "50vw", alt: "A kitten")
dynamic_picture_tag(image, ratio: "16:9", sizes: "50vw")

Parameters:

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

  • (defaults to: {})

    sizing options, routing options and HTML attributes

Options Hash (options):

  • :ratio (Numeric, Vector2d, String) —

    The aspect ratio to crop to. Implies cropping.

  • :sizes (String) —

    The sizes attribute, telling the browser how large the image will be rendered.

  • :breakpoints (Range, Array<Integer>, Integer) —

    The widths to offer, overriding DynamicImage#default_breakpoints

  • :step (Numeric) —

    The step between breakpoints, overriding DynamicImage#breakpoint_step

  • :fallback_width (Integer) —

    The width to ask for the img, overriding DynamicImage#picture_fallback_width

Returns:

  • the picture element



52
53
54
55
56
57
58
59
 
# File 'lib/dynamic_image/helper/pictures.rb', line 52

def dynamic_picture_tag(record_or_array, options = {})
  options = options.symbolize_keys
  picture = dynamic_picture(record_or_array, options)
  source = picture_source_tag(picture) unless picture.sources.empty?
  image = picture_fallback_tag(record_or_array, picture, options)

  tag.picture { safe_join([source, image].compact) }
end