• Stars
    star
    110
  • Rank 316,713 (Top 7 %)
  • Language
    Ruby
  • License
    BSD 2-Clause "Sim...
  • Created about 9 years ago
  • Updated 8 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A gem for integrating imgix into Rails projects

imgix logo

imgix-rails is a gem for integrating imgix into Ruby on Rails applications. It builds on imgix-rb to offer a few Rails-specific interfaces. It is tested under Ruby versions 3.1, 3.0, 2.7, and jruby-9.2.11.0.

Gem Version Build Status Downloads License FOSSA Status


Installation

Add this line to your application's Gemfile:

gem 'imgix-rails'

And then execute:

$ bundle

Usage

imgix-rails provides a few different hooks to work with your existing Rails application. All current methods are drop-in replacements for the image_tag helper.

Configuration

Before you get started, you will need to define your imgix configuration in your config/application.rb, or in an environment-specific configuration file.

Rails.application.configure do
  config.imgix = {
    source: "assets.imgix.net"
  }
end

The following configuration flags will be respected:

  • use_https: toggles the use of HTTPS. Defaults to true
  • source: a String or Array that specifies the imgix Source address. Should be in the form of "assets.imgix.net".
  • srcset_width_tolerance: an optional numeric value determining the maximum tolerance allowable, between the downloaded dimensions and rendered dimensions of the image (default 0.08 i.e. 8%).
  • secure_url_token: an optional secure URL token found in your dashboard (https://dashboard.imgix.com) used for signing requests
  • include_library_param: toggles the inclusion of the ixlib parameter. Defaults to true.

Multi-source configuration

In addition to the standard configuration flags, the following options can be used for multi-source support.

  • sources: a Hash of imgix source-secure_url_token key-value pairs. If the value for a source is nil, URLs generated for the corresponding source won't be secured. sources and source cannot be used together.
  • default_source: optionally specify a default source for generating URLs.

Example:

Rails.application.configure do
  config.imgix = {
    sources: {
      "assets.imgix.net"  => "foobarbaz",
      "assets2.imgix.net" => nil,   # Will generate unsigned URLs
    },
    default_source: "assets.imgix.net"
  }
end

ix_image_tag

The ix_image_tag helper method makes it easy to pass parameters to imgix to handle resizing, cropping, etc. It also simplifies adding responsive imagery to your Rails app by automatically generating a srcset based on the parameters you pass. We talk a bit about using the srcset attribute in an application in the following blog post: โ€œResponsive Images with srcset and imgix.โ€.

ix_image_tag generates <img> tags with a filled-out srcset attribute that leans on imgix-rb to do the hard work. It also makes a variety of options available for customizing how the srcset is generated. For example, if you already know the minimum or maximum number of physical pixels that this image will need to be displayed at, you can pass the min_width and/or max_width options. This will result in a smaller, more tailored srcset.

ix_image_tag takes the following arguments:

  • source: An optional String indicating the source to be used. If unspecified :source or :default_source will be used. If specified, the value must be defined in the config.
  • path: The path or URL of the image to display.
  • tag_options: HTML attributes to apply to the generated img element. This is useful for adding class names, alt tags, etc.
  • url_params: The imgix URL parameters to apply to this image. These will be applied to each URL in the srcset attribute, as well as the fallback src attribute.
  • srcset_options: A variety of options that allow for fine tuning srcset generation. More information on each of these modifiers can be found in the imgix-rb documentation. Any of the following can be passed as arguments:
    • widths: An array of exact widths that srcset pairs will be generated with.
    • min_width: The minimum width that srcset pairs will be generated with. Will be ignored if widths are provided.
    • max_width: The maximum width that srcset pairs will be generated with. Will be ignored if widths are provided.
    • disable_variable_quality: Pass true to disable variable quality parameters when generating a srcset (fixed-images only). In addition, imgix-rails will respect an overriding q (quality) parameter if one is provided through url_params.
    • attribute_options: Allow you to change where imgix-rails renders attributes. This can be helpful if you want to add lazy-loading.
<%= ix_image_tag('/unsplash/hotairballoon.jpg', url_params: { w: 300, h: 500, fit: 'crop', crop: 'right'}, tag_options: { alt: 'A hot air balloon on a sunny day' }) %>

Will render out HTML like the following:

<img
  alt="A hot air balloon on a sunny day"
  sizes="100vw"
  srcset="
    https://assets.imgix.net/unsplash/hotairballoon.jpg?w=100&amp;h=167&amp;fit=crop&amp;crop=right 100w,
    https://assets.imgix.net/unsplash/hotairballoon.jpg?w=200&amp;h=333&amp;fit=crop&amp;crop=right 200w,
    โ€ฆ
    https://assets.imgix.net/unsplash/hotairballoon.jpg?w=2560&amp;h=4267&amp;fit=crop&amp;crop=right 2560w
  "
  src="https://assets.imgix.net/unsplash/hotairballoon.jpg?w=300&amp;h=500&amp;fit=crop&amp;crop=right"
>

Similarly

<%= ix_image_tag('assets2.imgix.net', '/unsplash/hotairballoon.jpg') %>

Will generate URLs using assets2.imgix.net source.

We recommend leveraging this to generate powerful helpers within your application like the following:

def profile_image_tag(user)
  ix_image_tag(user.profile_image_url, url_params: { w: 100, h: 200, fit: 'crop' })
end

Then rendering the portrait in your application is very easy:

<%= profile_image_tag(@user) %>

If you already know all the exact widths you need images for, you can specify that by passing the widths option as an array. In this case, imgix-rails will only generate srcset pairs for the specified widths.

<%= ix_image_tag('/unsplash/hotairballoon.jpg', srcset_options: { widths: [320, 640, 960, 1280] }, tag_options: { alt: 'A hot air balloon on a sunny day' }) %>

Fixed image rendering

In cases where enough information is provided about an image's dimensions, ix_image_tag will instead build a srcset that will allow for an image to be served at different resolutions. The parameters taken into consideration when determining if an image is fixed-width are w, h, and ar. By invoking ix_image_tag with either a width or the height and aspect ratio (along with fit=crop, typically) provided, a different srcset will be generated for a fixed-size image instead.

<%= ix_image_tag('/unsplash/hotairballoon.jpg', url_params: {w: 1000}) %>

Will render the following HTML:

<img srcset="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=1&amp;q=75 1x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=2&amp;q=50 2x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=3&amp;q=35 3x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=4&amp;q=23 4x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=5&amp;q=20 5x" sizes="100vw" src="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000">

Fixed image rendering will automatically append a variable q parameter mapped to each dpr parameter when generating a srcset. This technique is commonly used to compensate for the increased filesize of high-DPR images. Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall filesize without sacrificing perceived visual quality. For more information and examples of this technique in action, see this blog post. This behavior will respect any overriding q value passed in via url_params and can be disabled altogether with srcset_options: { disable_variable_quality: true }.

Lazy loading

If you'd like to lazy load images, we recommend using lazysizes. In order to use imgix-rails with lazysizes, you need to use attribute_options as well as set tag_options[:src]:

<%= ix_image_tag('image.jpg', attribute_options: {src: "data-src",
srcset: "data-srcset", sizes: "data-sizes"}, url_params: {w: 1000},
tag_options: {src: "lqip.jpg"}) %>

Will render the following HTML:

<img data-srcset="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=1&amp;q=75 1x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=2&amp;q=50 2x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=3&amp;q=35 3x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=4&amp;q=23 4x,
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000&amp;dpr=5&amp;q=20 5x"
data-sizes="100vw"
data-src="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&amp;w=1000"
src="lqip.jpg">

ix_picture_tag

The ix_picture_tag helper method makes it easy to generate picture elements in your Rails app. picture elements are useful when an images needs to be art directed differently at different screen sizes.

ix_picture_tag takes the following arguments:

  • source: an optional String indicating the source to be used. If unspecified :source or :default_source will be used. If specified, the value must be defined in the config.
  • path: The path or URL of the image to display.
  • tag_options: Any options to apply to the parent picture element. This is useful for adding class names, etc.
  • img_tag_options: Any options to apply to the generated img element. This can be useful to add an alt attribute.
  • url_params: Default imgix options. These will be used to generate a fallback img tag for older browsers, and used in each source unless overridden by breakpoints.
  • breakpoints: A hash describing the variants. Each key must be a media query (e.g. (max-width: 880px)), and each value must be a hash of parameter overrides for that media query. A source element will be generated for each breakpoint specified.
  • srcset_options: A variety of options that allow for fine tuning srcset generation. More information on each of these modifiers can be found in the imgix-rb documentation. Any of the following can be passed as arguments:
    • widths: An array of exact widths that srcset pairs will be generated with.
    • min_width: The minimum width that srcset pairs will be generated with. Will be ignored if widths are provided.
    • max_width: The maximum width that srcset pairs will be generated with. Will be ignored if widths are provided.
    • disable_variable_quality: Pass true to disable variable quality parameters when generating a srcset (fixed-images only). In addition, imgix-rails will respect an overriding q (quality) parameter if one is provided through url_params.
<%= ix_picture_tag('bertandernie.jpg',
  tag_options: {
    class: 'a-picture-tag'
  },
  img_tag_options: {
    alt: 'A picture of Bert and Ernie arguing'
  },
  url_params: {
    w: 300,
    h: 300,
    fit: 'crop',
  },
  breakpoints: {
    '(max-width: 640px)' => {
      url_params: {
        h: 100,
      },
      tag_options: {
        sizes: 'calc(100vw - 20px)'
      }
    },
    '(max-width: 880px)' => {
      url_params: {
        crop: 'right',
      },
      tag_options: {
        sizes: 'calc(100vw - 20px - 50%)'
      }
    },
    '(min-width: 881px)' => {
      url_params: {
        crop: 'left',
      },
      tag_options: {
        sizes: '430px'
      }
    }
  }
) %>

To generate a picture element on a different source:

<%= ix_picture_tag('assets2.imgix.net', 'bertandernie.jpg',
      tag_options: {},
      img_tag_options: {},
      url_params: {},
      breakpoints: {
        '(max-width: 640px)' => {
          url_params: { h: 100 },
          tag_options: { sizes: 'calc(100vw - 20px)' }
        },
      }
   ) %>

ix_image_url

The ix_image_url helper makes it easy to generate a URL to an image in your Rails app.

ix_image_url takes three arguments:

  • source: an optional String indicating the source to be used. If unspecified :source or :default_source will be used. If specified, the value must be defined in the config.
  • path: The path or URL of the image to display.
  • options: The imgix URL parameters to apply to this image URL. Optionally, you can use disable_path_encoding: false for disabling URL-encoding which will be applied by default.
<%= ix_image_url('/users/1/avatar.png', { w: 400, h: 300 }) %>
<%= ix_image_url('assets2.imgix.net', '/users/1/avatar.png', { w: 400, h: 300, disable_path_encoding: true }) %>

Will generate the following URLs:

https://assets.imgix.net/users/1/avatar.png?w=400&h=300
https://assets2.imgix.net/users/1/avatar.png?w=400&h=300

Usage in Model

Since ix_image_url lives inside UrlHelper, it can also be used in places other than your views quite easily. This is useful for things such as including imgix URLs in JSON output from a serializer class.

include Imgix::Rails::UrlHelper

puts ix_image_url('/users/1/avatar.png', { w: 400, h: 300 })
# => https://assets.imgix.net/users/1/avatar.png?w=400&h=300

Alternatively, you can also use the imgix Ruby client in the same way.

Usage in Sprockets

ix_image_url is also pulled in as a Sprockets helper, so you can generate imgix URLs in your asset pipeline files. For example, here's how it would work inside an .scss.erb file:

.something {
  background-image: url(<%= ix_image_url('a-background.png', { w: 400, h: 300 }) %>);
}

Using With Image Uploading Libraries

imgix-rails plays well with image uploading libraries, because it just requires a URL and optional parameters as arguments. A good way to handle this interaction is by creating helpers that bridge between your uploading library of choice and imgix-rails. Below are examples of how this can work with some common libraries. Please submit an issue if you'd like to see specific examples for another!

Paperclip and CarrierWave

Paperclip and CarrierWave can directly provide paths to uploaded images, so we can use them with imgix-rails without a bridge.

<%= ix_image_tag(@user.avatar.path, { auto: 'format', fit: 'crop', w: 500}) %>

Refile

Since Refile doesn't actually store URLs or paths in the database (instead using a "prefix" + image identifier), the basic setup is slightly different. In this case, we use a couple helpers that bridge between Refile and imgix-rails.

module ImgixRefileHelper
  def ix_refile_image_url(obj, key, **opts)
    path = s3_path(obj, key)
    path ? ix_image_url(path, opts) : ''
  end

  def ix_refile_image_tag(obj, key, **opts)
    path = s3_path(obj, key)
    path ? ix_image_tag(path, opts) : ''
  end

private
  def s3_path(obj, key)
    refile_id = obj["#{key}_id"]
    s3_prefix = obj.send(key).try(:backend).instance_variable_get(:@prefix)

    s3_prefix ? "#{s3_prefix}/#{refile_id}" : nil
  end
end
<%= ix_refile_image_tag(@blog_post, :hero_photo, {auto: 'format', fit: 'crop', w: 500}) %>

Active Storage

To set up imgix with ActiveStorage, first ensure that the remote source your ActiveStorage service is pointing to is the same as your imgix source โ€” such as an s3 bucket.

S3

config/storage.yml

service: S3
access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
region: us-east-1
bucket: your_own_bucket

GCS

google:
  service: GCS
  project: Project Name
  credentials: <%= Rails.root.join("path/to/key.json") %>
  bucket: Bucket Name

Modify your active_storage.service setting depending on what environment you are using. For example, to use Amazon s3 in production, make the following change:

config/environments/production.rb

config.active_storage.service = :amazon

To use Google GCS in production, configure the active storage service like so:

config.active_storage.service = :google

As you would normally with imgix-rails, configure your application to point to your imgix source:

config/application.rb

Rails.application.configure do
      config.imgix = {
        source: your_domain,
        use_https: true,
        include_library_param: true
      }
end

Finally, the two can be used together by passing in the filename of the ActiveStorage blob into the imgix-rails helper function:

show.html.erb

<%= ix_image_tag(@your_model.image.key) %>

Upgrade Guides

3.x to 4.0

The v4.0.0 release of imgix-rails introduces a variety of improvements relating to how this gem handles and generates srcset attributes. However, in releasing this version there are some significant interface/behavioral changes that users need to be aware of. Users should note that the min_width and max_width fields (passed via tag_options), as well as the widths field, have all been moved to their own encompassing srcset_options field. This is done with the intention of providing a more organized and intuitive experience when fine-tuning how srcset width pairs are generated. See the following example demonstrating this new pattern:

<%= ix_image_tag('/unsplash/hotairballoon.jpg',
  srcset_options: { min_width: 1000, max_width: 2500},
  tag_options: { alt: 'A hot air balloon on a sunny day' }) %>

For users migrating to version 4.0 or later, it is important that all srcset-related modifiers be passed via srcset_options, as doing so through tag_options or widths directly will result in errors. For more details on these modifiers, please see the ix_image_tag or ix_picture_tag sections.

In addition to these changes, imgix-rails is now capable of producing fixed-image srcsets. Users should note that when certain dimension information is provided, imgix-rails will produce a srcset at different screen resolutions rather than the typical width pairs. This feature provides expanded functionality to cover more srcset use cases that users can take advantage of. We are always happy to provide our users with more tools to assist them in their efforts to build out responsive images on the web.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release to create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

See contributing guidelines.

Code of Conduct

Users contributing to or participating in the development of this project are subject to the terms of imgix's Code of Conduct.

License

FOSSA Status

More Repositories

1

drift

Easily add "zoom on hover" functionality to your site's images. Lightweight, no-dependency JavaScript.
JavaScript
1,527
star
2

imgix.js

Responsive images in the browser, simplified
JavaScript
965
star
3

luminous

A simple, lightweight, no-dependencies JavaScript lightbox
JavaScript
771
star
4

react-imgix

React component to display imgix images
JavaScript
360
star
5

prometheus-am-executor

Execute command based on Prometheus alerts
Go
234
star
6

js-core

A JavaScript client library for generating image URLs with imgix
JavaScript
122
star
7

imgix-php

A PHP client library for generating URLs with imgix
PHP
111
star
8

imgix-rb

A Ruby gem for generating image URLs with imgix
Ruby
76
star
9

jekyll-imgix

A plugin for integrating imgix into Jekyll sites
Ruby
51
star
10

motif

A simple Rails app to create responsive social images
HTML
41
star
11

imgix-url-params

Organized, machine-friendly documentation of imgix's URL parameters
39
star
12

imgix-python

A Python client library for generating URLs with imgix
Python
37
star
13

vue

A simple yet powerful integration between Vue and imgix
TypeScript
35
star
14

gatsby

A simple yet powerful integration between Gatsby and imgix
TypeScript
30
star
15

imgix-objc

Official imgix Objective-C client.
Objective-C
29
star
16

ember-cli-imgix

Easily add imgix functionality to your Ember application
JavaScript
26
star
17

imgix-swift

A Swift client library for generating URLs with imgix
Swift
25
star
18

magento

Browse, search, and insert image assets into your storefront quickly and easily via the imgix Image Manager.
JavaScript
21
star
19

imgix-emacs

An emacs major-mode for editing images via imgix.
Emacs Lisp
20
star
20

imgix-java

A Java client library for generating URLs with imgix
Java
19
star
21

django-imgix

Django module to provide imgix template tags and functions
Python
19
star
22

imgix-blueprint

Documentation for creating imgix libraries in different languages
18
star
23

imgix-statamic

An add-on for integrating imgix into Statamic sites
PHP
17
star
24

paperclip-imgix

Paperclip plugin to integrate with Imgix
Ruby
15
star
25

imgix-csharp

A C# client library for generating image URLs with imgix
C#
15
star
26

imgix-go

A Go client library for generating image URLs with imgix
Go
13
star
27

contentful

Browse, search, and add assets into your content quickly and easily via the imgix Asset Manager.
TypeScript
10
star
28

imgix-management-js

A Javascript library that wraps the imgix management API
JavaScript
7
star
29

typescript-imgix-url-params

TypeScript definitions of imgix's URL parameters
TypeScript
5
star
30

eddy

High-performance, maintenence-light, caching library and tools.
C
5
star
31

ix-video

An imgix video custom element that works anywhere
TypeScript
4
star
32

angular

A library for integrating imgix into Angular applications
TypeScript
4
star
33

fontmanager

Command line font manager for OS X
Objective-C
3
star
34

web-components

SDK web components shared across Frontend Frameworks - WIP
TypeScript
3
star
35

go-httpstring

fast http header string parser
Go
2
star
36

go-jobmanager

run subproc pools, on-demand grow and shrink, communicate with length-prefixed response, monitor RSS
Go
2
star
37

strapi-plugin-imgix

Strapi integration for imgix
TypeScript
2
star
38

renovate-config

A shareable Renovate bot configuration for all SDK repos
1
star
39

web-tools

Tools and configurations common to all imgix web projects
JavaScript
1
star
40

imgix-webfolder-router

A simple node.js router to allow multiple Base URLs for imgix Web Folders
JavaScript
1
star
41

nyt-example-app

Demos the imgix srcset API
HTML
1
star
42

sf-commerce-cloud

Use this integration to insert images from imgix's Image Manager into your Salesforce Commerce Cloud websites.
JavaScript
1
star
43

react-native-expo-example-app

Example Expo React Native application using @imgix/js-core to render a responsive image
JavaScript
1
star
44

shopify-integration-guide

Guide for integrating Shopify with imgix
1
star