Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Massive Rewrite and Update #88

Merged
merged 111 commits into from
Nov 29, 2018
Merged

Massive Rewrite and Update #88

merged 111 commits into from
Nov 29, 2018

Conversation

rbuchberger
Copy link
Owner

@rbuchberger rbuchberger commented Nov 28, 2018

Forgive the chaotic commit log.

I'll leave this pull request up for a little while for input, and then merge it into master if there are no objections!

Motivation

Most importantly, I want to thank Rob Wierzbowski and all the original contributors. While the
changes in this version are very extensive, its roots are still based in the purpose and approach of
the original.

Jekyll Picture Tag's last update was in October 2015. While the plugin grew stale, its application
certainly didn't; doing responsive images correctly is still involved, tedious, and tricky, and
there are still a few people out there building Jekyll sites.

Browser adoption of picture, source, srcset, and sizes is far better when this plugin was
first written. Firefox gained support in May of 2015, Safari in October of 2015, and Edge in october
of 2017. As of November 2018, all major, modern browsers have support and caniuse reports global
compatibility at 88%.

PictureTag's previous versions supported a few javascript solutions, but they didn't do a great job
supporting stock HTML (which, given browser suppport, was the most appropriate decision at the time).
That situation has now changed; standard HTML should be considered its core functionality, while
maintaining the ability to support javascript-based solutions in the future.

Goals

These were the objectives of the rewrite:

  • Do not stray beyond the original objective of this plugin: Automate the creation of responsive
    image files and their associated markup.
    In other words, do one thing well.
  • Maintain backwards compatibility with the old liquid tag syntax, to save website maintainers from
    needing changes made across their entire website.
  • Streamline the configuration process, ideally make all configuration optional. In the absence of
    explicit instruction, do something reasonable.
  • Enable multiple image formats (specifically webp). Generalize and modularize the code which
    generates output markup formats, to simplify the addition of new ones.
  • Break up the original plugin, which consists of ~250 (very long) lines split across only 3
    functions, into something more manageable.

Changes

  • The default output formats are bone-stock HTML (both <picture> and <img>. Picturefill, as of
    version 3, no longer requires special markup, so it remains compatible. Other javascript image
    solutions are supported with the data_ selection of markup formats. Interchange support is
    removed, though adding it again is not difficult if there is demand for it.
  • There are now 2 basic markup formats to choose from: <source> tags within a <picture>, and a
    single <img> tag. If markup is set to 'auto', or if it is not set at all, the plugin will
    automatically determine which is most appropriate. These formats also have data_ counterparts
    (i.e. data_auto), which accomplish the same thing except setting respective data-attributes
    to allow for lazy loading and such.
  • There are also 2 srcset formats: one which supplies image width, and another which supplies
    multiples (pixel ratios) of the base size.
  • Source Keys are replaced by media query presets, which can also be used to create the 'sizes'
    attribute.
  • Jekyll Picture Tag no longer accepts height arguments, and will no longer crop images for you.
    Aspect ratio will always be maintained.
  • Multiple image widths are now supported, which will be used to create a corresponding srcset.
  • Multiple image formats are now possible, including webp.
  • PictureTag can now generate sizes attributes.
  • Configuration takes a very different format. It should be simpler to write your config than the
    old version, and migrating to it should not be difficult. Instead of creating individual source
    keys, you supply an array of widths you'd like to construct. You can also supply an array (yaml
    sequence) of formats, including 'original'.
  • Only global settings are placed in _config.yml. Presets are moved to _data/picture.yml.

Stats:

Keep in mind that the new version adheres to an 80 character line limit, while the old version had no line limit at all. (There were some whoppers in there!)

rbuchberger@rikki-lenovo ~/development/jekyll-picture-tag                       [11:06:03] 
> $ cloc ./                                                                    [±master ✓]
      15 text files.
      15 unique files.                              
       7 files ignored.

github.com/AlDanial/cloc v 1.76  T=1.02 s (8.8 files/s, 621.8 lines/s)
--------------------------------------------------------------------------------
Language                      files          blank        comment           code
--------------------------------------------------------------------------------
Ruby                              3             51             54            176
Markdown                          2             91              0            139
HTML                              2              9              5             48
YAML                              1              2              4             47
Bourne Again Shell                1              2              1              4
--------------------------------------------------------------------------------
SUM:                              9            155             64            414
--------------------------------------------------------------------------------
                                                                                               
rbuchberger@rikki-lenovo ~/development/jekyll-picture-tag                       [11:06:07] 
> $ git checkout refactor                                                      [±master ✓]
Switched to branch 'refactor'
                                                                                               
rbuchberger@rikki-lenovo ~/development/jekyll-picture-tag                       [11:06:12] 
> $ cloc ./                                                                  [±refactor ✓]
      38 text files.
      38 unique files.                              
       7 files ignored.

github.com/AlDanial/cloc v 1.76  T=1.02 s (31.5 files/s, 1779.1 lines/s)
--------------------------------------------------------------------------------
Language                      files          blank        comment           code
--------------------------------------------------------------------------------
Ruby                             24            170            170            653
Markdown                          3            189              0            523
YAML                              4             13             33             49
Bourne Again Shell                1              2              1              4
--------------------------------------------------------------------------------
SUM:                             32            374            204           1229
--------------------------------------------------------------------------------

Issues Fixed, implemented, or rendered irrelevant:

close #75, close #71, close #68, close #63, close #54, close #52, close #51,
close #26, close #24, close #19, close #13, close #12, close #7, close #6,
close #5

Remember to delete before merging into master
I didn't want to break the existing API, but now I think it will be
necessary for the sake of sanity.

I'll set reasonable defaults, so the plugin is useful without any
configuration at all (except possibly the destination folder)

Global picturetag settings will live in _config.yml, as before. Presets
will live in _data/picture.yml. Souces will be listed under the sources
key, rather than inline with preset settings, and will lose the
'source_' prefix.
Deleted 'generator' and 'srcset' files. Source inherits from objective
elements' SingleTag, because that's what it is.

Generated files belong to a source, and will know their own names,
formats, pixel ratios, sizes, and source files. Will handle file
generation logic and calls to imagemagick.
The master (PictureTag) class will handle the high level decision making
and interfacing with Jekyll. Picture will take PictureTag's instructions
and generate the markup. (This involves generating the required sources,
which will each generate the files they need.)
Added --parent argument, updated behavior of implicit html attributes to
match previous version. Updated relevant documentation.
Extracted most source-file related logic and properties to it. Source
files are persisted within a given PictureTag, so expensive operations
(such as getting its size and building an MD5 checksum) are only
performed once.
Consolidate warning related code in Utils module.

Create setting to suppress error messages

Set default suppression to false, add related documentation
@rbuchberger rbuchberger merged commit 0f38ff4 into master Nov 29, 2018
@rbuchberger rbuchberger deleted the refactor branch November 29, 2018 16:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment