imgix 3.1.0 → 3.3.1
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 +15 -13
- data/CHANGELOG.md +32 -1
- data/README.md +149 -21
- data/imgix.gemspec +7 -0
- data/lib/imgix.rb +32 -8
- data/lib/imgix/client.rb +47 -15
- data/lib/imgix/param_helpers.rb +1 -0
- data/lib/imgix/path.rb +115 -44
- data/lib/imgix/version.rb +1 -1
- data/test/units/param_helpers_test.rb +23 -0
- data/test/units/path_test.rb +54 -4
- data/test/units/srcset_test.rb +751 -222
- data/test/units/url_test.rb +47 -5
- metadata +15 -5
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
|
-
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
2
|
+
SHA256:
|
|
3
|
+
metadata.gz: 1af83e026e72b6ce6bfcfdf1169add23c12cbec68a7d7fbe03243150c832b34b
|
|
4
|
+
data.tar.gz: 3a7e0d57c3f65b75327e226918370771f7bb579284228de9e6de77d694d4fadc
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 0a68e202aaa183a4974d9c15a20e97f404269879da403cb7a949c04dd5ba3053e4b4802aa2a7006826f357a4268f87fd20d14971034e598d792e18a5cd2b322d
|
|
7
|
+
data.tar.gz: e1f068f01a5cd8cac1b959bd16f9e2d586a72278a6b4be844a822c74a41c7b7e110471c36a4bf156b6ec6c17cbcc5e425ebdf40373b2424ce3360bd1ada391d2
|
data/.github/CODEOWNERS
ADDED
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Bug report
|
|
3
|
+
about: Create a report to help us improve
|
|
4
|
+
title: ''
|
|
5
|
+
labels: bug
|
|
6
|
+
assignees:
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
Please provide the following information and someone from @imgix/imgix-sdk-team will respond to your issue shortly.
|
|
11
|
+
|
|
12
|
+
**Describe the bug**
|
|
13
|
+
A clear and concise description of what the bug is.
|
|
14
|
+
|
|
15
|
+
**To Reproduce**
|
|
16
|
+
Steps to reproduce the behavior:
|
|
17
|
+
|
|
18
|
+
**Expected behavior**
|
|
19
|
+
A clear and concise description of what you expected to happen.
|
|
20
|
+
|
|
21
|
+
**Screenshots**
|
|
22
|
+
If applicable, add screenshots to help explain your problem.
|
|
23
|
+
|
|
24
|
+
**Information:**
|
|
25
|
+
- imgix-rb version: [e.g. 2.0.0]
|
|
26
|
+
|
|
27
|
+
**Additional context**
|
|
28
|
+
Add any other context about the problem here.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Feature request
|
|
3
|
+
about: Suggest an idea for this project
|
|
4
|
+
title: ''
|
|
5
|
+
labels: ''
|
|
6
|
+
assignees:
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
Please provide the following information and someone from @imgix/imgix-sdk-team will respond to your issue shortly.
|
|
11
|
+
|
|
12
|
+
**Before you submit:**
|
|
13
|
+
|
|
14
|
+
- [ ] Please search through the [existing issues](https://github.com/imgix/imgix-rb/issues?utf8=%E2%9C%93&q=is%3Aissue) to see if your feature has already been discussed.
|
|
15
|
+
- [ ] Please take a moment to find out whether your idea fits with the scope and aims of this project.
|
|
16
|
+
|
|
17
|
+
**Is your feature request related to a problem? Please describe.**
|
|
18
|
+
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
|
|
19
|
+
|
|
20
|
+
**Describe the solution you'd like**
|
|
21
|
+
A clear and concise description of what you want to happen.
|
|
22
|
+
|
|
23
|
+
**Describe alternatives you've considered**
|
|
24
|
+
A clear and concise description of any alternative solutions or features you've considered.
|
|
25
|
+
|
|
26
|
+
**Additional context**
|
|
27
|
+
Add any other context or screenshots about the feature request here.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: Question
|
|
3
|
+
about: Ask a question about the project
|
|
4
|
+
title: ''
|
|
5
|
+
labels: ''
|
|
6
|
+
assignees:
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
Please provide the following information and someone from @imgix/imgix-sdk-team will respond to your issue shortly.
|
|
11
|
+
|
|
12
|
+
**Before you submit:**
|
|
13
|
+
|
|
14
|
+
- [ ] Please search through the [existing issues](https://github.com/imgix/imgix-rb/issues?utf8=%E2%9C%93&q=is%3Aissue) to see if your question has already been discussed.
|
|
15
|
+
|
|
16
|
+
**Question**
|
|
17
|
+
A clear and concise description of your question.
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
Hello, and thanks for contributing to imgix-rb! 🎉🙌
|
|
3
|
+
Please take a second to fill out PRs with the following template!
|
|
4
|
+
-->
|
|
5
|
+
|
|
6
|
+
# Description
|
|
7
|
+
|
|
8
|
+
<!-- What is accomplished by this PR? If there is something potentially controversial in your PR, please take a moment to tell us about your choices. -->
|
|
9
|
+
|
|
10
|
+
<!--
|
|
11
|
+
Please use the checklist that is most closely related to your PR, and delete the other checklists. -->
|
|
12
|
+
|
|
13
|
+
## Checklist: Fixing typos/Doc change
|
|
14
|
+
|
|
15
|
+
- [ ] Each commit follows the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) format: e.g. `chore(readme): fixed typo`. See the end of this file for more information.
|
|
16
|
+
|
|
17
|
+
## Checklist: Bug Fix
|
|
18
|
+
|
|
19
|
+
- [ ] Each commit follows the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) format: e.g. `chore(readme): fixed typo`. See the end of this file for more information.
|
|
20
|
+
- [ ] All existing unit tests are still passing (if applicable)
|
|
21
|
+
- [ ] Add new passing unit tests to cover the code introduced by your PR
|
|
22
|
+
- [ ] Update the readme
|
|
23
|
+
- [ ] Update or add any necessary API documentation
|
|
24
|
+
- [ ] Add some [steps](#steps-to-test) so we can test your bug fix
|
|
25
|
+
|
|
26
|
+
## Checklist: New Feature
|
|
27
|
+
|
|
28
|
+
- [ ] Each commit follows the [Conventional Commit](https://www.conventionalcommits.org/en/v1.0.0/#summary) format: e.g. `chore(readme): fixed typo`. See the end of this file for more information.
|
|
29
|
+
- [ ] Any breaking changes are specified on the commit on which they are introduced with `BREAKING CHANGE` in the body of the commit.
|
|
30
|
+
- [ ] If this is a big feature with breaking changes, consider [opening an issue][issues] to discuss first. This is completely up to you, but please keep in mind that your PR might not be accepted.
|
|
31
|
+
- [ ] Run unit tests to ensure all existing tests are still passing
|
|
32
|
+
- [ ] Add new passing unit tests to cover the code introduced by your PR
|
|
33
|
+
- [ ] Update the readme
|
|
34
|
+
- [ ] Add some [steps](#steps-to-test) so we can test your cool new feature!
|
|
35
|
+
|
|
36
|
+
## Steps to Test
|
|
37
|
+
|
|
38
|
+
<!-- Delete this selction if you are just submitting a doc change/small fix -->
|
|
39
|
+
|
|
40
|
+
<!-- A code example or a set of steps is preferred -->
|
|
41
|
+
|
|
42
|
+
Related issue: [e.g. #42]
|
|
43
|
+
|
|
44
|
+
Code:
|
|
45
|
+
|
|
46
|
+
```rb
|
|
47
|
+
// A standalone Ruby example of what the PR solves
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
<!-- A link to a codepen/codesandbox is also an option. -->
|
|
51
|
+
|
|
52
|
+
<!--
|
|
53
|
+
|
|
54
|
+
## Conventional Commit Spec
|
|
55
|
+
|
|
56
|
+
PR titles should be in the format `<type>(<scope>): <description>`. For example: `chore(readme): fix typo`
|
|
57
|
+
|
|
58
|
+
`type` can be any of the follow:
|
|
59
|
+
- `feat`: a feature, or breaking change
|
|
60
|
+
- `fix`: a bug-fix
|
|
61
|
+
- `test`: Adding missing tests or correcting existing tests
|
|
62
|
+
- `docs`: documentation only changes (readme, changelog, contributing guide)
|
|
63
|
+
- `refactor`: a code change that neither fixes a bug nor adds a feature
|
|
64
|
+
- `chore`: reoccurring tasks for project maintainability (example scopes: release, deps)
|
|
65
|
+
- `config`: changes to tooling configurations used in the project
|
|
66
|
+
- `build`: changes that affect the build system or external dependencies (example scopes: npm, bundler, gradle)
|
|
67
|
+
- `ci`: changes to CI configuration files and scripts (example scopes: travis)
|
|
68
|
+
- `perf`: a code change that improves performance
|
|
69
|
+
- `style`: changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
|
|
70
|
+
|
|
71
|
+
`scope` is optional, and can be anything.
|
|
72
|
+
`description` should be a short description of the change, written in the imperative-mood.
|
|
73
|
+
-->
|
data/.travis.yml
CHANGED
|
@@ -1,19 +1,21 @@
|
|
|
1
|
+
dist: trusty
|
|
1
2
|
language: ruby
|
|
2
3
|
bundler_args: --without development
|
|
3
|
-
before_install:
|
|
4
|
-
# Extracts the ruby version number
|
|
5
|
-
- RUBY_VERS="$(bc -l<<<$(ruby -v | cut -d' ' -f 2 | cut -d'.' -f 1,2))"
|
|
6
|
-
# Bundler 2.0 requires at least ruby vers 2.3.0
|
|
7
|
-
- LATEST_VERS=2.3
|
|
8
|
-
# Based on a given job's ruby version, install either
|
|
9
|
-
# Bundler 2.x or 1.17
|
|
10
|
-
- if (( $(echo "$RUBY_VERS >= $LATEST_VERS" | bc -l) ));
|
|
11
|
-
then echo $(gem install bundler);
|
|
12
|
-
else echo $(gem install bundler -v '< 2');
|
|
13
|
-
fi
|
|
14
4
|
rvm:
|
|
15
5
|
- 2.3.0
|
|
16
6
|
- 2.2.4
|
|
17
7
|
- 2.1.8
|
|
18
|
-
- jruby-9.
|
|
19
|
-
|
|
8
|
+
- jruby-9.2.11.0
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
# Use `fast_finish`, don't wait for any allowed failures.
|
|
12
|
+
fast_finish: true
|
|
13
|
+
|
|
14
|
+
include:
|
|
15
|
+
- name: Rubinius
|
|
16
|
+
rvm: rbx-3.107
|
|
17
|
+
dist: trusty
|
|
18
|
+
|
|
19
|
+
allow_failures:
|
|
20
|
+
- name: Rubinius
|
|
21
|
+
|
data/CHANGELOG.md
CHANGED
|
@@ -3,7 +3,38 @@
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
This project adheres to [Semantic Versioning](http://semver.org/).
|
|
5
5
|
|
|
6
|
-
## [3.1
|
|
6
|
+
## [3.3.1](https://github.com/imgix/imgix-rb/compare/3.3.0...3.3.1) - July 27, 2020
|
|
7
|
+
|
|
8
|
+
* fix: ensure host is initialized ([#82](https://github.com/imgix/imgix-rb/pull/82))
|
|
9
|
+
|
|
10
|
+
## [3.3.0](https://github.com/imgix/imgix-rb/compare/3.2.1...3.3.0) - July 21, 2020
|
|
11
|
+
|
|
12
|
+
* fix: warn prefix-with-args is deprecated ([#78](https://github.com/imgix/imgix-rb/pull/78))
|
|
13
|
+
* fix: warn host has been deprecated in favor of domain ([#76](https://github.com/imgix/imgix-rb/pull/76))
|
|
14
|
+
* fix: deprecate ALIASES and corresponding define_method(s) ([#75](https://github.com/imgix/imgix-rb/pull/75))
|
|
15
|
+
* fix: deprecate ParamHelpers.rect ([#74](https://github.com/imgix/imgix-rb/pull/74))
|
|
16
|
+
* fix: allow rbx-3.107 to fail (travis-config) ([#70](https://github.com/imgix/imgix-rb/pull/70))
|
|
17
|
+
* fix: remove ensure even requirement ([#69](https://github.com/imgix/imgix-rb/pull/69))
|
|
18
|
+
|
|
19
|
+
## [3.2.1](https://github.com/imgix/imgix-rb/compare/3.2.0...3.2.1) - November 15, 2019
|
|
20
|
+
|
|
21
|
+
* fix: duplicate entries when using `min_width` or `max_width` ([#59](https://github.com/imgix/imgix-rb/pull/59))
|
|
22
|
+
|
|
23
|
+
## [3.2.0](https://github.com/imgix/imgix-rb/compare/3.1.1...3.2.0) - November 15, 2019
|
|
24
|
+
|
|
25
|
+
* feat: append variable qualities to dpr srcsets ([#58](https://github.com/imgix/imgix-rb/pull/58))
|
|
26
|
+
* refactor: pass srcset modifiers through the `options` parameter ([#57](https://github.com/imgix/imgix-rb/pull/57))
|
|
27
|
+
* feat: support defining a min and max width range ([#56](https://github.com/imgix/imgix-rb/pull/56))
|
|
28
|
+
* feat: add ability to pass in custom widths ([#55](https://github.com/imgix/imgix-rb/pull/55))
|
|
29
|
+
* feat: add ability to configure the srcset width tolerance ([#54](https://github.com/imgix/imgix-rb/pull/54))
|
|
30
|
+
* style: drop redundant explicit return statements ([#52](https://github.com/imgix/imgix-rb/pull/52))
|
|
31
|
+
|
|
32
|
+
## [3.1.1](https://github.com/imgix/imgix-rb/compare/3.1.0...3.1.1) - July 28, 2019
|
|
33
|
+
|
|
34
|
+
* fix: include dpr parameter when generating a DPR srcset ([#48](https://github.com/imgix/imgix-rb/pull/48))
|
|
35
|
+
* ci(travis): change build dist to trusty and remove bundler script ([#49](https://github.com/imgix/imgix-rb/pull/49))
|
|
36
|
+
|
|
37
|
+
## [3.1.0](https://github.com/imgix/imgix-rb/compare/3.0.0...3.1.0) - July 28, 2019
|
|
7
38
|
|
|
8
39
|
* feat: add srcset generation ([#47](https://github.com/imgix/imgix-rb/pull/47))
|
|
9
40
|
|
data/README.md
CHANGED
|
@@ -1,8 +1,29 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
<!-- ix-docs-ignore -->
|
|
2
|
+
|
|
3
|
+
|
|
4
|
+
`imgix-rb` is a client library for generating image URLs with [imgix](https://www.imgix.com/). It is tested under Ruby versions `2.3.0`, `2.2.4`, `2.1.8`, `jruby-9.2.11.0`, and `rbx-3.107`.
|
|
5
|
+
|
|
6
|
+
[](https://rubygems.org/gems/imgix)
|
|
7
|
+
[](https://travis-ci.org/imgix/imgix-rb)
|
|
8
|
+
|
|
9
|
+
[](https://github.com/imgix/imgix-rb/blob/main/LICENSE)
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
<!-- /ix-docs-ignore -->
|
|
13
|
+
|
|
14
|
+
- [Installation](#installation)
|
|
15
|
+
- [Usage](#usage)
|
|
16
|
+
- [Srcset Generation](#srcset-generation)
|
|
17
|
+
- [Fixed image rendering](#fixed-image-rendering)
|
|
18
|
+
- [Custom Widths](#custom-widths)
|
|
19
|
+
- [Width Tolerance](#width-tolerance)
|
|
20
|
+
- [Minimum and Maximum Width Ranges](#minimum-and-maximum-width-ranges)
|
|
21
|
+
- [Variable Qualities](#variable-qualities)
|
|
22
|
+
- [Multiple Parameters](#multiple-parameters)
|
|
23
|
+
- [Purge Cache](#purge-cache)
|
|
24
|
+
- [URL encoding and signed imgix URLs](#url-encoding-and-signed-imgix-urls)
|
|
25
|
+
- [What is the `ixlib` param on every request?](#what-is-the-ixlib-param-on-every-request)
|
|
26
|
+
- [Contributing](#contributing)
|
|
6
27
|
|
|
7
28
|
## Installation
|
|
8
29
|
|
|
@@ -23,12 +44,12 @@ Or install it yourself as:
|
|
|
23
44
|
|
|
24
45
|
## Usage
|
|
25
46
|
|
|
26
|
-
|
|
47
|
+
Initialize a client with a `:domain` and your `:secure_url_token`. By default, HTTPS URLs are generated, but you can toggle that by passing `use_https: false`.
|
|
27
48
|
|
|
28
49
|
Call `Imgix::Client#path` with the resource path to get an `Imgix::Path` object back. You can then manipulate the path parameters, and call `Imgix#Path#to_url` when you're done.
|
|
29
50
|
|
|
30
51
|
``` ruby
|
|
31
|
-
client = Imgix::Client.new(
|
|
52
|
+
client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token')
|
|
32
53
|
|
|
33
54
|
client.path('/images/demo.png').to_url(w: 200)
|
|
34
55
|
#=> https://your-subdomain.imgix.net/images/demo.png?w=200&s=2eadddacaa9bba4b88900d245f03f51e
|
|
@@ -46,12 +67,23 @@ path.defaults.width(300).to_url # Resets parameters
|
|
|
46
67
|
path.rect(x: 0, y: 50, width: 200, height: 300).to_url # Rect helper
|
|
47
68
|
```
|
|
48
69
|
|
|
70
|
+
**Deprecation Notice:** Usage of `:host` has been deprecated and will become invalid in the next major release.
|
|
71
|
+
|
|
72
|
+
In the previous version, `:host` can be used to specify a domain for an `Imgix::Client` like so:
|
|
73
|
+
|
|
74
|
+
```ruby
|
|
75
|
+
Imgix::Client.new(host: 'demo.imgix.net', secure_url_token: 'token')
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Code using `:host` like the above will continue to work until the next major release. While using `:host` will remain valid until the next major release, its usage will result in a deprecation warning. In order to resolve these deprecation warnings before upgrading to the new release, use `:domain` instead of `:host`.
|
|
79
|
+
|
|
80
|
+
|
|
49
81
|
## Srcset Generation
|
|
50
82
|
|
|
51
83
|
The imgix gem allows for generation of custom `srcset` attributes, which can be invoked through `Imgix::Path#to_srcset`. By default, the `srcset` generated will allow for responsive size switching by building a list of image-width mappings.
|
|
52
84
|
|
|
53
85
|
```rb
|
|
54
|
-
client = Imgix::Client.new(
|
|
86
|
+
client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token', include_library_param: false)
|
|
55
87
|
path = client.path('/images/demo.png')
|
|
56
88
|
|
|
57
89
|
srcset = path.to_srcset
|
|
@@ -68,27 +100,124 @@ https://your-subdomain.imgix.net/images/demo.png?w=7400&s=a5dd7dda1dbac613f0475f
|
|
|
68
100
|
https://your-subdomain.imgix.net/images/demo.png?w=8192&s=9fbd257c53e770e345ce3412b64a3452 8192w
|
|
69
101
|
```
|
|
70
102
|
|
|
71
|
-
|
|
103
|
+
### Fixed image rendering
|
|
104
|
+
|
|
105
|
+
In cases where enough information is provided about an image's dimensions, `to_srcset` 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 `to_srcset` 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.
|
|
72
106
|
|
|
73
107
|
```rb
|
|
74
|
-
client = Imgix::Client.new(
|
|
108
|
+
client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', secure_url_token: 'your-token', include_library_param: false)
|
|
75
109
|
path = client.path('/images/demo.png')
|
|
76
110
|
|
|
77
|
-
srcset = path.to_srcset(h:800, ar:'3:2')
|
|
111
|
+
srcset = path.to_srcset(h:800, ar:'3:2', fit:'crop')
|
|
78
112
|
```
|
|
79
113
|
|
|
80
114
|
Will produce the following attribute value:
|
|
81
115
|
|
|
82
116
|
```html
|
|
83
|
-
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=
|
|
84
|
-
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=
|
|
85
|
-
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=
|
|
86
|
-
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=
|
|
87
|
-
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=
|
|
117
|
+
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&fit=crop&dpr=1&s=f97f2dccf85beac33a3824b57ef4ddc6 1x,
|
|
118
|
+
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&fit=crop&dpr=2&s=e1727167fef53cdb0a89dd66b8672410 2x,
|
|
119
|
+
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&fit=crop&dpr=3&s=7718db8457345419c30214f1d1a3a5d3 3x,
|
|
120
|
+
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&fit=crop&dpr=4&s=000c50a7f97ccdbb9bb2f00bc5241ed4 4x,
|
|
121
|
+
https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&fit=crop&dpr=5&s=970b6fc12a410f3dd2959674dd1f4120 5x
|
|
88
122
|
```
|
|
89
123
|
|
|
90
124
|
For more information to better understand `srcset`, we highly recommend [Eric Portis' "Srcset and sizes" article](https://ericportis.com/posts/2014/srcset-sizes/) which goes into depth about the subject.
|
|
91
125
|
|
|
126
|
+
### Custom Widths
|
|
127
|
+
|
|
128
|
+
In situations where specific widths are desired when generating `srcset` pairs, a user can specify them by passing an array of integers via `widths` to the `options` keyword argument.
|
|
129
|
+
|
|
130
|
+
```rb
|
|
131
|
+
@client ||= Imgix::Client.new(domain: 'testing.imgix.net', include_library_param: false)
|
|
132
|
+
.path('image.jpg')
|
|
133
|
+
.to_srcset(options: { widths: [100, 500, 1000, 1800] })
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Will generate the following `srcset` of width pairs:
|
|
137
|
+
|
|
138
|
+
```html
|
|
139
|
+
https://testing.imgix.net/image.jpg?w=100 100w,
|
|
140
|
+
https://testing.imgix.net/image.jpg?w=500 500w,
|
|
141
|
+
https://testing.imgix.net/image.jpg?w=1000 1000w,
|
|
142
|
+
https://testing.imgix.net/image.jpg?w=1800 1800w
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Please note that in situations where a `srcset` is being rendered as a [fixed image](#fixed-image-rendering), any custom `widths` passed in will be ignored. Additionally, if both `widths` and a `width_tolerance` are passed to the `options` parameter in the `to_srcset` method, the custom widths list will take precedence.
|
|
146
|
+
|
|
147
|
+
### Width Tolerance
|
|
148
|
+
|
|
149
|
+
The `srcset` width tolerance dictates the maximum tolerated size difference between an image's downloaded size and its rendered size. For example: setting this value to 0.1 means that an image will not render more than 10% larger or smaller than its native size. In practice, the image URLs generated for a width-based srcset attribute will grow by twice this rate. A lower tolerance means images will render closer to their native size (thereby reducing rendering artifacts), but a large srcset list will be generated and consequently users may experience lower rates of cache-hit for pre-rendered images on your site.
|
|
150
|
+
|
|
151
|
+
By default this rate is set to 8 percent, which we consider to be the ideal rate for maximizing cache hits without sacrificing visual quality. Users can specify their own width tolerance by passing a positive numeric value to `width_tolerance` within the `options` keyword argument:
|
|
152
|
+
|
|
153
|
+
```rb
|
|
154
|
+
client = Imgix::Client.new(domain: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false)
|
|
155
|
+
client.path('image.jpg').to_srcset(options: { width_tolerance: 0.20 })
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
In this case, the `width_tolerance` is set to 20 percent, which will be reflected in the difference between subsequent widths in a srcset pair:
|
|
159
|
+
|
|
160
|
+
```
|
|
161
|
+
https://testing.imgix.net/image.jpg?w=100 100w,
|
|
162
|
+
https://testing.imgix.net/image.jpg?w=140 140w,
|
|
163
|
+
https://testing.imgix.net/image.jpg?w=196 196w,
|
|
164
|
+
...
|
|
165
|
+
https://testing.imgix.net/image.jpg?w=8192 8192w
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
### Minimum and Maximum Width Ranges
|
|
169
|
+
|
|
170
|
+
If the exact number of minimum/maximum physical pixels that an image will need to be rendered at is known, a user can specify them by passing an integer via `min_srcset` and/or `max_srcset` to the `options` keyword parameters:
|
|
171
|
+
|
|
172
|
+
```rb
|
|
173
|
+
client = Imgix::Client.new(domain: 'testing.imgix.net', include_library_param: false)
|
|
174
|
+
client.path('image.jpg').to_srcset(options: { min_srcset: 500, max_srcset: 2000 })
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Will result in a smaller, more tailored srcset.
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
https://testing.imgix.net/image.jpg?w=500 500w,
|
|
181
|
+
https://testing.imgix.net/image.jpg?w=580 580w,
|
|
182
|
+
https://testing.imgix.net/image.jpg?w=672 672w,
|
|
183
|
+
https://testing.imgix.net/image.jpg?w=780 780w,
|
|
184
|
+
https://testing.imgix.net/image.jpg?w=906 906w,
|
|
185
|
+
https://testing.imgix.net/image.jpg?w=1050 1050w,
|
|
186
|
+
https://testing.imgix.net/image.jpg?w=1218 1218w,
|
|
187
|
+
https://testing.imgix.net/image.jpg?w=1414 1414w,
|
|
188
|
+
https://testing.imgix.net/image.jpg?w=1640 1640w,
|
|
189
|
+
https://testing.imgix.net/image.jpg?w=1902 1902w,
|
|
190
|
+
https://testing.imgix.net/image.jpg?w=2000 2000w
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Remember that browsers will apply a device pixel ratio as a multiplier when selecting which image to download from a `srcset`. For example, even if you know your image will render no larger than 1000px, specifying `options: { max_srcset: 1000 }` will give your users with DPR higher than 1 no choice but to download and render a low-resolution version of the image. Therefore, it is vital to factor in any potential differences when choosing a minimum or maximum range.
|
|
194
|
+
|
|
195
|
+
Also please note that according to the [imgix API](https://docs.imgix.com/apis/url/size/w), the maximum renderable image width is 8192 pixels.
|
|
196
|
+
|
|
197
|
+
### Variable Qualities
|
|
198
|
+
|
|
199
|
+
This gem will automatically append a variable `q` parameter mapped to each `dpr` parameter when generating a [fixed-image](https://github.com/imgix/imgix-rb#fixed-image-rendering) 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).
|
|
200
|
+
|
|
201
|
+
This behavior will respect any overriding `q` value passed in as a parameter. Additionally, it can be disabled altogether by passing `options: { disable_variable_quality: true }` to `Imgix:Path#to_srcset`.
|
|
202
|
+
|
|
203
|
+
This behavior specifically occurs when a [fixed-size image](https://github.com/imgix/imgix-rb#fixed-image-rendering) is rendered, for example:
|
|
204
|
+
|
|
205
|
+
```rb
|
|
206
|
+
srcset = Imgix::Client.new(domain: 'testing.imgix.net', include_library_param: false)
|
|
207
|
+
.path('image.jpg')
|
|
208
|
+
.to_srcset(w:100)
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
will generate a srcset with the following `q` to `dpr` mapping:
|
|
212
|
+
|
|
213
|
+
```html
|
|
214
|
+
https://testing.imgix.net/image.jpg?w=100&dpr=1&q=75 1x,
|
|
215
|
+
https://testing.imgix.net/image.jpg?w=100&dpr=2&q=50 2x,
|
|
216
|
+
https://testing.imgix.net/image.jpg?w=100&dpr=3&q=35 3x,
|
|
217
|
+
https://testing.imgix.net/image.jpg?w=100&dpr=4&q=23 4x,
|
|
218
|
+
https://testing.imgix.net/image.jpg?w=100&dpr=5&q=20 5x
|
|
219
|
+
```
|
|
220
|
+
|
|
92
221
|
## Multiple Parameters
|
|
93
222
|
|
|
94
223
|
When the imgix api requires multiple parameters you have to use the method rather than an accessor.
|
|
@@ -99,21 +228,20 @@ For example to use the noise reduction:
|
|
|
99
228
|
path.noise_reduction(50,50)
|
|
100
229
|
```
|
|
101
230
|
|
|
102
|
-
|
|
103
231
|
## Purge Cache
|
|
104
232
|
|
|
105
233
|
If you need to remove or update an image on imgix, you can purge it from our cache by initializing a client with your api_key, then calling Imgix::Client#purge with the resource path.
|
|
106
234
|
|
|
107
235
|
```ruby
|
|
108
|
-
client = Imgix::Client.new(
|
|
236
|
+
client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', api_key: 'your-key')
|
|
109
237
|
client.purge('/images/demo.png')
|
|
110
238
|
```
|
|
111
239
|
|
|
112
240
|
To learn more about purging assets with imgix, [see our docs](https://docs.imgix.com/setup/purging-images).
|
|
113
241
|
|
|
114
|
-
## URL encoding and signed
|
|
242
|
+
## URL encoding and signed imgix URLs
|
|
115
243
|
|
|
116
|
-
Some important third parties (like Facebook) apply URL escaping to query string components, which can cause correctly signed
|
|
244
|
+
Some important third parties (like Facebook) apply URL escaping to query string components, which can cause correctly signed imgix URLs to to be transformed into incorrectly signed ones. We URL encode the query part of the URL before signing, so you don't have to worry about this.
|
|
117
245
|
|
|
118
246
|
## What is the `ixlib` param on every request?
|
|
119
247
|
|
|
@@ -122,7 +250,7 @@ For security and diagnostic purposes, we sign all requests with the language and
|
|
|
122
250
|
This can be disabled by including `include_library_param: false` in the instantiation Hash parameter for `Imgix::Client`:
|
|
123
251
|
|
|
124
252
|
```ruby
|
|
125
|
-
client = Imgix::Client.new(
|
|
253
|
+
client = Imgix::Client.new(domain: 'your-subdomain.imgix.net', include_library_param: false )
|
|
126
254
|
```
|
|
127
255
|
|
|
128
256
|
## Contributing
|