Smart Cross-platform Image Delivery Plugin - smart_images

Yet another smart Image Delivery plugin for jQuery that automatically updates the src of an img tag and pulls in the image appropriate to the current window width.

Dependencies:

• jQuery.
• BreakpointX: Define responsive breakpoints, register callbacks when crossing, with optional css class handling.

Installation:

# Yarn
$ yarn add @aklump/smart-images

# NPM
$ npm install @aklump/smart-images --save

How to use it:

1. Include the needed JavaScript file as noticed above in your html document.

<script src="/path/to/jquery.min.js"></script>
<script src="/path/to/BreakpointX.js"></script>

2. Download and include the jQuery smart_images plugin after jQuery.

<script src="jquery.smart_images.js"></script>

3. The markup.

• You MUST have at least two image paths defined based on a media query regarding a screen width.
• You MUST have only one min-width declaration and it needs to be 1px greater than your highest max-width declaration.
• You MAY have as many max-width declarations as you want breakpoints.
• Each max-width tag MUST define a path to an image the SHOULD be the same width as the max-width value.
• The single min-width tag MUST define a path to the largest image you want to load and it SHOULD be larger than the min-width value, e.g., if min-width=769 the image may be 1080px wide.

<div class="smart-image">
  <span data-si-srcset="small.jpg" data-si-media="(max-width: 319px)"></span>
  <span data-si-srcset="medium.jpg" data-si-media="(max-width: 479px)"></span>
  <span data-si-srcset="large.jpg" data-si-media="(max-width: 767px)"></span>
  <span data-si-srcset="full.jpg" data-si-media="(min-width: 768px)"></span>
  <img/>
</div>

4. Initialize the plugin on document ready and we're done.

$('.smart-image').smartImages();

5. To get the SmartImages object after it's attached you can do this:

var smartImages = $('.smart-image').data('smartImages');

6. Possible plugin settings with default values.

/**
 * Namespace for all data tags, e.g. 'si-'.
 */
dataPrefix     : 'si-',
dataSrcSuffix  : 'srcset',
dataMediaSuffix: 'media',

/**
 * Used with $el.find() to locate the img tag that gets replaced with src.
 */
imgSelector: 'img',

/**
 * Used with $el.find() to locate the tags that contain the srcsets. By default this is null because it uses the
 * data suffixes above, but setting it here will override that behavior.  This would allow you to use an alternate
 * structure if necessary.
 */
srcSelector: null,

/**
 * How many milliseconds to wait to read the window width after a resize event.
 */
resizeThrottle: 300,

/**
 * This setting answers the question of loading smaller images when the window downsizes.
 *
 * 'never' means the largest image that gets loaded first will always show.  Use this method to reduce bandwidth,
 * and if aspect ratios are the same across breakpoints.  THIS IS THE FASTEST AND USES THE LEAST BANDWIDTH.
 *
 * Setting this to 'always' will mean that the images are swapped BOTH when the window grows larger and grows
 * smaller and results in more data transfer when the window starts out larger because the smaller images need to
 * be downloaded.  One reason to choose this setting is if the aspect ratios are different for different
 * breakpoints--to ensure images don't distort.  USE THIS OPTION IF ASPECT RATIOS ARE DIFFERENT ACROSS BREAKPOINTS.
 *
 * 'loaded' means smaller images will be shown if they were previously loaded.  This happens when the window starts
 * out small, grows larger, then shrinks back.  This option may give better visual appearance because the browser
 * is not resizing the image.  Compared to 'never' this results in a slight delay as the window grows larger, and
 * the image needs to be swapped out for the larger. USE THIS OPTION IF YOU NOTICE SMALLER IMAGES ARE NOT AS CLEAR
 * AS YOU WANT.
 *
 * One of:
 * - never
 * - always
 * - loaded
 */
downsize: 'never',

/**
 * Callback fired on initializing before loading the first images.
 */
onInit: null,

/**
 * Callback before a src change is to occur.  Only the first time this is called will `this.firstRun` be true.
 *
 * Return false to prevent the image src swap.
 *
 * @param string breakpoint name
 * @param string image src
 */
onBeforeChange: null,

/**
 * Callback just after a src change has occurred.
 *
 * @param string breakpoint name
 * @param string image src
 */
onAfterChange: null

Changelog:

v0.4.4 (2019-02-03)

• Update

v0.4.3 (2018-12-17)

• Update

v0.4.2 (2018-12-15)

• Update

v0.4.0 (2018-12-13)

• Changed name back to jquery.smart-images.js to be standards compliant.

v0.3.2 (2018-12-11)

• onBeforeChange now receives a segment object as the first argument.
• onAfterChange now receives a segment object as the first argument.

v0.2.4 (2018-12-05)

• JS update

v0.2.1 (2018-11-30)

• JS update

v0.1.7 (2017-05-19)

• JS update

v0.1.5 (2017-03-31)

• added new setting srcSelector

---

This awesome jQuery plugin is developed by aklump. For more Advanced Usages, please check the demo page or visit the official website.