new features for the exposed function

Author: jgnewman

README.md

@@ -185,6 +185,22 @@ To use retina.js the old-school way, download **retina.min.js** and put it on yo
 
 Using this technique, retina.js will run automatically on page load. It will also create a globally available function called `retinajs`. Whenever you'd like to manually re-initialize the script, simply call `window.retinajs()`.
 
+If you don't pass any arguments to the `retinajs` function, it will only attempt to process images that have not previously been processed by the script. Optionally, you can pass a collection of HTML elements to the script, in which case it will only attempt to process elements in that collection, specifically the ones that have not been processed before. Your collection may take the form of an Array, NodeList, or jQuery selection.
+
+```javascript
+retinajs();
+// Finds all images not previously processed and processes them.
+
+retinajs( [img, img, img] );
+// Only attempts to process the images in the collection.
+
+retinajs( $('img') );
+// Same.
+
+retinajs( document.querySelectorAll('img') );
+// Same.
+```
+
 #### New-School
 
 To use retina.js the new-school way, you'll want to `require` it (or `import` it if you're using ES6) into your Gulp/Webpack/Grunt/CommonJS/etc application. In this case, the script won't run automatically. Instead, it'll let you determine when you'd like it to run.
@@ -197,6 +213,22 @@ window.addEventListener('load', retina);
 
 Notice that the `retina` function can be called as often as you need in order to re-initialize the image swapping.
 
+If you don't pass any arguments to the `retina` function, it will only attempt to process images that have not previously been processed by the script. Optionally, you can pass a collection of HTML elements to the script, in which case it will only attempt to process elements in that collection, specifically the ones that have not been processed before. Your collection may take the form of an Array, NodeList, or jQuery selection.
+
+```javascript
+retina();
+// Finds all images not previously processed and processes them.
+
+retina( [img, img, img] );
+// Only attempts to process the images in the collection.
+
+retina( $('img') );
+// Same.
+
+retina( document.querySelectorAll('img') );
+// Same.
+```
+
 ### CSS Preprocessors
 
 The process for including the CSS mixins is relatively straightforward. Here is a breakdown for each:

dist/retina.js

@@ -1,5 +1,5 @@
 /*!
- * Retina.js v2.0.0
+ * Retina.js v2.1.0
  *
  * Copyright 2016 Axial, LLC
  * Released under the MIT license
@@ -34,6 +34,22 @@ var inlineReplace = /url\(('|")?([^\)'"]+)('|")?\)/i;
  */
 var selector = '[data-rjs]';
 
+/*
+ * Define the attribute we'll use to mark an image as having been processed.
+ */
+var processedAttr = 'data-rjs-processed';
+
+/**
+ * Shortcut for turning some iterable object into an array.
+ *
+ * @param  {Iterable} object Any iterable object.
+ *
+ * @return {Array}
+ */
+function arrayify(object) {
+  return Array.prototype.slice.call(object);
+}
+
 /**
  * Chooses the actual image size to fetch, (for example 2 or 3) that
  * will be used to create a suffix like "@2x" or "@3x".
@@ -120,6 +136,11 @@ function setSourceIfAvailable(image, retinaURL) {
    * image resource.
    */
   testImage.setAttribute('src', retinaURL);
+
+  /*
+   * Mark our image as processed so that it won't be processed again.
+   */
+  image.setAttribute(processedAttr, true);
 }
 
 /**
@@ -164,10 +185,17 @@ function manualSwapImage(image, src, hdsrc) {
  * Collects all images matching our selector, and converts our
  * NodeList into an Array so that Array methods will be available to it.
  *
- * @return {Array} Contains all elements matching our selector.
+ * @param {Iterable} images  Optional. An Array, jQuery selection, or NodeList
+ *                           of elements to affect with retina.js.
+ *
+ * @return {Iterable} Contains all elements matching our selector.
  */
