jekyll_picture_tag 1.9.0 → 1.10.0

data/docs/releases.md

@@ -2,6 +2,10 @@
 ---
 # Release History
 
+* 1.10.0 May 11, 2020
+  * **Image Cropping support!** access the power of ImageMagick's `crop` function.
+  * Don't issue a warning when `default` preset is not found.
+  * Documentation improvements
 * 1.9.0 Feb 2, 2020
   * Add `fast_build` global setting
   * Add `disabled` global setting

data/docs/usage.md

@@ -1,11 +1,12 @@
 ---
 ---
+
 # How to use the Liquid Tag:
 
 ## Format:
 
 {% raw %}
-`{% picture [preset] (base image) [alternate images] [attributes] %}`
+`{% picture [preset] (image) [crop] [alternate images & crops] [attributes] %}`
 {% endraw %}
 
 The only required argument is the base image. Line breaks and extra spaces are fine, and you can
@@ -16,50 +17,79 @@ use liquid variables anywhere.
 {% raw %}
 `{% picture example.jpg %}`
 
-`{% picture thumbnail example.jpg --alt Example Image %}`
+`{% picture thumbnail example.jpg 1:1 --alt Example Image %}`
 
-`{% picture example.jpg --picture class="attribute-demo" %}`
+`{% picture example.jpg 16:9 north --picture class="attribute-demo" %}`
 
 `{% picture blog_index {{ post.image }} --link {{ post.url }} %}`
 
 `{% picture "some example.jpg" mobile: other\ example.jpg %}`
 
 ```md
-{% picture 
-  hero 
-  example.jpg 
-  tablet: example_cropped.jpg
-  mobile: example_cropped_more.jpg 
-  --alt Happy Puppy 
-  --picture class="hero" 
+{% picture
+  hero
+  example.jpg 16:9 east
+  tablet: example_cropped.jpg 3:2 east
+  mobile: example_cropped_more.jpg 1:1-50+0 east
+  --alt Happy Puppy
+  --picture class="hero"
   --link /
 %}
 ```
+
 {% endraw %}
 
 ## Argument reference
 
 Given in order:
 
