imgix-rails 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 123b72f2be8e8d5a3d5a8170b386e1623d763010
-  data.tar.gz: fdda3f207a947cd64dbef1d1a20f4558b0155deb
+  metadata.gz: 62c3df395875ff9ec0422abe8b6b5ab60ddc8a0c
+  data.tar.gz: 285cbe4283c1caad13a3266dfe150e1726a6977f
 SHA512:
-  metadata.gz: 056412199a9166b00ece1946bb78d8399ba8e59bc3079bbe41598cf9774ec0b04d6657e1d0aba4ddd39ca179a70bf229a4f47d03d876d4411e66f69296936644
-  data.tar.gz: 402a42b8784e40243dcee65aaca5a64b531caf629a15efaf78b305cbfb9e3a0f22dd8f40a970eb8fbc436cb29a0c1a9ce56a9a67c936a9e44b4c71fc3097361c
+  metadata.gz: c3ecb91c1f1452f5a026bf77590d56987ab2946d7875276a95784ab9dec52c89d245ae3b73a002199513addca758848ac4fcb588570440106b076519a32154da
+  data.tar.gz: 26927455ee9b481d06a6427176876d2f2ee5c45c28c5f96af2cada5c35eeae582de03da29ecb8649787785a855db001b7bf6387132d06c7ba65afaddb9759674

data/README.md