-function getImages() {
-  return typeof document !== 'undefined' ? Array.prototype.slice.call(document.querySelectorAll(selector)) : [];
+function getImages(images) {
+  if (!images) {
+    return typeof document !== 'undefined' ? arrayify(document.querySelectorAll(selector)) : [];
+  } else {
+    return typeof images.forEach === 'function' ? images : arrayify(images);
+  }
 }
 
 /**
@@ -186,23 +214,30 @@ function cleanBgImg(img) {
  * retina equivalent taking into account the environment capabilities and
  * the densities for which the user has provided images.
  *
+ * @param {Iterable} images  Optional. An Array, jQuery selection, or NodeList
+ *                           of elements to affect with retina.js. If not
+ *                           provided, retina.js will grab all images on the
+ *                           page.
+ *
  * @return {undefined}
  */
-function retina() {
-  getImages().forEach(function (img) {
-    var isImg = img.nodeName.toLowerCase() === 'img';
-    var src = isImg ? img.getAttribute('src') : cleanBgImg(img);
-    var rjs = img.getAttribute('data-rjs');
-    var rjsIsNumber = !isNaN(parseInt(rjs, 10));
-
-    /*
-     * If the user provided a number, dynamically swap out the image.
-     * If the user provided a url, do it manually.
-     */
-    if (rjsIsNumber) {
-      dynamicSwapImage(img, src, rjs);
-    } else {
-      manualSwapImage(img, src, rjs);
+function retina(images) {
+  getImages(images).forEach(function (img) {
+    if (!img.getAttribute(processedAttr)) {
+      var isImg = img.nodeName.toLowerCase() === 'img';
+      var src = isImg ? img.getAttribute('src') : cleanBgImg(img);
+      var rjs = img.getAttribute('data-rjs');
+      var rjsIsNumber = !isNaN(parseInt(rjs, 10));
+
+      /*
+       * If the user provided a number, dynamically swap out the image.
+       * If the user provided a url, do it manually.
+       */
+      if (rjsIsNumber) {
+        dynamicSwapImage(img, src, rjs);
+      } else {
+        manualSwapImage(img, src, rjs);
+      }
     }
   });
 }

dist/retina.min.js

@@ -1,6 +1,6 @@
 {
   "name": "retinajs",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "license": "MIT",
   "homepage": "https://github.com/imulus/retinajs",
   "bugs": "https://github.com/imulus/retinajs/issues",

package.json

@@ -20,6 +20,22 @@ const inlineReplace = /url\(('|")?([^\)'"]+)('|")?\)/i;
  */
 const selector = '[data-rjs]';
 
+/*
+ * Define the attribute we'll use to mark an image as having been processed.
+ */
+const processedAttr = 'data-rjs-processed';
+
+/**
+ * Shortcut for turning some iterable object into an array.
+ *
+ * @param  {Iterable} object Any iterable object.
+ *
+ * @return {Array}
+ */
+function arrayify(object) {
+  return Array.prototype.slice.call(object);
+}
+
 /**
  * Chooses the actual image size to fetch, (for example 2 or 3) that
  * will be used to create a suffix like "@2x" or "@3x".
@@ -106,6 +122,11 @@ function setSourceIfAvailable(image, retinaURL) {
    * image resource.
    */
   testImage.setAttribute('src', retinaURL);
+
+  /*
+   * Mark our image as processed so that it won't be processed again.
+   */
+  image.setAttribute(processedAttr, true);
 }
 
 /**
@@ -148,12 +169,19 @@ function manualSwapImage(image, src, hdsrc) {
  * Collects all images matching our selector, and converts our
  * NodeList into an Array so that Array methods will be available to it.
  *
- * @return {Array} Contains all elements matching our selector.
+ * @param {Iterable} images  Optional. An Array, jQuery selection, or NodeList
+ *                           of elements to affect with retina.js.
+ *
+ * @return {Iterable} Contains all elements matching our selector.
  */
-function getImages() {
-  return typeof document !== 'undefined' ? Array.prototype.slice.call(
-    document.querySelectorAll(selector)
-  ) : [];
+function getImages(images) {
+  if (!images) {
+    return typeof document !== 'undefined' ? arrayify(
+      document.querySelectorAll(selector)
+    ) : [];
+  } else {
+    return typeof images.forEach === 'function' ? images : arrayify(images);
+  }
 }
 
 /**
@@ -172,23 +200,30 @@ function cleanBgImg(img) {
  * retina equivalent taking into account the environment capabilities and
  * the densities for which the user has provided images.
  *
+ * @param {Iterable} images  Optional. An Array, jQuery selection, or NodeList
+ *                           of elements to affect with retina.js. If not
+ *                           provided, retina.js will grab all images on the
+ *                           page.
+ *
  * @return {undefined}
  */
-function retina() {
-  getImages().forEach(img => {
-    const isImg = img.nodeName.toLowerCase() === 'img';
-    const src = isImg ? img.getAttribute('src') : cleanBgImg(img);
-    const rjs = img.getAttribute('data-rjs');
-    const rjsIsNumber = !isNaN(parseInt(rjs, 10));
-
-    /*
-     * If the user provided a number, dynamically swap out the image.
-     * If the user provided a url, do it manually.
-     */
-    if (rjsIsNumber) {
-      dynamicSwapImage(img, src, rjs);
-    } else {
-      manualSwapImage(img, src, rjs);
+function retina(images) {
+  getImages(images).forEach(img => {
+    if (!img.getAttribute(processedAttr)) {
+      const isImg = img.nodeName.toLowerCase() === 'img';
+      const src = isImg ? img.getAttribute('src') : cleanBgImg(img);
+      const rjs = img.getAttribute('data-rjs');
+      const rjsIsNumber = !isNaN(parseInt(rjs, 10));
+
+      /*
+       * If the user provided a number, dynamically swap out the image.
+       * If the user provided a url, do it manually.
+       */
+      if (rjsIsNumber) {
+        dynamicSwapImage(img, src, rjs);
+      } else {
+        manualSwapImage(img, src, rjs);
+      }
     }
   });
 }