better_image_tag 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7df2e2edc57e025ec836d4c102c617d70dea1c072a76cf7185c188cea873d704
+  data.tar.gz: 2b7680cec05ea1078275f14b1d11483d6717807629a6140605aac48a5bc47eab
+SHA512:
+  metadata.gz: 81e4711d38e429cee31da67d3d933c65ef87af17f128561e863e6827feb9a9ef9359bb27bde6bfd0117279950485359bd66eb2541c15f6fc14220af34711aa90
+  data.tar.gz: 03f67acd1da24a1f55452fc44a2e1b89f64bd73893c2cd45da99d582594d7a388d3b0451fac4ec92771b91f06d7a1822c3fcfda33db7c346975939d29f1aa6ce

data/.gitignore

@@ -0,0 +1,18 @@
+.tool-versions
+/.rspec_status
+/.bundle/
+/.overcommit.yml
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/spec/dummy/log/*
+/spec/dummy/tmp/*
+/tmp/
+/gemfiles/*.lock
+/gemfiles/.bundle
+/spec/dummy/tmp/cache/*
+/spec/dummy/log/*

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at joel.oliveira@gmail.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in better_image_tag.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 ezCater, Inc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

data/README.md

@@ -0,0 +1,311 @@
+# BetterImageTag
+
+`better_image_tag` is a drop-in evolution (mutation?) of Rails' stock
+`image_tag` view helper. "Is that really necessary?", you might say. No, not
+necessarily, but there are opportunities for improvement in the typical web
+app/site work-flow that are addressable via common boilerplate code that
+-- we hope -- is wrapped up nicely into this gem. Namely:
+
+* Using webp or avif versions of an image if the browser supports it.
+* A rake task that will generate webp or avif versions of all jpg's in your app.
+* Ability to inline contents of an image as a base64 encoded string.
+* Inlining SVG's will output the contents of the SVG image instead of using img
+  tag and its base64 encoded data. This also allows for width, height, and
+  class properties to be applied to the root SVG tag.
+* In conjunction with the excellent [lazysizes] JS library, lazy-loading
+  of images.
+* Fetching dimensions of, typically, user-generated image content and
+  applying width and height properties to the image tag
+* An `inlineable` executable is provided for cases where you're not working
+  with Rails and just need a tool to output the base64 data url for images or
+  css.
+
+Everything above is in service of making web pages render faster. If you're
+familiar with [Google's lighthouse page speed tool], or [WebPageTest], then
+you may be familiar with some of the strategies outlined above.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'better_image_tag'
+```
+
+And then execute:
+
+```sh
+$ bundle
+```
+
+To make use of the lazy-loading, install [lazysizes] with your javascript budndler of choice -- webpacker, the asset pipeline, etc.
+
+## Configuration
+
+You may configure `better_image_tag` with an initializer (eg: `config/initializers/better_image_tag.rb`) containing any or all of the following:
+
+```
+# the following are the defaults
+
+BetterImageTag.configure do |config|
+  config.cache_inlining_enabled = false
+  config.cache_sizing_enabled   = false
+  config.images_path            = "#{Rails.root}/app/assets/images"
+  config.inlining_enabled       = true
+  config.sizing_enabled         = true
+  config.require_alt_tags       = false
+end
+```
+
+* `cache_inlining_enabled` uses Rails' cache for the base64 encoded contents of an image path
+* `cache_sizing_enabled` uses Rails' cache for the width and height dimensions of an images path/url.
+* `images_path` points to the base image assets' path in your application.
+* `inlining_enabled` turns the inlining mechanism on or off.
+* `sizing_enabled` turns the image size fetching mechanism on or off.
+* `require_alt_tags`, when set to true, will raise an exception if an image tag does not have an alt attribute set. [Adding alternative text to photos is first and foremost a principle of web accessibility]. This helps enforce usage of alt tags in an effort to increase web accessibility.
+
+[Adding alternative text to photos is first and foremost a principle of web accessibility]: https://moz.com/learn/seo/alt-text
+
+## Usage
+
+Add the controller concern to the controllers where you would like to use
+`better_image_tag`:
+
+```
+class HomepageController < ApplicationController
+  include BetterImageTag::ImageTaggable
+end
+```
+
+Optionally, you can further constrain usage with a `better_image_tag` class
+method. This is useful for scenarios where you want to use the features for
+one action only:
+
+```
+class HomepageController < ApplicationController
+  include BetterImageTag::ImageTaggable
+
+  better_image_tag if: :needs_better_image_tags?
+  better_image_tag unless: :we_dont?
+end
+```
+
+Furthermore, sometimes there are view partials shared across some controllers
+that _do_ use `better_image_tag` and some that _do not_. In that case, you
+would want to ensure that the endpoints/controllers pulling those partials in
+will still function when the chained methods are called. In this case you can
+"disable" the better_image_tag functionality explicitly in the controller that
+is not using it:
+
+
+```
+class AnotherController < ApplicationController
+  include BetterImageTag::ImageTaggable
+
+  # explicitly pass through chained methods to default behavior
+  better_image_tag disabled: true
+end
+```
+
+## CLI usage
+
+There is an `inlineable` cli that will accept the path to a local image and will
+output a base64 data url that can be used in your image `src`, or css `url()`
+properties.
+
+Example:
+
+```sh
+$ inlineable ./path/to/image.jpg
+data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEAAkGB ... a whole lot o' letters & numbers
+```
+
+## Features
+
+`better_image_tag`, by default, keeps the stock `image_tag` implementation
+but extends it with chainable methods that will mutate the contents of
+the generated `<img/>` tag. This is done purposefully to allow you to keep
+things as they stand until you're ready to tackle those image-heavy corners
+of your app.
+
+Examples - chainable methods on `image_tag`:
+
+* `#with_size` finds the size of an image by fetching as little data as needed. *Note:* If a `height` or `width` property are passed to the image tag then this will not run.
+
+```
+<%= image_tag("http://example.com/file.jpg").with_size %>
+
+# => <img src="http://example.com/file.jpg" width="320" height="240">
+```
+
+* `#lazy_load`
+
+```
+<%= image_tag("http://example.com/file.jpg").lazy_load %>
+
+# => <img class="lazyload" data-src="http://example.com/file.jpg" src="data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw==" />
+```
+
+* `#webp`
+
+```
+<%= image_tag("http://example.com/file.jpg").webp %>
+
+# => <picture>
+       <!--[if IE 9]><video style="display: none;"><![endif]-->
+       <source srcset="http://example.com/file.webp" type="image/webp">
+       <!--[if IE 9]></video><![endif]-->
+       <img src="http://example.com/file.jpg" />
+     </picture>
+
+# OPTIONAL -- pass url to where another WEBP is:
+
+<%= image_tag("http://example.com/file.jpg").webp("https://some.other-cdn.com/file.webp") %>
+
+# => <picture>
+       <!--[if IE 9]><video style="display: none;"><![endif]-->
+       <source srcset="https://some.other-cdn.com/file.webp" type="image/webp">
+       <!--[if IE 9]></video><![endif]-->
+       <img src="http://example.com/file.jpg" />
+     </picture>
+```
+
+* `#avif`
+
+```
+<%= image_tag("http://example.com/file.jpg").avif %>
+
+# => <picture>
+       <!--[if IE 9]><video style="display: none;"><![endif]-->
+       <source srcset="http://example.com/file.avif" type="image/avif">
+       <!--[if IE 9]></video><![endif]-->
+       <img src="http://example.com/file.jpg" />
+     </picture>
+
+# OPTIONAL -- pass url to where another AVIF is:
+
+<%= image_tag("http://example.com/file.jpg").avif("https://some.other-cdn.com/file.avif") %>
+
+# => <picture>
+       <!--[if IE 9]><video style="display: none;"><![endif]-->
+       <source srcset="https://some.other-cdn.com/file.avif" type="image/avif">
+       <!--[if IE 9]></video><![endif]-->
+       <img src="http://example.com/file.jpg" />
+     </picture>
+```
+
+* `#avif` *AND* `#webp` -- use them both!
+
+```
+<%= image_tag("http://example.com/file.jpg").avif.webp %>
+
+# => <picture>
+       <!--[if IE 9]><video style="display: none;"><![endif]-->
+       <source srcset="http://example.com/file.avif" type="image/avif">
+       <source srcset="http://example.com/file.webp" type="image/webp">
+       <!--[if IE 9]></video><![endif]-->
+       <img src="http://example.com/file.jpg" />
+     </picture>
+```
+
+* `#inline`
+
+```
+<%= image_tag("http://example.com/file.jpg").inline %>
+
+# => <img src="data:image/jpg;base64...">
+```
+
+## Rake task(s)
+
+Included in this gem are a pair of rake tasks that will find all jpg's in your project and will convert them to webp's, or avif's, if you have the appropriate tooling available on your machine.
+
+```
+bundle exec rake better_image_tag:convert_jpgs_to_webp
+bundle exec rake better_image_tag:convert_jpgs_to_avif
+```
+
+For webp you will need [ImageMagick] installed. On Macs with [homebrew] you may install with `brew install imagemagick`.
+
+For avif you will need the `go-avif` tool, which has [binaries publicly available on their GitHub releases page].
+
+[ImageMagick]: https://imagemagick.org/index.php
+[homebrew]: https://brew.sh
+[binaries publicly available on their GitHub releases page]: https://github.com/Kagami/go-avif/releases
+
+## Testing
+
+If you use RSpec we have provided some helpers that you may add to `rails_helper.rb` that
+will allow your specs to:
+
+1. For all specs -- turn the inlining or size fetching features off.
+2. For helper or view specs -- configure the `better_image_tag` functionality per test.
+
+
+In `rails_helper.rb`,
+add the following:
+
+```ruby
+require "better_image_tag/rspec"
+
+RSpec.configure do |config|
+  # ...
+  config.include BetterImageTag::SpecHelpers
+  config.include BetterImageTag::ViewSpecHelpers, type: :view
+  config.include BetterImageTag::ViewSpecHelpers, type: :helper
+  # ...
+```
+
+In any of your specs you may disable inlining or sizing with the following helper methods:
+
+```ruby
+disable_better_image_tag_sizing!
+disable_better_image_tag_inlining!
+```
+
+In your _view_ or _helper_ spec(s) you can configure the functionality with the same
+options you can pass through the controller class method. For example:
+
+```ruby
+require "rails_helper"
+
+RSpec.describe "home/index.html.erb", type: :view do
+  it "renders main partial with inlined logo image" do
+    better_image_tag
+
+    render
+
+    expect(rendered).to render_template("shared/_header")
+    # expect(rendered).to have_inlined_logo
+  end
+
+  it "renders default image tag" do
+    better_image_tag disabled: true
+
+    render
+
+    # ... assertions here.
+  end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jayroh/better_image_tag. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the BetterImageTag project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/jayroh/better_image_tag/blob/master/CODE_OF_CONDUCT.md).
+
+[Google's lighthouse page speed tool]: https://developers.google.com/web/tools/lighthouse
+[WebPageTest]: https://webpagetest.org
+[lazysizes]: https://github.com/aFarkas/lazysizes

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+Dir.glob('./lib/better_image_tag/tasks/*.rake').each do |rake|
+  import rake
+end
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/app/controllers/concerns/better_image_tag/image_taggable.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+
+module BetterImageTag
+  module ImageTaggable
+    extend ::ActiveSupport::Concern
+
+    module ClassMethods
+      attr_reader :better_image_tag_options
+
+      def better_image_tag(better_image_tag_options = {})
+        @better_image_tag_options = better_image_tag_options
+                                    .with_indifferent_access
+      end
+    end
+
+    included do
+      helper_method :image_tag
+    end
+
+    def image_tag(image, options = {})
+      return ActionController::Base.helpers.image_tag(image, options) if options.delete(:use_super)
+
+      better_image_tag = if better_image_tag_allowed?
+                           BetterImageTag::ImageTag.new(view_context, image, options)
+                         else
+                           BetterImageTag::BaseImageTag.new(view_context, image, options)
+                         end
+
+      return better_image_tag.picture_tag.to_s if options.delete(:use_picture)
+
+      better_image_tag
+    end
+
+    private
+
+    def better_image_tag_allowed?
+      options = self.class.better_image_tag_options || {}
+
+      return send(options[:if]) if options[:if].present?
+      return !send(options[:unless]) if options[:unless].present?
+      return !options[:disabled] if options[:disabled].present?
+
+      true
+    end
+  end
+end

data/better_image_tag.gemspec

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'better_image_tag/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'better_image_tag'
+  spec.version       = BetterImageTag::VERSION
+  spec.authors       = ['Joel Oliveira']
+  spec.email         = ['joel.oliveira@ezcater.com']
+
+  spec.summary       = 'A more robust and optimized rails image_tag'
+  spec.description   = <<~EODESC
+    From lazy loading, to inline image contents, to fetching unknown width and
+    height, to next generation image formats, this gem aims to extend the
+    default image_tag method to do more for static web pages.
+  EODESC
+  spec.homepage      = 'https://www.ezcater.com'
+  spec.license       = 'MIT'
+
+  # Specify which files should be added to the gem when it is released.  The
+  # `git ls-files -z` loads the files in the RubyGem that have been added into
+  # git.
+  spec.files         = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.match(%r{^(test|spec|features)/})
+    end
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'fastimage'
+  spec.add_dependency 'mimemagic'
+  spec.add_dependency 'rails', ['>= 5', '< 7.0']
+
+
+  spec.add_development_dependency 'bundler', '~> 2.1'
+  spec.add_development_dependency 'pry-byebug'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
+  spec.add_development_dependency 'rspec-rails'
+  spec.add_development_dependency 'vcr'
+  spec.add_development_dependency 'webmock'
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "better_image_tag"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/inlineable

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+STDOUT.sync = true
+
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+
+require 'better_image_tag'
+
+puts BetterImageTag::InlineData.inline_data(ARGV[0], local_file: true)

data/lib/better_image_tag/base_image_tag.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module BetterImageTag
+  class BaseImageTag
+    attr_reader :view_context, :options, :image
+
+    def initialize(view_context, image, options = {})
+      @view_context = view_context
+      @image = image
+      @options = options.symbolize_keys
+    end
+
+    def with_size
+      self
+    end
+
+    def lazy_load(**_args)
+      self
+    end
+
+    def webp
+      self
+    end
+
+    def avif
+      self
+    end
+
+    def inline
+      self
+    end
+
+    def to_s
+      view_context.image_tag(image, options.merge(use_super: true))
+    end
+  end
+end

data/lib/better_image_tag/commands/clear_inline_cache.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module BetterImageTag
+  module Commands
+    class ClearInlineCache
+      def self.call
+        new.call
+      end
+
+      def call
+        inline_cache_keys.select do |key|
+          Rails.cache.delete key
+        end
+      end
+
+      private
+
+      def inline_cache_keys
+        cache_keys.select do |key|
+          key.start_with? BetterImageTag::InlineData::CACHE_PREFIX
+        end
+      end
+
+      def cache_keys
+        Rails.cache.instance_variable_get(:@data)&.keys || []
+      end
+    end
+  end
+end