@@ -12,12 +12,11 @@ We recommend using something like [Paperclip](https://github.com/thoughtbot/pape
 * [Usage](#usage)
   * [Configuration](#configuration)
   * [ix_image_tag](#ix_image_tag)
-  * [ix_responsive_image_tag](#ix_responsive_image_tag)
   * [ix_picture_tag](#ix_picture_tag)
   * [ix_image_url](#ix_image_url)
   * [Hostname Removal](#hostname-removal)
 * [Using With Image Uploading Libraries](#using-with-image-uploading-libraries)
-  * [Paperclip](#paperclip)
+  * [Paperclip and CarrierWave](#paperclip-and-carrierwave)
   * [Refile](#refile)
 * [Development](#development)
 * [Contributing](#contributing)
@@ -65,16 +64,28 @@ The following configuration flags will be respected:
 <a name="ix_image_tag"></a>
 ### ix_image_tag
 
-The simplest way of working with imgix-rails is to use the `ix_image_tag`, this allows you to pass parameters to imgix to handle things like resizing, cropping, etc.
+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.”](http://blog.imgix.com/post/127012184664/responsive-images-with-srcset-imgix).
+
+`ix_image_tag` generates `<img>` tags with a filled-out `srcset` attribute that leans on imgix to do the hard work. 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`.
 
 ```erb
-<%= ix_image_tag('/path/to/image.jpg', { w: 400, h: 300 }) %>
+<%= ix_image_tag('/unsplash/hotairballoon.jpg', { w: 300, h: 500, fit: 'crop', crop: 'right', alt: 'A hot air balloon on a sunny day' }) %>
 ```
 
 Will render out HTML like the following:
 
 ```html
-<img src="https://assets.imgix.net/path/to/image?w=400&h=300" />
+<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"
+>
 ```
 
 We recommend leveraging this to generate powerful helpers within your application like the following:
@@ -91,51 +102,46 @@ Then rendering the portrait in your application is very easy:
 <%= profile_image_tag(@user) %>
 ```
 
-<a name="ix_responsive_image_tag"></a>
-### ix_responsive_image_tag
-
-The `ix_responsive_image_tag` helper method makes it easy to bring responsive imagery to your Rails app. We talk a bit about using the `srcset` attribute in an application in the following blog post: [“Responsive Images with `srcset` and imgix.”](http://blog.imgix.com/post/127012184664/responsive-images-with-srcset-imgix)
-
-The `ix_responsive_image_tag` will generate an `<img>` element with a filled-out `srcset` attribute that leans on imgix to do the hard work.
-
-It will use the configured device-pixel-ratios in the `config.imgix[:responsive_resolutions]` value. It will default to `[1, 2]`.
-
-```erb
-<%= ix_responsive_image_tag('/users/1/avatar.png', { w: 400, h: 300 }) %>
-```
-
-This will generate the following HTML:
-
-```html
-<img
-  srcset="https://assets.imgix.net/users/1/avatar.png?w=400&h=300 1x,
-          https://assets.imgix.net/users/1/avatar.png?w=400&h=300&dpr=2 2x"
-  src="https://assets.imgix.net/users/1/avatar.png?w=400&h=300"
-/>
-```
 
 <a name="ix_picture_tag"></a>
 ### ix_picture_tag
 
-The `ix_picture_tag` helper method makes it easy to generate `<picture>` elements in your Rails app.
+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.
 
-The `ix_picture_tag` method will generate a `<picture>` element with a single `<source>` element and a fallback `<img>` element. We are open for new directions to take this in.
+`ix_picture_tag` takes four arguments:
 
-It will use the configured device-pixel-ratios in the `config.imgix[:responsive_resolutions]` value. It will default to `[1, 2]`.
+* `source`: The path or URL of the image to display.
+* `picture_tag_options`: Any options to apply to the parent `picture` element. This is useful for adding class names, etc.
+* `imgix_default_options`: 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 param overrides for that media query. A `source` element will be generated for each breakpoint specified.
 
 ```erb
-<%= ix_picture_tag('/users/1/avatar.png', { w: 400, h: 300 }) %>
+<%= ix_picture_tag('bertandernie.jpg',
+  picture_tag_options: {
+    class: 'a-picture-tag'
+  },
+  imgix_default_options: {
+    w: 300,
+    h: 300,
+    fit: 'crop',
+  },
+  breakpoints: {
+    '(max-width: 640px)' => {
+      h: 100,
+      sizes: 'calc(100vw - 20px)'
+    },
+    '(max-width: 880px)' => {
+      crop: 'right',
+      sizes: 'calc(100vw - 20px - 50%)'
+    },
+    '(min-width: 881px)' => {
+      crop: 'left',
+      sizes: '430px'
+    }
+  }
+) %>
 ```
 
-Will generate the following HTML:
-
-```html
-<picture>
-  <source srcset="https://assets.imgix.net/users/1/avatar.png?w=400&h=300 1x,
-                  https://assets.imgix.net/users/1/avatar.png?w=400&h=300&dpr=2 2x" />
-  <img src="https://assets.imgix.net/users/1/avatar.png?w=400&h=300" />
-</picture>
-```
 
 <a name="ix_image_url"></a>
 ### ix_image_url
@@ -201,10 +207,10 @@ Renders:
 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!
 
 
-<a name="paperclip"></a>
-### Paperclip
+<a name="paperclip-and-carrierwave"></a>
+### Paperclip and CarrierWave
 
-Paperclip can directly provide paths to uploaded images, so we can use it with imgix-rails without a bridge.
+Paperclip and CarrierWave can directly provide paths to uploaded images, so we can use them with imgix-rails without a bridge.
 
 ``` html
 <%= ix_image_tag(@user.avatar.path, { auto: 'format', fit: 'crop', w: 500}) %>

data/lib/imgix/rails/image_tag.rb

@@ -0,0 +1,13 @@
+require "imgix/rails/tag"
+
+class Imgix::Rails::ImageTag < Imgix::Rails::Tag
+  def render
+    @options[:srcset] = srcset
+    @options[:sizes] ||= '100vw'
+
+    @source = replace_hostname(@source)
+    normal_opts = @options.slice!(*self.class.available_parameters)
+
+    image_tag(ix_image_url(@source, @options), normal_opts)
+  end
+end

data/lib/imgix/rails/picture_tag.rb

@@ -0,0 +1,28 @@
+require "imgix/rails/tag"
+require "imgix/rails/image_tag"
+
+class Imgix::Rails::PictureTag < Imgix::Rails::Tag
+  include ActionView::Context
+
+  def initialize(source, options, default_options, breakpoints)
+    @source = source
+    @options = options
+    @default_options = default_options
+    @breakpoints = breakpoints
+  end
+
+  def render
+    content_tag(:picture, @options) do
+      @breakpoints.each do |media, opts|
+        html_opts = opts.except(*self.class.available_parameters)
+        html_opts[:media] ||= media
+        html_opts[:srcset] ||= srcset(@default_options.clone.merge(opts))
+
+
+        concat(content_tag(:source, nil, html_opts))
+      end
+
+      concat Imgix::Rails::ImageTag.new(@source, @default_options).render
+    end
+  end
+end

data/lib/imgix/rails/tag.rb

@@ -0,0 +1,162 @@
+require "imgix/rails/url_helper"
+
+class Imgix::Rails::Tag
+  include Imgix::Rails::UrlHelper
+  include ActionView::Helpers
+
+  @@parameters = nil
+
+  # Store our parameter information on the class instance so that
+  # each instance of any this class or our subclasses doesn't have to
+  # go back to disk to get this configuration information
+  def self.available_parameters
+    @@available_parameters ||= parameters.keys
+  end
+
+  def self.parameters
+    return @@parameters if @@parameters
+
+    path = File.expand_path("../../../../vendor/parameters.json", __FILE__)
+    @@parameters ||= JSON.parse(File.read(path), symbolize_names: true)[:parameters]
+  end
+
+  def initialize(source, options={})
+    @source = source
+    @options = options
+  end
+
+protected
+
+  def srcset(opts=@options)
+    @source = replace_hostname(@source)
+    target_widths.map do |target_width|
+      srcset_options = opts.slice(*self.class.available_parameters)
+      srcset_options[:w] = target_width
+
+      if opts[:w].present? && opts[:h].present?
+        srcset_options[:h] = (target_width * (opts[:h].to_f / opts[:w])).round
+      end
+
+      "#{ix_image_url(@source, srcset_options)} #{target_width}w"
+    end.join(', ')
+  end
+
+private
+
+  MAXIMUM_SCREEN_WIDTH = 2560 * 2 # Physical resolution of 27" iMac (2016)
+  SCREEN_STEP = 100
+
+  # Taken from http://mydevice.io/devices/
+
+  # Phones
+  IPHONE = { css_width: 320, dpr: 1 }
+  IPHONE_4 = { css_width: 320, dpr: 2 }
+  IPHONE_6 = { css_width: 375, dpr: 2 }
+  LG_G3 = { css_width: 360, dpr: 4 }
+
+  # Phablets
+  IPHONE_6_PLUS = { css_width: 414, dpr: 3 }
+  IPHONE_6_PLUS_LANDSCAPE = { css_width: 736, dpr: 3 }
+  MOTO_NEXUS_6 = { css_width: 412, dpr: 3.5 }
+  MOTO_NEXUS_6_LANDSCAPE = { css_width: 690, dpr: 3.5 }
+  LUMIA_1520 = { css_width: 432, dpr: 2.5 }
+  LUMIA_1520_LANDSCAPE = { css_width: 768, dpr: 2.5 }
+  GALAXY_NOTE_3 = { css_width: 360, dpr: 3 }
+  GALAXY_NOTE_3_LANDSCAPE = { css_width: 640, dpr: 3 }
+  GALAXY_NOTE_4 = { css_width: 360, dpr: 4 }
+  GALAXY_NOTE_4_LANDSCAPE = { css_width: 640, dpr: 4 }
+
+  # Tablets
+  IPAD = { css_width: 768, dpr: 1 };
+  IPAD_LANDSCAPE = { css_width: 1024, dpr: 1 };
+  IPAD_3 = { css_width: 768, dpr: 2 };
+  IPAD_3_LANDSCAPE = { css_width: 1024, dpr: 2 };
+  IPAD_PRO = { css_width: 1024, dpr: 2 };
+  IPAD_PRO_LANDSCAPE = { css_width: 1366, dpr: 2 };
+
+  BOOTSTRAP_SM = { css_width: 576, dpr: 1 }
+  BOOTSTRAP_MD = { css_width: 720, dpr: 1 }
+  BOOTSTRAP_LG = { css_width: 940, dpr: 1 }
+  BOOTSTRAP_XL = { css_width: 1140, dpr: 1 }
+
+  def devices
+    phones + phablets + tablets + bootstrap_breaks
+  end
+
+  def bootstrap_breaks
+    breaks = [
+      BOOTSTRAP_SM,
+      BOOTSTRAP_MD,
+      BOOTSTRAP_LG,
+      BOOTSTRAP_XL
+    ]
+
+    breaks + breaks.map { |b| b[:dpr] = 2; b }
+  end
+
+  def phones
+    [
+      IPHONE,
+      IPHONE_4,
+      IPHONE_6,
+      LG_G3
+    ]
+  end
+
+  def phablets
+    [
+      IPHONE_6_PLUS,
+      IPHONE_6_PLUS_LANDSCAPE,
+      MOTO_NEXUS_6,
+      MOTO_NEXUS_6_LANDSCAPE,
+      LUMIA_1520,
+      LUMIA_1520_LANDSCAPE,
+      GALAXY_NOTE_3,
+      GALAXY_NOTE_3_LANDSCAPE,
+      GALAXY_NOTE_4,
+      GALAXY_NOTE_4_LANDSCAPE
+    ]
+  end
+
+  def tablets
+    [
+      IPAD,
+      IPAD_LANDSCAPE,
+      IPAD_3,
+      IPAD_3_LANDSCAPE,
+      IPAD_PRO,
+      IPAD_PRO_LANDSCAPE
+    ]
+  end
+
+  # Return the widths to generate given the input `sizes`
+  # attribute.
+  #
+  # @return {Array} An array of {Fixnum} instances representing the unique `srcset` URLs to generate.
+  def target_widths
+    min_screen_width_required = @options[:min_width] || SCREEN_STEP
+    max_screen_width_required = @options[:max_width] || MAXIMUM_SCREEN_WIDTH
+
+    (device_widths + screen_widths).select do |w|
+      w <= max_screen_width_required && w >= min_screen_width_required
+    end.compact.uniq.sort
+  end
+
+  def device_widths
+    devices.map do |device|
+      (device[:css_width] * device[:dpr]).round
+    end
+  end
+
+  # Generates an array of physical screen widths to represent
+  # the different potential viewport sizes.
+  #
+  # We step by `SCREEN_STEP` to give some sanity to the amount
+  # of widths we output.
+  #
+  # The upper bound is the widest known screen on the planet.
+  # @return {Array} An array of {Fixnum} instances
+  def screen_widths
+    (0..MAXIMUM_SCREEN_WIDTH).step(SCREEN_STEP).to_a + [MAXIMUM_SCREEN_WIDTH]
+  end
+end

data/lib/imgix/rails/version.rb

@@ -1,5 +1,5 @@
 module Imgix
   module Rails
-    VERSION = "1.1.0"
+    VERSION = '2.0.0'
   end
 end

data/lib/imgix/rails/view_helper.rb

@@ -1,55 +1,18 @@
 require "imgix"
-require "imgix/rails/url_helper"
+require "imgix/rails/image_tag"
+require "imgix/rails/picture_tag"
 
 module Imgix
   module Rails
-   module ViewHelper
+    module ViewHelper
       include UrlHelper
 
       def ix_image_tag(source, options={})
-        source = replace_hostname(source)
-        normal_opts = options.slice!(*available_parameters)
-
-        image_tag(ix_image_url(source, options), normal_opts)
-      end
-
-      def ix_responsive_image_tag(source, options={})
-        options.merge!({
-          srcset: srcset_for(source, options)
-        })
-
-        ix_image_tag(source, options)
-      end
-
-      def ix_picture_tag(source, options={})
-        content_tag(:picture) do
-          concat(tag(:source, srcset: srcset_for(source, options)))
-          concat(ix_image_tag(source, options))
-        end
-      end
-
-    private
-
-      def available_parameters
-        @available_parameters ||= parameters.keys
-      end
-
-      def parameters
-        path = File.expand_path("../../../../vendor/parameters.json", __FILE__)
-        @parameters ||= JSON.parse(File.read(path), symbolize_names: true)[:parameters]
-      end
-
-      def srcset_for(source, options={})
-        source = replace_hostname(source)
-        configured_resolutions.map do |resolution|
-          srcset_options = options.slice(*available_parameters)
-          srcset_options[:dpr] = resolution unless resolution == 1
-          "#{ix_image_url(source, srcset_options)} #{resolution}x"
-        end.join(', ')
+        Imgix::Rails::ImageTag.new(source, options).render
       end
 
-      def configured_resolutions
-        ::Imgix::Rails.config.imgix[:responsive_resolutions] || [1, 2]
+      def ix_picture_tag(source, picture_tag_options:, imgix_default_options:, breakpoints:)
+        Imgix::Rails::PictureTag.new(source, picture_tag_options, imgix_default_options, breakpoints).render
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: imgix-rails
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Kelly Sutton
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-25 00:00:00.000000000 Z
+date: 2016-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: imgix
@@ -107,6 +107,9 @@ files:
 - bin/setup
 - imgix-rails.gemspec
 - lib/imgix/rails.rb
+- lib/imgix/rails/image_tag.rb
+- lib/imgix/rails/picture_tag.rb
+- lib/imgix/rails/tag.rb
 - lib/imgix/rails/url_helper.rb
 - lib/imgix/rails/version.rb
 - lib/imgix/rails/view_helper.rb