imgix 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a7ecfad08f5fb987982e65a9e4c22a7427f08be4
-  data.tar.gz: 23579307f97e575b2f30c065360b1244795e1081
+  metadata.gz: c260521282fd6b24c05cf774caaf4b140fef9b5a
+  data.tar.gz: d7b53e8cce58a50020eeba7d9c4ad6aa556dfbb5
 SHA512:
-  metadata.gz: '098a9a3ace9b4c06d8466ceb3ec4a3dc73ef64ee004d6d9d62082d200a0c19e34ad4b066eb418b36f7731213c30f1b172834e4b7a4deddc3326839ab1f12e1ae'
-  data.tar.gz: e1cd1ae2bb0eaeb1a6ddf330e53fe844d60cbc84133c102ba8f57774e3d6fe823f0eb820426af8adabacaa20b1cb9e1a77fb64cefdeb07c01e35ad649110b088
+  metadata.gz: 33ff8d7ea4e778dcea4ade90283896b034c40b9d6cbd613920ec2712390b925d39041f996b3d44698a76dd279b829ab1d0a55e86e05dd57fbb2a417a03cf3b7b
+  data.tar.gz: 87ab1ed154e7ea3bfa69538a8904d3f8e9145f3cfa9175b3db60dc9855a20ca0f9845663be9a12eadcf340e8bf3cd1e29de630fa6561c092a0e7e9700a493b22

data/CHANGELOG.md