-* **Preset**
+- **Preset**
 
   Select a [markup preset]({{ site.baseurl }}/presets#markup-presets), or omit to use the `default` preset. Presets
   are collections of settings that determine nearly everything about JPT's output, from the image
   formats used to the exact format your markup will take.
 
-* **Base Image** (Required)
+- **Base Image** (Required)
 
   Can be any raster image (as long as you have the required ImageMagick delegate). Relative to
   jekyll's root directory, or the `source` [setting]({{ site.baseurl }}/global_configuration) if you've configured it.
 
-  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\
-  image.jpg`).
+  For filenames with spaces, either use double quotes (`"my image.jpg"`) or a backslash (`my\ image.jpg`).
+
+- **Crop**
+
+  **Check the [ installation guide ](installation) before using this feature.**
+
+  Crop an image to a given aspect ratio or size. This argument is given as a `geometry` and
+  (optionally) a `gravity`, which can appear in either order and are thin wrappers around
+  ImageMagick's [geometry](http://www.imagemagick.org/script/command-line-processing.php#geometry)
+  and [gravity](http://www.imagemagick.org/script/command-line-options.php#gravity) settings. The
+  values given here will override the preset settings (if present), can be given after every image,
+  and apply only to the preceding image.
+
+  Geometry can take many forms, but most likely you'll want to set an aspect ratio-- given in the
+  standard `width:height` ratio such as `3:2`. Gravity sets which portion of the image to keep, and
+  is given in compass directions (`north`, `southeast`, etc) or `center` (default). Cropping happens
+  before resizing; the preset `widths` setting is a post-crop value.
 
-* **Alternate images**
+  If you'd like more fine-grained control, this can be offset by appending `+|-x` and (optionally)
+  `y` pixel values to the _geometry_ (not the gravity!). Example: `1:1+400 west` means "Crop to a
+  1:1 aspect ratio, starting 400 pixels from the left side.", and `north 3:2+0+100` means "Crop to
+  3:2, starting 100 pixels from the top." These can get a bit persnickety; there's nothing to stop
+  you from running off the side of the image. Pay attention.
 
-    *Format:* `(media query preset): (filename) (...)`
+  For detailed documentation, see ImageMagick's
+  [crop](http://www.imagemagick.org/script/command-line-options.php#crop) tool.
 
-    *Example:* `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
+  _Note:_ If you do a lot of trial and error with these, it's a good idea to manually delete your
+  generated images folder more often as each change will build a new set of images without removing
+  the old ones.
+
+- **Alternate images**
+
+  _Format:_ `(media query preset): (filename) (...)`
+
+  _Example:_ `tablet: img_cropped.jpg mobile: img_cropped_more.jpg`
 
   Optionally specify any number of alternate base images for given [screen
   sizes]({{ site.baseurl }}/presets/#media-presets) (specified in `_data/picture.yml`). This is called [art
@@ -70,44 +100,44 @@ Given in order:
   be provided to the browser in reverse order, and it will select the first one with an applicable
   media query.
 
-* **Attributes**
+- **Attributes**
 
   Optionally specify any number of HTML attributes, or an href target. These will be added to any
   attributes you've set in a preset.
 
-  * **`--link`**
+  - **`--link`**
 
-    *Format:* `--link (some url)`
+    _Format:_ `--link (some url)`
 
-    *Examples*: `--link https://example.com`, `--link /blog/some_post/`
+    _Examples_: `--link https://example.com`, `--link /blog/some_post/`
 
-      Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
-      This will override automatic source image linking, if you have enabled it.
+    Wrap the image in an anchor tag, with the `href` attribute set to whatever value you give it.
+    This will override automatic source image linking, if you have enabled it.
 
-      **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
-      [here]({{ site.baseurl }}/notes).
+    **Note**: If you get either mangled HTML or extra {::nomarkdown} tags when using this, read
+    [here]({{ site.baseurl }}/notes).
 
-  * **`--alt`**
-  
-    *Format:* `--alt (alt text)`
+  - **`--alt`**
 
-    *Example:* `--alt Here is my alt text!`
+    _Format:_ `--alt (alt text)`
+
+    _Example:_ `--alt Here is my alt text!`
 
     Convenience shortcut for `--img alt="..."`
-  
-  * **`--(element)`**
 
-    *Format:* `--(picture|img|source|a|parent) (Standard HTML attributes)`
+  - **`--(element)`**
+
+    _Format:_ `--(picture|img|source|a|parent) (Standard HTML attributes)`
 
-    *Example:* `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
+    _Example:_ `--img class="awesome-fade-in" id="coolio" --a data-awesomeness="11"`
 
     Apply attributes to a given HTML element. Your options are:
 
-    * `picture`
-    * `img`
-    * `source`
-    * `a` (anchor tag)
-    * `parent`
+    - `picture`
+    - `img`
+    - `source`
+    - `a` (anchor tag)
+    - `parent`
 
     `--parent` will be applied to the `<picture>` if present, otherwise the `<img>`; useful when
     using an `auto` output format.

data/jekyll_picture_tag.gemspec

@@ -38,9 +38,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'solargraph'
 
   spec.add_dependency 'addressable', '~> 2.6'
+  spec.add_dependency 'base32', '~> 0.3'
   spec.add_dependency 'mime-types', '~> 3'
   spec.add_dependency 'mini_magick', '~> 4'
-  spec.add_dependency 'objective_elements', '~> 1.1.1'
+  spec.add_dependency 'objective_elements', '~> 1.1.2'
 
   spec.add_runtime_dependency 'jekyll', '< 5'
 end

data/lib/jekyll_picture_tag/defaults/presets.yml

@@ -7,3 +7,4 @@ noscript: false
 link_source: false
 quality: 75
 data_sizes: true
+gravity: center

data/lib/jekyll_picture_tag/generated_image.rb

@@ -1,4 +1,5 @@
 require 'mini_magick'
+require 'base32'
 
 module PictureTag
   # Represents a generated image file.
@@ -6,10 +7,12 @@ module PictureTag
     attr_reader :width, :format
     include MiniMagick
 
-    def initialize(source_file:, width:, format:)
+    def initialize(source_file:, width:, format:, crop: nil, gravity: '')
       @source = source_file
       @width  = width
       @format = process_format format
+      @crop = crop
+      @gravity = gravity
     end
 
     def exists?
@@ -38,6 +41,10 @@ module PictureTag
       ImgURI.new(name).to_s
     end
 
+    def cropped_source_width
+      image.width
+    end
+
     private
 
     # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
@@ -57,7 +64,19 @@ module PictureTag
     # /home/dave/my_blog/_site/generated/somefolder/myimage-100-123abc.jpg
     #                                                                 ^^^^
     def name_right
-      '.' + @format
+      crop_code + '.' + @format
+    end
+
+    # Hash the crop settings, so we can detect when they change.  We use a
+    # base32 encoding scheme to pack more information into fewer characters,
+    # without dealing with various filesystem naming limitations that would crop
+    # up using base64 (such as NTFS being case insensitive).
+    def crop_code
+      return '' unless @crop
+
+      Base32.encode(
+        Digest::MD5.hexdigest(@crop + @gravity)
+      )[0..2]
     end
 
     # Used for the fast build option: look for a file which matches everything
@@ -77,15 +96,12 @@ module PictureTag
 
     # Returns a list of images which are probably correct.
     def dest_glob
-      Dir.glob File.join(PictureTag.dest_dir, name_left + '?' * 6 + name_right)
-    end
+      query = File.join(
+        PictureTag.dest_dir,
+        name_left + '?' * 6 + name_right
+      )
 
-    def image
-      @image ||= Image.open(@source.name)
-    end
-
-    def dest_dir
-      File.dirname absolute_filename
+      Dir.glob query
     end
 
     def generate_image
@@ -94,10 +110,26 @@ module PictureTag
       write_image
     end
 
+    def image
+      @image ||= open_image
+    end
+
+    def open_image
+      image_base = Image.open(@source.name)
+      image_base.combine_options do |i|
+        i.auto_orient
+        if @crop
+          i.gravity @gravity
+          i.crop @crop
+        end
+      end
+
+      image_base
+    end
+
     def process_image
       image.combine_options do |i|
         i.resize "#{@width}x"
-        i.auto_orient
         i.strip
       end
 
@@ -106,16 +138,16 @@ module PictureTag
     end
 
     def write_image
-      check_dest_dir
+      # Make sure destination directory exists:
+      FileUtils.mkdir_p(dest_dir) unless Dir.exist?(dest_dir)
 
       image.write absolute_filename
 
       FileUtils.chmod(0o644, absolute_filename)
     end
 
-    # Make sure destination directory exists
-    def check_dest_dir
-      FileUtils.mkdir_p(dest_dir) unless Dir.exist?(dest_dir)
+    def dest_dir
+      File.dirname absolute_filename
     end
 
     def process_format(format)

data/lib/jekyll_picture_tag/instructions.rb

@@ -3,3 +3,4 @@ require_relative './instructions/configuration'
 require_relative './instructions/html_attributes'
 require_relative './instructions/preset'
 require_relative './instructions/tag_parser'
+require_relative './instructions/arg_splitter'

data/lib/jekyll_picture_tag/instructions/arg_splitter.rb

@@ -0,0 +1,68 @@
+module PictureTag
+  module Instructions
+    # This class takes in the arguments passed to the liquid tag, and splits it
+    # up into 'words' (correctly handling quotes and backslash escapes.)
+    #
+    # To handle quotes and backslash escaping, we have to parse the string by
+    # characters to break it up correctly. I'm sure there's a library to do
+    # this, but it's not that much code honestly. If this starts getting big,
+    # we'll pull in a new dependency.
+    #
+    class ArgSplitter
+      attr_reader :words
+
+      def initialize(raw_params)
+        @words = []
+        @word = ''
+        @in_quotes = false
+        @escaped = false
+
+        raw_params.each_char { |c| handle_char(c) }
+
+        add_word # We have to explicitly add the last one.
+      end
+
+      private
+
+      def handle_char(char)
+        # last character was a backslash:
+        if @escaped
+          close_escape char
+
+        # char is a backslash or a quote:
+        elsif char.match?(/["\\]/)
+          handle_special char
+
+        # Character isn't whitespace, or it's inside double quotes:
+        elsif @in_quotes || char.match(/\S/)
+          @word << char
+
+        # Character is whitespace outside of double quotes:
+        else
+          add_word
+        end
+      end
+
+      def add_word
+        return if @word.empty?
+
+        @words << @word
+        @word = ''
+      end
+
+      def handle_special(char)
+        if char == '\\'
+          @escaped = true
+        elsif char == '"'
+          @in_quotes = !@in_quotes
+          @word << char
+        end
+      end
+
+      def close_escape(char)
+        @word << char
+        @escaped = false
+      end
+    end
+  end
+end

data/lib/jekyll_picture_tag/instructions/preset.rb

@@ -12,13 +12,6 @@ module PictureTag
         @content[key]
       end
 
-      # Returns the set of widths to use for a given media query.
-      def widths(media)
-        width_hash = self['media_widths'] || {}
-        width_hash.default = self['widths']
-        width_hash[media]
-      end
-
       def formats
         @content['formats']
       end
@@ -41,15 +34,38 @@ module PictureTag
         end
       end
 
+      # Image widths to generate for a given media query.
+      def widths(media = nil)
+        setting_lookup('widths', 'media', media)
+      end
+
+      # Image quality setting, possibly dependent on format.
       def quality(format = nil)
-        qualities = @content['format_quality'] || {}
-        qualities.default = @content['quality']
+        setting_lookup('quality', 'format', format)
+      end
+
+      # Gravity setting (for imagemagick cropping)
+      def gravity(media = nil)
+        setting_lookup('gravity', 'media', media)
+      end
 
-        qualities[format]
+      # Crop value
+      def crop(media = nil)
+        setting_lookup('crop', 'media', media)
       end
 
       private
 
+      # Return arbitrary setting values, taking their defaults into account.
+      # Ex: quality can be set for all image formats, or individually per
+      # format. Per-format settings should override the general setting.
+      def setting_lookup(setting, prefix, lookup)
+        media_values = @content[prefix + '_' + setting] || {}
+        media_values.default = @content[setting]
+
+        media_values[lookup]
+      end
+
       def build_preset
         # The _data/picture.yml file is optional.
         picture_data_file = grab_data_file
@@ -70,10 +86,14 @@ module PictureTag
       end
 
       def no_preset
-        Utils.warning(
-          " Preset \"#{@name}\" not found in #{PictureTag.config['data_dir']}/"\
-          + 'picture.yml under markup_presets key. Using default values.'
-        )
+        unless @name == 'default'
+          Utils.warning(
+            <<~HEREDOC
+              Preset "#{@name}" not found in {PictureTag.config['data_dir']}/picture.yml
+              under markup_presets key. Using default values."
+            HEREDOC
+          )
+        end
 
         {}
       end