imgix-rails 2.1.4 → 4.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +5 -5
- data/.github/CODEOWNERS +2 -0
- data/.github/ISSUE_TEMPLATE/bug_report.md +28 -0
- data/.github/ISSUE_TEMPLATE/feature_request.md +27 -0
- data/.github/ISSUE_TEMPLATE/question.md +17 -0
- data/.github/pull_request_template.md +73 -0
- data/.travis.yml +4 -3
- data/CHANGELOG.md +59 -0
- data/LICENSE +24 -0
- data/README.md +278 -107
- data/imgix-rails.gemspec +10 -4
- data/lib/imgix/rails/image_tag.rb +22 -5
- data/lib/imgix/rails/picture_tag.rb +23 -9
- data/lib/imgix/rails/tag.rb +16 -159
- data/lib/imgix/rails/url_helper.rb +101 -25
- data/lib/imgix/rails/version.rb +1 -1
- data/lib/imgix/rails/view_helper.rb +5 -4
- metadata +21 -18
- data/vendor/parameters.json +0 -1712
data/README.md
CHANGED
@@ -1,76 +1,120 @@
|
|
1
|
-
|
1
|
+
<!-- ix-docs-ignore -->
|
2
|
+
![imgix logo](https://assets.imgix.net/sdk-imgix-logo.svg)
|
3
|
+
|
4
|
+
`imgix-rails` is a gem for integrating [imgix](https://www.imgix.com/) into Ruby on Rails applications. It builds on [imgix-rb](https://github.com/imgix/imgix-rb) to offer a few Rails-specific interfaces.
|
5
|
+
|
6
|
+
[![Gem Version](https://img.shields.io/gem/v/imgix-rails.svg)](https://rubygems.org/gems/imgix-rails)
|
7
|
+
[![Build Status](https://travis-ci.com/imgix/imgix-rails.svg?branch=main)](https://travis-ci.com/imgix/imgix-rails)
|
8
|
+
![Downloads](https://img.shields.io/gem/dt/imgix-rails)
|
9
|
+
[![License](https://img.shields.io/github/license/imgix/imgix-rails)](https://github.com/imgix/imgix-rails/blob/main/LICENSE)
|
10
|
+
|
11
|
+
---
|
12
|
+
<!-- /ix-docs-ignore -->
|
13
|
+
|
14
|
+
- [Installation](#installation)
|
15
|
+
- [Usage](#usage)
|
16
|
+
- [Configuration](#configuration)
|
17
|
+
- [Multi-source configuration](#multi-source-configuration)
|
18
|
+
- [`ix_image_tag`](#iximagetag)
|
19
|
+
- [Fixed image rendering](#fixed-image-rendering)
|
20
|
+
- [Lazy Loading](#lazy-loading)
|
21
|
+
- [`ix_picture_tag`](#ixpicturetag)
|
22
|
+
- [`ix_image_url`](#iximageurl)
|
23
|
+
- [Usage in Model](#usage-in-model)
|
24
|
+
- [Usage in Sprockets](#usage-in-sprockets)
|
25
|
+
- [Using With Image Uploading Libraries](#using-with-image-uploading-libraries)
|
26
|
+
- [Paperclip and CarrierWave](#paperclip-and-carrierwave)
|
27
|
+
- [Refile](#refile)
|
28
|
+
- [Active Storage](#active-storage)
|
29
|
+
- [S3](#s3)
|
30
|
+
- [GCS](#gcs)
|
31
|
+
- [Upgrade Guides](#upgrade-guides)
|
32
|
+
- [3.x to 4.0](#3x-to-40)
|
33
|
+
- [Development](#development)
|
34
|
+
- [Contributing](#contributing)
|
35
|
+
- [Code of Conduct](#code-of-conduct)
|
2
36
|
|
3
|
-
# imgix-rails [![Build Status](https://travis-ci.org/imgix/imgix-rails.svg?branch=master)](https://travis-ci.org/imgix/imgix-rails) [![Slack Status](http://slack.imgix.com/badge.svg)](http://slack.imgix.com)
|
4
|
-
|
5
|
-
`imgix-rails` is a gem designed to make integrating imgix into your Rails app easier. It builds on [imgix-rb](https://github.com/imgix/imgix-rb) to offer a few Rails-specific interfaces.
|
6
|
-
|
7
|
-
imgix is a real-time image processing service and CDN. It allows you to manipulate images merely by changing their URL parameters. For a full list of URL parameters, please see the [imgix URL API documentation](https://www.imgix.com/docs/reference).
|
8
|
-
|
9
|
-
We recommend using something like [Paperclip](https://github.com/thoughtbot/paperclip), [Refile](https://github.com/refile/refile), [Carrierwave](https://github.com/carrierwaveuploader/carrierwave), or [s3_direct_upload](https://github.com/waynehoover/s3_direct_upload) to handle uploads. After they've been uploaded, you can then serve them using this gem.
|
10
|
-
|
11
|
-
* [Installation](#installation)
|
12
|
-
* [Usage](#usage)
|
13
|
-
* [Configuration](#configuration)
|
14
|
-
* [ix_image_tag](#ix_image_tag)
|
15
|
-
* [ix_picture_tag](#ix_picture_tag)
|
16
|
-
* [ix_image_url](#ix_image_url)
|
17
|
-
* [Usage in Sprockets](#usage-in-sprockets)
|
18
|
-
* [Hostname Removal](#hostname-removal)
|
19
|
-
* [Using With Image Uploading Libraries](#using-with-image-uploading-libraries)
|
20
|
-
* [Paperclip and CarrierWave](#paperclip-and-carrierwave)
|
21
|
-
* [Refile](#refile)
|
22
|
-
* [Development](#development)
|
23
|
-
* [Contributing](#contributing)
|
24
|
-
|
25
|
-
|
26
|
-
<a name="installation"></a>
|
27
37
|
## Installation
|
28
38
|
|
29
39
|
Add this line to your application's Gemfile:
|
30
40
|
|
31
|
-
```
|
41
|
+
```rb
|
32
42
|
gem 'imgix-rails'
|
33
43
|
```
|
34
44
|
|
35
45
|
And then execute:
|
36
46
|
|
37
|
-
|
38
|
-
|
47
|
+
```bash
|
48
|
+
$ bundle
|
49
|
+
```
|
39
50
|
|
40
|
-
<a name="usage"></a>
|
41
51
|
## Usage
|
42
52
|
|
43
53
|
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.
|
44
54
|
|
45
|
-
<a name="configuration"></a>
|
46
55
|
### Configuration
|
47
56
|
|
48
57
|
Before you get started, you will need to define your imgix configuration in your `config/application.rb`, or in an environment-specific configuration file.
|
49
58
|
|
50
|
-
```
|
59
|
+
```rb
|
51
60
|
Rails.application.configure do
|
52
61
|
config.imgix = {
|
53
|
-
source: "
|
62
|
+
source: "assets.imgix.net"
|
54
63
|
}
|
55
64
|
end
|
56
65
|
```
|
57
66
|
|
58
67
|
The following configuration flags will be respected:
|
59
68
|
|
60
|
-
- `:
|
61
|
-
- `:
|
62
|
-
- `:
|
63
|
-
- `:
|
69
|
+
- `use_https`: toggles the use of HTTPS. Defaults to `true`
|
70
|
+
- `source`: a String or Array that specifies the imgix Source address. Should be in the form of `"assets.imgix.net"`.
|
71
|
+
- `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%`).
|
72
|
+
- `secure_url_token`: an optional secure URL token found in your dashboard (https://dashboard.imgix.com) used for signing requests
|
73
|
+
- `include_library_param`: toggles the inclusion of the [`ixlib` parameter](https://github.com/imgix/imgix-rb#what-is-the-ixlib-param-on-every-request). Defaults to `true`.
|
74
|
+
|
75
|
+
#### Multi-source configuration
|
64
76
|
|
65
|
-
|
66
|
-
### ix_image_tag
|
77
|
+
In addition to the standard configuration flags, the following options can be used for multi-source support.
|
67
78
|
|
68
|
-
|
79
|
+
- `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.
|
80
|
+
- `default_source`: optionally specify a default source for generating URLs.
|
69
81
|
|
70
|
-
|
82
|
+
Example:
|
83
|
+
|
84
|
+
```rb
|
85
|
+
Rails.application.configure do
|
86
|
+
config.imgix = {
|
87
|
+
sources: {
|
88
|
+
"assets.imgix.net" => "foobarbaz",
|
89
|
+
"assets2.imgix.net" => nil, # Will generate unsigned URLs
|
90
|
+
},
|
91
|
+
default_source: "assets.imgix.net"
|
92
|
+
}
|
93
|
+
end
|
94
|
+
```
|
95
|
+
|
96
|
+
### `ix_image_tag`
|
97
|
+
|
98
|
+
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.”](https://docs.imgix.com/tutorials/responsive-images-srcset-imgix?_ga=utm_medium=referral&utm_source=sdk&utm_campaign=rails-readme).
|
99
|
+
|
100
|
+
`ix_image_tag` generates `<img>` tags with a filled-out `srcset` attribute that leans on [imgix-rb](https://github.com/imgix/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`.
|
101
|
+
|
102
|
+
`ix_image_tag` takes the following arguments:
|
103
|
+
|
104
|
+
* `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.
|
105
|
+
* `path`: The path or URL of the image to display.
|
106
|
+
* `tag_options`: HTML attributes to apply to the generated `img` element. This is useful for adding class names, alt tags, etc.
|
107
|
+
* `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.
|
108
|
+
* `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](https://github.com/imgix/imgix-rb#srcset-generation). Any of the following can be passed as arguments:
|
109
|
+
* [`widths`](https://github.com/imgix/imgix-rb#custom-widths): An array of exact widths that `srcset` pairs will be generated with.
|
110
|
+
* [`min_width`](https://github.com/imgix/imgix-rb#minimum-and-maximum-width-ranges): The minimum width that `srcset` pairs will be generated with. Will be ignored if `widths` are provided.
|
111
|
+
* [`max_width`](https://github.com/imgix/imgix-rb#minimum-and-maximum-width-ranges): The maximum width that `srcset` pairs will be generated with. Will be ignored if `widths` are provided.
|
112
|
+
* [`disable_variable_quality`](https://github.com/imgix/imgix-rb#variable-qualities): Pass `true` to disable variable quality parameters when generating a `srcset` ([fixed-images only](https://github.com/imgix/imgix-rails#fixed-image-rendering)). In addition, imgix-rails will respect an overriding `q` (quality) parameter if one is provided through `url_params`.
|
113
|
+
* `attribute_options`: Allow you to change where imgix-rails renders
|
114
|
+
attributes. This can be helpful if you want to add lazy-loading.
|
71
115
|
|
72
116
|
```erb
|
73
|
-
<%= ix_image_tag('/unsplash/hotairballoon.jpg', { w: 300, h: 500, fit: 'crop', crop: 'right', alt: 'A hot air balloon on a sunny day' }) %>
|
117
|
+
<%= 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' }) %>
|
74
118
|
```
|
75
119
|
|
76
120
|
Will render out HTML like the following:
|
@@ -89,11 +133,19 @@ Will render out HTML like the following:
|
|
89
133
|
>
|
90
134
|
```
|
91
135
|
|
136
|
+
Similarly
|
137
|
+
|
138
|
+
```erb
|
139
|
+
<%= ix_image_tag('assets2.imgix.net', '/unsplash/hotairballoon.jpg') %>
|
140
|
+
```
|
141
|
+
|
142
|
+
Will generate URLs using `assets2.imgix.net` source.
|
143
|
+
|
92
144
|
We recommend leveraging this to generate powerful helpers within your application like the following:
|
93
145
|
|
94
|
-
```
|
146
|
+
```rb
|
95
147
|
def profile_image_tag(user)
|
96
|
-
ix_image_tag(user.profile_image_url, { w: 100, h: 200, fit: 'crop' })
|
148
|
+
ix_image_tag(user.profile_image_url, url_params: { w: 100, h: 200, fit: 'crop' })
|
97
149
|
end
|
98
150
|
```
|
99
151
|
|
@@ -106,78 +158,161 @@ Then rendering the portrait in your application is very easy:
|
|
106
158
|
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`.
|
107
159
|
|
108
160
|
```erb
|
109
|
-
<%= ix_image_tag('/unsplash/hotairballoon.jpg', { widths: [320, 640, 960, 1280]
|
161
|
+
<%= ix_image_tag('/unsplash/hotairballoon.jpg', srcset_options: { widths: [320, 640, 960, 1280] }, tag_options: { alt: 'A hot air balloon on a sunny day' }) %>
|
162
|
+
```
|
163
|
+
|
164
|
+
#### Fixed image rendering
|
165
|
+
|
166
|
+
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.
|
167
|
+
|
168
|
+
```erb
|
169
|
+
<%= ix_image_tag('/unsplash/hotairballoon.jpg', url_params: {w: 1000}) %>
|
170
|
+
```
|
171
|
+
|
172
|
+
Will render the following HTML:
|
173
|
+
|
174
|
+
```html
|
175
|
+
<img srcset="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=1&q=75 1x,
|
176
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=2&q=50 2x,
|
177
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=3&q=35 3x,
|
178
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=4&q=23 4x,
|
179
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=5&q=20 5x" sizes="100vw" src="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000">
|
110
180
|
```
|
111
181
|
|
182
|
+
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](https://blog.imgix.com/2016/03/30/dpr-quality?_ga=utm_medium=referral&utm_source=sdk&utm_campaign=rails-readme). 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 }`.
|
183
|
+
|
184
|
+
#### Lazy loading
|
112
185
|
|
113
|
-
|
114
|
-
|
186
|
+
If you'd like to lazy load images, we recommend using [lazysizes](https://github.com/aFarkas/lazysizes). In order to use imgix-rails with lazysizes, you need to use `attribute_options` as well as set `tag_options[:src]`:
|
187
|
+
|
188
|
+
```erb
|
189
|
+
<%= ix_image_tag('image.jpg', attribute_options: {src: "data-src",
|
190
|
+
srcset: "data-srcset", sizes: "data-sizes"}, url_params: {w: 1000},
|
191
|
+
tag_options: {src: "lqip.jpg"}) %>
|
192
|
+
```
|
193
|
+
|
194
|
+
Will render the following HTML:
|
195
|
+
|
196
|
+
```html
|
197
|
+
<img data-srcset="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=1&q=75 1x,
|
198
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=2&q=50 2x,
|
199
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=3&q=35 3x,
|
200
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=4&q=23 4x,
|
201
|
+
https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000&dpr=5&q=20 5x"
|
202
|
+
data-sizes="100vw"
|
203
|
+
data-src="https://assets.imgix.net/image.jpg?ixlib=rails-3.0.2&w=1000"
|
204
|
+
src="lqip.jpg">
|
205
|
+
```
|
206
|
+
|
207
|
+
### `ix_picture_tag`
|
115
208
|
|
116
209
|
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.
|
117
210
|
|
118
|
-
`ix_picture_tag` takes
|
211
|
+
`ix_picture_tag` takes the following arguments:
|
119
212
|
|
120
|
-
* `source`:
|
121
|
-
* `
|
122
|
-
* `
|
123
|
-
* `
|
213
|
+
* `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.
|
214
|
+
* `path`: The path or URL of the image to display.
|
215
|
+
* `tag_options`: Any options to apply to the parent `picture` element. This is useful for adding class names, etc.
|
216
|
+
* `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`.
|
217
|
+
* `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.
|
218
|
+
* `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](https://github.com/imgix/imgix-rb#srcset-generation). Any of the following can be passed as arguments:
|
219
|
+
* [`widths`](https://github.com/imgix/imgix-rb#custom-widths): An array of exact widths that `srcset` pairs will be generated with.
|
220
|
+
* [`min_width`](https://github.com/imgix/imgix-rb#minimum-and-maximum-width-ranges): The minimum width that `srcset` pairs will be generated with. Will be ignored if `widths` are provided.
|
221
|
+
* [`max_width`](https://github.com/imgix/imgix-rb#minimum-and-maximum-width-ranges): The maximum width that `srcset` pairs will be generated with. Will be ignored if `widths` are provided.
|
222
|
+
* [`disable_variable_quality`](https://github.com/imgix/imgix-rb#variable-qualities): Pass `true` to disable variable quality parameters when generating a `srcset` ([fixed-images only](https://github.com/imgix/imgix-rails#fixed-image-rendering)). In addition, imgix-rails will respect an overriding `q` (quality) parameter if one is provided through `url_params`.
|
124
223
|
|
125
224
|
```erb
|
126
225
|
<%= ix_picture_tag('bertandernie.jpg',
|
127
|
-
|
226
|
+
tag_options: {
|
128
227
|
class: 'a-picture-tag'
|
129
228
|
},
|
130
|
-
|
229
|
+
url_params: {
|
131
230
|
w: 300,
|
132
231
|
h: 300,
|
133
232
|
fit: 'crop',
|
134
233
|
},
|
135
234
|
breakpoints: {
|
136
235
|
'(max-width: 640px)' => {
|
137
|
-
|
138
|
-
|
236
|
+
url_params: {
|
237
|
+
h: 100,
|
238
|
+
},
|
239
|
+
tag_options: {
|
240
|
+
sizes: 'calc(100vw - 20px)'
|
241
|
+
}
|
139
242
|
},
|
140
243
|
'(max-width: 880px)' => {
|
141
|
-
|
142
|
-
|
244
|
+
url_params: {
|
245
|
+
crop: 'right',
|
246
|
+
},
|
247
|
+
tag_options: {
|
248
|
+
sizes: 'calc(100vw - 20px - 50%)'
|
249
|
+
}
|
143
250
|
},
|
144
251
|
'(min-width: 881px)' => {
|
145
|
-
|
146
|
-
|
252
|
+
url_params: {
|
253
|
+
crop: 'left',
|
254
|
+
},
|
255
|
+
tag_options: {
|
256
|
+
sizes: '430px'
|
257
|
+
}
|
147
258
|
}
|
148
259
|
}
|
149
260
|
) %>
|
150
261
|
```
|
151
262
|
|
263
|
+
To generate a `picture` element on a different source:
|
152
264
|
|
153
|
-
|
154
|
-
|
265
|
+
```erb
|
266
|
+
<%= ix_picture_tag('assets2.imgix.net', 'bertandernie.jpg',
|
267
|
+
tag_options: {},
|
268
|
+
url_params: {},
|
269
|
+
breakpoints: {
|
270
|
+
'(max-width: 640px)' => {
|
271
|
+
url_params: { h: 100 },
|
272
|
+
tag_options: { sizes: 'calc(100vw - 20px)' }
|
273
|
+
},
|
274
|
+
}
|
275
|
+
) %>
|
276
|
+
```
|
277
|
+
|
278
|
+
### `ix_image_url`
|
155
279
|
|
156
280
|
The `ix_image_url` helper makes it easy to generate a URL to an image in your Rails app.
|
157
281
|
|
282
|
+
`ix_image_url` takes three arguments:
|
283
|
+
|
284
|
+
* `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.
|
285
|
+
* `path`: The path or URL of the image to display.
|
286
|
+
* `options`: The imgix URL parameters to apply to this image URL.
|
287
|
+
|
158
288
|
```erb
|
159
289
|
<%= ix_image_url('/users/1/avatar.png', { w: 400, h: 300 }) %>
|
290
|
+
<%= ix_image_url('assets2.imgix.net', '/users/1/avatar.png', { w: 400, h: 300 }) %>
|
160
291
|
```
|
161
292
|
|
162
|
-
Will generate the following
|
293
|
+
Will generate the following URLs:
|
163
294
|
|
164
295
|
```html
|
165
296
|
https://assets.imgix.net/users/1/avatar.png?w=400&h=300
|
297
|
+
https://assets2.imgix.net/users/1/avatar.png?w=400&h=300
|
166
298
|
```
|
167
299
|
|
300
|
+
#### Usage in Model
|
301
|
+
|
168
302
|
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.
|
169
303
|
|
170
|
-
```
|
304
|
+
```rb
|
171
305
|
include Imgix::Rails::UrlHelper
|
172
306
|
|
173
307
|
puts ix_image_url('/users/1/avatar.png', { w: 400, h: 300 })
|
174
308
|
# => https://assets.imgix.net/users/1/avatar.png?w=400&h=300
|
175
309
|
```
|
176
310
|
|
177
|
-
|
311
|
+
Alternatively, you can also use the imgix [Ruby client](https://github.com/imgix/imgix-rb) in the same way.
|
312
|
+
|
178
313
|
#### Usage in Sprockets
|
179
314
|
|
180
|
-
`ix_image_url` is also pulled in as a Sprockets helper, so you can generate imgix URLs in your asset
|
315
|
+
`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:
|
181
316
|
|
182
317
|
```scss
|
183
318
|
.something {
|
@@ -185,47 +320,10 @@ puts ix_image_url('/users/1/avatar.png', { w: 400, h: 300 })
|
|
185
320
|
}
|
186
321
|
```
|
187
322
|
|
188
|
-
### Hostname Removal
|
189
|
-
|
190
|
-
You can also configure imgix-rails to disregard given hostnames and only use the path component from given URLs. This is useful if you have [a Web Folder or an Amazon S3 imgix Source configured](https://www.imgix.com/docs/tutorials/creating-sources) but store the fully-qualified URLs for those resources in your database.
|
191
|
-
|
192
|
-
For example, let's say you are using S3 for storage. An `#avatar_url` value might look like the following in your application:
|
193
|
-
|
194
|
-
```ruby
|
195
|
-
@user.avatar_url #=> "https://s3.amazonaws.com/my-bucket/users/1.png"
|
196
|
-
```
|
197
|
-
|
198
|
-
You would then configure imgix in your Rails application to disregard the `'s3.amazonaws.com'` hostname:
|
199
|
-
|
200
|
-
```ruby
|
201
|
-
Rails.application.configure do
|
202
|
-
config.imgix = {
|
203
|
-
source: "my-imgix-source.imgix.net",
|
204
|
-
hostname_to_replace: "s3.amazonaws.com"
|
205
|
-
}
|
206
|
-
end
|
207
|
-
```
|
208
|
-
|
209
|
-
Now when you call `ix_image_tag` or another helper, you get an imgix URL:
|
210
|
-
|
211
|
-
```erb
|
212
|
-
<%= ix_image_tag(@user.avatar_url) %>
|
213
|
-
```
|
214
|
-
|
215
|
-
Renders:
|
216
|
-
|
217
|
-
```html
|
218
|
-
<img src="https://my-imgix-source.imgix.net/my-bucket/users/1.png" />
|
219
|
-
```
|
220
|
-
|
221
|
-
|
222
|
-
<a name="using-with-image-uploading-libraries"></a>
|
223
323
|
## Using With Image Uploading Libraries
|
224
324
|
|
225
325
|
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!
|
226
326
|
|
227
|
-
|
228
|
-
<a name="paperclip-and-carrierwave"></a>
|
229
327
|
### Paperclip and CarrierWave
|
230
328
|
|
231
329
|
Paperclip and CarrierWave can directly provide paths to uploaded images, so we can use them with imgix-rails without a bridge.
|
@@ -234,8 +332,6 @@ Paperclip and CarrierWave can directly provide paths to uploaded images, so we c
|
|
234
332
|
<%= ix_image_tag(@user.avatar.path, { auto: 'format', fit: 'crop', w: 500}) %>
|
235
333
|
```
|
236
334
|
|
237
|
-
|
238
|
-
<a name="refile"></a>
|
239
335
|
### Refile
|
240
336
|
|
241
337
|
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.
|
@@ -266,16 +362,88 @@ end
|
|
266
362
|
<%= ix_refile_image_tag(@blog_post, :hero_photo, {auto: 'format', fit: 'crop', w: 500}) %>
|
267
363
|
```
|
268
364
|
|
365
|
+
### Active Storage
|
366
|
+
|
367
|
+
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.
|
368
|
+
|
369
|
+
### S3
|
370
|
+
**config/storage.yml**
|
371
|
+
|
372
|
+
```yml
|
373
|
+
service: S3
|
374
|
+
access_key_id: <%= Rails.application.credentials.dig(:aws, :access_key_id) %>
|
375
|
+
secret_access_key: <%= Rails.application.credentials.dig(:aws, :secret_access_key) %>
|
376
|
+
region: us-east-1
|
377
|
+
bucket: your_own_bucket
|
378
|
+
```
|
379
|
+
|
380
|
+
### GCS
|
381
|
+
```yml
|
382
|
+
google:
|
383
|
+
service: GCS
|
384
|
+
project: Project Name
|
385
|
+
credentials: <%= Rails.root.join("path/to/key.json") %>
|
386
|
+
bucket: Bucket Name
|
387
|
+
```
|
388
|
+
|
389
|
+
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:
|
390
|
+
|
391
|
+
**config/environments/production.rb**
|
392
|
+
|
393
|
+
```rb
|
394
|
+
config.active_storage.service = :amazon
|
395
|
+
```
|
396
|
+
|
397
|
+
To use Google GCS in production, configure the active storage service like so:
|
398
|
+
|
399
|
+
```rb
|
400
|
+
config.active_storage.service = :google
|
401
|
+
```
|
402
|
+
|
403
|
+
As you would normally with imgix-rails, configure your application to point to your imgix source:
|
404
|
+
|
405
|
+
**config/application.rb**
|
406
|
+
|
407
|
+
```rb
|
408
|
+
Rails.application.configure do
|
409
|
+
config.imgix = {
|
410
|
+
source: your_domain,
|
411
|
+
use_https: true,
|
412
|
+
include_library_param: true
|
413
|
+
}
|
414
|
+
end
|
415
|
+
```
|
416
|
+
|
417
|
+
Finally, the two can be used together by passing in the filename of the ActiveStorage blob into the imgix-rails helper function:
|
418
|
+
|
419
|
+
**show.html.erb**
|
420
|
+
|
421
|
+
```erb
|
422
|
+
<%= ix_image_tag(@your_model.image.key) %>
|
423
|
+
```
|
424
|
+
|
425
|
+
## Upgrade Guides
|
426
|
+
|
427
|
+
### 3.x to 4.0
|
428
|
+
|
429
|
+
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:
|
430
|
+
|
431
|
+
```erb
|
432
|
+
<%= ix_image_tag('/unsplash/hotairballoon.jpg',
|
433
|
+
srcset_options: { min_width: 1000, max_width: 2500},
|
434
|
+
tag_options: { alt: 'A hot air balloon on a sunny day' }) %>
|
435
|
+
```
|
436
|
+
|
437
|
+
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](https://github.com/imgix/imgix-rails#ix_image_tag) or [ix_picture_tag](https://github.com/imgix/imgix-rails#ix_picture_tag) sections.
|
438
|
+
|
439
|
+
In addition to these changes, imgix-rails is now capable of producing [fixed-image srcsets](https://github.com/imgix/imgix-rb#fixed-image-rendering). 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.
|
269
440
|
|
270
|
-
<a name="development"></a>
|
271
441
|
## Development
|
272
442
|
|
273
443
|
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.
|
274
444
|
|
275
445
|
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](https://rubygems.org).
|
276
446
|
|
277
|
-
|
278
|
-
<a name="contributing"></a>
|
279
447
|
## Contributing
|
280
448
|
|
281
449
|
1. Fork it ( https://github.com/[my-github-username]/imgix-rails/fork )
|
@@ -283,3 +451,6 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
|
|
283
451
|
3. Commit your changes (`git commit -am 'Add some feature'`)
|
284
452
|
4. Push to the branch (`git push origin my-new-feature`)
|
285
453
|
5. Create a new Pull Request
|
454
|
+
|
455
|
+
## Code of Conduct
|
456
|
+
Users contributing to or participating in the development of this project are subject to the terms of imgix's [Code of Conduct](https://github.com/imgix/code-of-conduct).
|
data/imgix-rails.gemspec
CHANGED
@@ -8,12 +8,18 @@ Gem::Specification.new do |spec|
|
|
8
8
|
spec.version = Imgix::Rails::VERSION
|
9
9
|
spec.authors = ["Kelly Sutton", "Paul Straw"]
|
10
10
|
spec.email = ["kelly@imgix.com", "ixemail"]
|
11
|
-
spec.licenses = ["
|
11
|
+
spec.licenses = ["BSD-2-Clause"]
|
12
12
|
|
13
13
|
spec.summary = %q{Makes integrating imgix into your Rails app easier. It builds on imgix-rb to offer a few Rails-specific interfaces.}
|
14
14
|
spec.description = %q{Makes integrating imgix into your Rails app easier. It builds on imgix-rb to offer a few Rails-specific interfaces. Please see https://github.com/imgix/imgix-rails for more details.}
|
15
15
|
spec.homepage = "https://github.com/imgix/imgix-rails"
|
16
16
|
|
17
|
+
spec.metadata = {
|
18
|
+
'bug_tracker_uri' => 'https://github.com/imgix/imgix-rails/issues',
|
19
|
+
'changelog_uri' => 'https://github.com/imgix/imgix-rails/blob/main/CHANGELOG.md',
|
20
|
+
'documentation_uri' => "https://www.rubydoc.info/gems/imgix-rails/#{spec.version}",
|
21
|
+
'source_code_uri' => "https://github.com/imgix/imgix-rails/tree/v#{spec.version}"
|
22
|
+
}
|
17
23
|
# Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
|
18
24
|
# delete this section to allow pushing this gem to any host.
|
19
25
|
if spec.respond_to?(:metadata)
|
@@ -27,10 +33,10 @@ Gem::Specification.new do |spec|
|
|
27
33
|
spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
|
28
34
|
spec.require_paths = ["lib"]
|
29
35
|
|
30
|
-
spec.add_runtime_dependency "imgix", "
|
36
|
+
spec.add_runtime_dependency "imgix", ">= 3.0"
|
31
37
|
|
32
|
-
spec.add_development_dependency "bundler", "
|
33
|
-
spec.add_development_dependency "rake", "~>
|
38
|
+
spec.add_development_dependency "bundler", ">=1.9"
|
39
|
+
spec.add_development_dependency "rake", "~> 12.3"
|
34
40
|
spec.add_development_dependency "rspec"
|
35
41
|
spec.add_development_dependency "rspec-rails"
|
36
42
|
end
|
@@ -1,13 +1,30 @@
|
|
1
1
|
require "imgix/rails/tag"
|
2
2
|
|
3
3
|
class Imgix::Rails::ImageTag < Imgix::Rails::Tag
|
4
|
+
|
4
5
|
def render
|
5
|
-
|
6
|
-
|
6
|
+
url = ix_image_url(@source, @path, @url_params)
|
7
|
+
|
8
|
+
if @attribute_options[:srcset].present?
|
9
|
+
@tag_options[@attribute_options[:srcset]] = srcset
|
10
|
+
else
|
11
|
+
@tag_options[:srcset] = srcset
|
12
|
+
end
|
13
|
+
|
14
|
+
if @attribute_options[:size].present?
|
15
|
+
@tag_options[@attribute_options[:size]] ||= '100vw'
|
16
|
+
else
|
17
|
+
@tag_options[:sizes] ||= '100vw'
|
18
|
+
end
|
7
19
|
|
8
|
-
|
9
|
-
|
20
|
+
if @attribute_options[:src].present?
|
21
|
+
@tag_options[@attribute_options[:src]] = url
|
22
|
+
end
|
10
23
|
|
11
|
-
|
24
|
+
if @tag_options[:src].present?
|
25
|
+
image_tag(@tag_options[:src], @tag_options)
|
26
|
+
else
|
27
|
+
image_tag(url, @tag_options)
|
28
|
+
end
|
12
29
|
end
|
13
30
|
end
|
@@ -1,28 +1,42 @@
|
|
1
1
|
require "imgix/rails/tag"
|
2
2
|
require "imgix/rails/image_tag"
|
3
|
+
require "action_view"
|
3
4
|
|
4
5
|
class Imgix::Rails::PictureTag < Imgix::Rails::Tag
|
5
6
|
include ActionView::Context
|
6
7
|
|
7
|
-
def initialize(source,
|
8
|
+
def initialize(path, source: nil, tag_options: {}, url_params: {}, breakpoints: {}, srcset_options: {})
|
9
|
+
@path = path
|
8
10
|
@source = source
|
9
|
-
@
|
10
|
-
@
|
11
|
+
@tag_options = tag_options
|
12
|
+
@url_params = url_params
|
11
13
|
@breakpoints = breakpoints
|
14
|
+
@srcset_options = srcset_options
|
12
15
|
end
|
13
16
|
|
14
17
|
def render
|
15
|
-
content_tag(:picture, @
|
18
|
+
content_tag(:picture, @tag_options) do
|
16
19
|
@breakpoints.each do |media, opts|
|
17
|
-
|
18
|
-
html_opts[:media] ||= media
|
19
|
-
html_opts[:srcset] ||= srcset(@default_options.clone.merge(opts))
|
20
|
+
validate_opts(opts)
|
20
21
|
|
22
|
+
source_tag_opts = opts[:tag_options] || {}
|
23
|
+
source_tag_url_params = opts[:url_params] || {}
|
24
|
+
srcset_options = opts[:srcset_options] || {}
|
25
|
+
source_tag_opts[:media] ||= media
|
26
|
+
source_tag_opts[:srcset] ||= srcset(url_params: @url_params.clone.merge(source_tag_url_params), srcset_options: srcset_options)
|
21
27
|
|
22
|
-
concat(content_tag(:source, nil,
|
28
|
+
concat(content_tag(:source, nil, source_tag_opts))
|
23
29
|
end
|
24
30
|
|
25
|
-
concat Imgix::Rails::ImageTag.new(@source, @
|
31
|
+
concat Imgix::Rails::ImageTag.new(@path, source: @source, url_params: @url_params, srcset_options: @srcset_options).render
|
26
32
|
end
|
27
33
|
end
|
34
|
+
|
35
|
+
private
|
36
|
+
def validate_opts(opts = {})
|
37
|
+
unsupported_opts = opts.except(:tag_options, :url_params, :srcset_options)
|
38
|
+
if unsupported_opts.length > 0
|
39
|
+
raise "'#{unsupported_opts.keys.join("', '")}' key(s) not supported; use tag_options, url_params, srcset_options."
|
40
|
+
end
|
41
|
+
end
|
28
42
|
end
|