@@ -3,9 +3,13 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.1.0](https://github.com/imgix/imgix-rb/compare/2.1.0...3.1.0) - July 28, 2019
+
+* feat: add srcset generation ([#47](https://github.com/imgix/imgix-rb/pull/47))
+
 ## [3.0.0](https://github.com/imgix/imgix-rb/compare/2.1.0...3.0.0) - June 7, 2019
 
-*  fix: remove deprecated domain sharding functionality ([#46](https://github.com/imgix/imgix-rb/pull/46))
+* fix: remove deprecated domain sharding functionality ([#46](https://github.com/imgix/imgix-rb/pull/46))
 
 ## [2.1.0](https://github.com/imgix/imgix-rb/compare/2.0.0...2.1.0) - May 7, 2019
 

data/README.md

@@ -46,6 +46,48 @@ path.defaults.width(300).to_url # Resets parameters
 path.rect(x: 0, y: 50, width: 200, height: 300).to_url # Rect helper
 ```
 
+## Srcset Generation
+
+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.
+
+```rb
+client = Imgix::Client.new(host: 'your-subdomain.imgix.net', secure_url_token: 'your-token', include_library_param: false)
+path = client.path('/images/demo.png')
+
+srcset = path.to_srcset
+```
+
+Will produce the following attribute value, which can then be served to the client:
+
+```html
+https://your-subdomain.imgix.net/images/demo.png?w=100&s=efb3e4ae8eaa1884357f40510b11787c 100w,
+https://your-subdomain.imgix.net/images/demo.png?w=116&s=1417ebeaaaecff39533408cb44893eda 116w,
+https://your-subdomain.imgix.net/images/demo.png?w=134&s=4e45e67c087df930b9ddc8cf5be869d0 134w,
+                                            ...
+https://your-subdomain.imgix.net/images/demo.png?w=7400&s=a5dd7dda1dbac613f0475f1ffd90ef79 7400w,
+https://your-subdomain.imgix.net/images/demo.png?w=8192&s=9fbd257c53e770e345ce3412b64a3452 8192w
+```
+
+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 provided, a different `srcset` will be generated for a fixed-size image instead.
+
+```rb
+client = Imgix::Client.new(host: 'your-subdomain.imgix.net', secure_url_token: 'your-token')
+path = client.path('/images/demo.png')
+
+srcset = path.to_srcset(h:800, ar:'3:2')
+```
+
+Will produce the following attribute value:
+
+```html
+https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=be8c153bb9ed0dd152e846414a8fdc86 1x,
+https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=be8c153bb9ed0dd152e846414a8fdc86 2x,
+https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=be8c153bb9ed0dd152e846414a8fdc86 3x,
+https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=be8c153bb9ed0dd152e846414a8fdc86 4x,
+https://your-subdomain.imgix.net/images/demo.png?h=800&ar=3%3A2&s=be8c153bb9ed0dd152e846414a8fdc86 5x
+```
+
+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.
 
 ## Multiple Parameters
 

data/lib/imgix.rb

@@ -5,5 +5,23 @@ require 'imgix/client'
 require 'imgix/path'
 
 module Imgix
+  # regex pattern used to determine if a domain is valid
   DOMAIN_REGEX = /^(?:[a-z\d\-_]{1,62}\.){0,125}(?:[a-z\d](?:\-(?=\-*[a-z\d])|[a-z]|\d){0,62}\.)[a-z\d]{1,63}$/i
+
+  # returns an array of width values used during scrset generation
+  TARGET_WIDTHS = lambda {
+    increment_percentage = 8
+    max_size = 8192
+    resolutions = []
+    prev = 100
+
+    while(prev <= max_size)
+      # ensures that each width is even
+      resolutions.push((2 * (prev / 2).round))
+      prev *= 1 + ((increment_percentage.to_f) / 100) * 2
+    end
+
+    resolutions.push(max_size)
+    return resolutions
+  }
 end

data/lib/imgix/path.rb

@@ -39,6 +39,7 @@ module Imgix
 
       @path = CGI.escape(@path) if /^https?/ =~ @path
       @path = "/#{@path}" if @path[0] != '/'
+      @target_widths = TARGET_WIDTHS.call
     end
 
     def to_url(opts = {})
@@ -83,6 +84,19 @@ module Imgix
       end
     end
 
+    def to_srcset(params = {})
+      @options.merge!(params)
+      width = @options['w'.to_sym]
+      height = @options['h'.to_sym]
+      aspect_ratio = @options['ar'.to_sym]
+
+      if ((width) || (height && aspect_ratio))
+        build_dpr_srcset(@options)
+      else
+        build_srcset_pairs(@options)
+      end
+    end
+    
     private
 
     def signature
@@ -108,5 +122,28 @@ module Imgix
     def has_query?
       query.length > 0
     end
+
+    def build_srcset_pairs(params = {})
+      srcset = ''
+      for width in @target_widths do
+        currentParams = params || {}
+        currentParams['w'] = width
+        srcset += "#{to_url(currentParams)} #{width}w,\n"
+      end
+
+      return srcset[0..-3]
+    end
+
+    def build_dpr_srcset(params = {})
+      srcset = ''
+      target_ratios = [1,2,3,4,5]
+      url = to_url(params)
+
+      for ratio in target_ratios do
+        srcset += "#{url} #{ratio}x,\n"
+      end
+
+      return srcset[0..-3]
+    end
   end
 end

data/lib/imgix/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Imgix
-  VERSION = '3.0.0'
+  VERSION = '3.1.0'
 end

data/test/units/srcset_test.rb

@@ -0,0 +1,226 @@
+require 'test_helper'
+
+module SrcsetTest
+
+    class SrcsetDefault < Imgix::Test
+        def test_no_parameters
+            srcset = path.to_srcset()
+            expected_number_of_pairs = 31
+            assert_equal expected_number_of_pairs, srcset.split(',').length
+        end
+        
+        private
+            def path
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg')
+            end
+    end
+
+    class SrcsetGivenWidth < Imgix::Test
+        def test_srcset_in_dpr_form
+            device_pixel_ratio = 1
+
+            srcset.split(',').map { |src|
+                ratio = src.split(' ')[1]
+                assert_equal ("#{device_pixel_ratio}x"), ratio
+                device_pixel_ratio += 1
+            }
+        end
+
+        def test_srcset_signs_urls
+            expected_signature = 'b95cfd915f4a198442bff4ce5befe5b8'
+
+            srcset.split(',').map { |src|
+                url = src.split(' ')[0]
+                assert_includes url, "s="
+
+                generated_signature = url.slice(url.index("s=")+2, url.length)
+                assert_equal expected_signature, generated_signature
+            }
+        end
+    
+        private
+            def srcset
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100)
+            end
+    end
+
+    class SrcsetGivenHeight < Imgix::Test
+        def test_srcset_generates_width_pairs
+            expected_number_of_pairs = 31
+            assert_equal expected_number_of_pairs, srcset.split(',').length
+        end
+
+        def test_srcset_respects_height_parameter
+            srcset.split(',').map { |src|
+                assert_includes src, 'h='
+            }
+        end
+
+        def test_srcset_within_bounds
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length-1].split(' ')[1].to_i
+
+            assert_operator min, :>=, 100
+            assert_operator max, :<=, 8192
+        end
+
+        def test_srcset_iterates_18_percent
+            increment_allowed = 0.18
+
+            # create an array of widths
+            widths = srcset.split(',').map { |src|
+                src.split(' ')[1].to_i
+            }
+
+            prev = widths[0]
+
+            for i in 1..widths.length-1 do
+                element = widths[i]
+                assert_operator (element / prev), :<, (1 + increment_allowed)
+                prev = element
+            end
+        end
+
+        def test_srcset_signs_urls
+            srcset.split(',').map { |srcset_split|
+                src = srcset_split.split(' ')[0]
+                assert_includes src, 's='
+
+                # parses out all parameters except for 's=...'
+                params = src.slice(src.index('?'), src.length)
+                params = params.slice(0, params.index('s=')-1)
+                # parses out the 's=...' parameter
+                generated_signature = src.slice(src.index('s=')+2, src.length)
+
+                signature_base = 'MYT0KEN' + '/image.jpg' + params;
+                expected_signature = Digest::MD5.hexdigest(signature_base)
+                
+                assert_equal expected_signature, generated_signature
+            }
+        end
+
+        private
+            def srcset
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(h:100)
+            end
+    end
+
+    class SrcsetGivenWidthAndHeight < Imgix::Test
+        def test_srcset_in_dpr_form
+            device_pixel_ratio = 1
+
+            srcset.split(',').map { |src|
+                ratio = src.split(' ')[1]
+                assert_equal ("#{device_pixel_ratio}x"), ratio
+                device_pixel_ratio += 1
+            }
+        end
+
+        def test_srcset_signs_urls
+            expected_signature = 'fb081a45c449b28f69e012d474943df3'
+
+            srcset.split(',').map { |src|
+                url = src.split(' ')[0]
+                assert_includes url, "s="
+
+                generated_signature = url.slice(url.index("s=")+2, url.length)
+                assert_equal expected_signature, generated_signature
+            }
+        end
+
+        private
+            def srcset
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(w:100,h:100)
+            end
+    end
+
+    class SrcsetGivenAspectRatio < Imgix::Test
+        def test_srcset_generates_width_pairs
+            expected_number_of_pairs = 31
+            assert_equal expected_number_of_pairs, srcset.split(',').length
+        end
+
+        def test_srcset_within_bounds
+            min, *max = srcset.split(',')
+
+            # parse out the width descriptor as an integer
+            min = min.split(' ')[1].to_i
+            max = max[max.length-1].split(' ')[1].to_i
+
+            assert_operator min, :>=, 100
+            assert_operator max, :<=, 8192
+        end
+
+        def test_srcset_iterates_18_percent
+            increment_allowed = 0.18
+
+            # create an array of widths
+            widths = srcset.split(',').map { |src|
+                src.split(' ')[1].to_i
+            }
+
+            prev = widths[0]
+
+            for i in 1..widths.length-1 do
+                element = widths[i]
+                assert_operator (element / prev), :<, (1 + increment_allowed)
+                prev = element
+            end
+        end
+
+        def test_srcset_signs_urls
+            srcset.split(',').map { |srcset_split|
+                src = srcset_split.split(' ')[0]
+                assert_includes src, 's='
+
+                # parses out all parameters except for 's=...'
+                params = src.slice(src.index('?'), src.length)
+                params = params.slice(0, params.index('s=')-1)
+                # parses out the 's=...' parameter
+                generated_signature = src.slice(src.index('s=')+2, src.length)
+
+                signature_base = 'MYT0KEN' + '/image.jpg' + params;
+                expected_signature = Digest::MD5.hexdigest(signature_base)
+                
+                assert_equal expected_signature, generated_signature
+            }
+        end
+
+        private
+            def srcset
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset(ar:'3:2')
+            end
+    end
+
+    class SrcsetGivenAspectRatioAndHeight < Imgix::Test
+        def test_srcset_in_dpr_form
+            device_pixel_ratio = 1
+
+            srcset.split(',').map { |src|
+                ratio = src.split(' ')[1]
+                assert_equal ("#{device_pixel_ratio}x"), ratio
+                device_pixel_ratio += 1
+            }
+        end
+
+        def test_srcset_signs_urls
+            expected_signature = '84db8cb226483fc0130b4fb58e1e6ff2'
+
+            srcset.split(',').map { |src|
+                url = src.split(' ')[0]
+                assert_includes url, "s="
+
+                generated_signature = url.slice(url.index("s=")+2, url.length)
+                assert_equal expected_signature, generated_signature
+            }
+        end
+
+        private
+            def srcset
+                @client ||= Imgix::Client.new(host: 'testing.imgix.net', secure_url_token: 'MYT0KEN', include_library_param: false).path('image.jpg').to_srcset({h:100,ar:'3:2'})
+            end
+    end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imgix
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Kelly Sutton
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-06-07 00:00:00.000000000 Z
+date: 2019-07-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -73,6 +73,7 @@ files:
 - test/units/domains_test.rb
 - test/units/path_test.rb
 - test/units/purge_test.rb
+- test/units/srcset_test.rb
 - test/units/url_test.rb
 homepage: https://github.com/imgix/imgix-rb
 licenses:
@@ -103,4 +104,5 @@ test_files:
 - test/units/domains_test.rb
 - test/units/path_test.rb
 - test/units/purge_test.rb
+- test/units/srcset_test.rb
 - test/units/url_test.rb