Respeto

Respeto is a deferred image loader with responsive design workflows in mind. It was borne of fire and steel (and some semicolons). You generate images, Respeto loads them based on media queries + HTML data attributes. Easy peasey.

This repository contains tests, a responsive workflow demo, and a bunch of other junk. If you only want the Respeto lib, then download respeto.min.js or simply bower install respeto.

Respeto is currently in alpha, which means it's feature-complete, and ready for real-world testing. So grab it and give it a spin!

TODO

• finish explaining what this is
• explain bandwidth vs. JS support implications
• nod to the ongoing responsive image standards conversation
• finish responsive workflow explanation
• this all seems like it goes in a web site, not a README, no?
• maybe remove jQuery as a dependency?

Usage

This can be used by itself, or with a responsive state manager. I've created a very simple state manager implementation in the /demo/js/demo.js file.

1 - Download the latest version of Respeto here or bower install respeto

Respeto depends on jQuery

2 - Add respeto.js to your HTML document (I recommend putting this at the bottom, before your closing </body> tag)

	...
	<script src="path_to_js/respeto.js"></script>
</body>

3 - Add Respeto data attributes where you want to manage image loading

<img src="lincoln_fallback.jpg" data-rsp-img="portrait_lincoln.jpg">
<img data-rsp-img="portrait_washington.jpg">
<img data-rsp-img="portrait_obama.jpg" data-rsp-path="custom/path/">
<div data-rsp-img="portrait_obama.jpg"></div>

4 - Create a Respeto object and run the load() method

$(function() { // jQuery.on('ready')

	var rsp = new Respeto();
	rsp.load('tablet');

});

5 - ...and your img elements get their src attributes set, and new images will load

<img src="portrait_lincoln_tablet.jpg" data-rsp-img="portrait_lincoln.jpg">
<img src="portrait_washington_tablet.jpg" data-rsp-img="portrait_washington.jpg">
<img src="custom/path/portrait_obama_tablet.jpg" data-rsp-img="portrait_obama.jpg" data-rsp-path="custom/path/">
<div style="background-image: url(http://your_site.com/portrait_obama_tablet.jpg)" data-rsp-img="portrait_obama.jpg"></div>

6 - [optional] Simple state-based usage

// this should be inside of a jQuery $.ready() function

var rsp = new Respeto();

var width = $(window).width();

if(width <= 480) {
  rsp.load('small'); // loads images with _small suffix
}

if(width > 480 && width <= 1024) {
  rsp.load('large'); // sets image sources with _large suffix
}

if(width > 1024) {
  rsp.load('huge'); // loads images with _huge suffix
}

Respeto recommends a responsive image workflow with Grunt and Grunt Responsive Images

A Responsive Image Workflow

Using Respeto really means that you're using a responsive image workflow (possibly for the first time). What I've created in the /demo directory constitutes a very simple example of a working responsive workflow.

Here are the pieces:

1. a source images directory
2. image workflow tools (in this case Grunt and ImageMagick)
3. a destination directory
4. Respeto, of course

1 - Source image management

• certain formats don't process well (animated gifs, svg)
• have a source images dir for processing, and a source images dir for copying
• my example only has a processing dir for brevity

2 - Image Workflow Tools

• Grunt
• Grunt Responsive Images (https://github.com/andismith/grunt-responsive-images)
• ImageMagick
• brew install ImageMagick if you're on OSX

3 - Destination image management

• no source control here
• .gitignore away
• compress wisely
• you can get away with more compression in retina (http://dh.karelia.com/retina/)

4 - Respeto implementation

• This is the easy part, eh? Depending on your needs, the rest of this README and examples should take care of this part...

API

new Respeto(options)

• options - object , optional . Respeto parameters, see below

Usage

var rsp = new Respeto();

Returns the object with the following methods:

• rsp.load(label, options) - processes targets that contain Respeto data attributes and assigns src or style properties as necessary. options is an optional object where you may specify a context, a selector to match, and/or a selector to exclude:
• context: a jQuery selector that limits the scope of what you're loading. Useful if you're working in a single-page app, and you only want to load images inside a specific container.
• match: a jQuery selector that limits the scope of what you're loading to elements that match this option.
• exclude: a single jQuery selector (not comma-delimited)

options

Parameter	Type	Default Value	Example	Description
imageDataAttribute	string	'rsp-img'	'image-source'	This translates into a data attribute that contains a source image. Using the default, it will look like this: <img data-rsp-img=“your_image_here.jpg”>
imagePathAttribute	string	'rsp-path'	'custom-path'	This is the data attribute with will contain paths for each image that wishes to override the global imagePath.
imagePath	string	''	'images/'	This path will be prefixed onto every source image. If a data-rsp-path is present, imagePath will be ignored.
disableRetina	boolean	true	false	If you wish to enable retina suffixes (for instance, if you are generating retina alternatives), set this to false.
retinaSuffix	string	'_x2'	'@2'	retinaSuffix determines the suffix that will be attached when disableRetina is false, and users are accessing your site on a retina-friendly device.

Minimizing Requests/Bandwidth vs. JavaScript support

TBD

Advanced

Loading images based on class matching

var rsp = new Respeto();
rsp.load('small', {
	match: '.load-me'
});

Before running rsp.load():

<img class="load-me" data-rsp-img="dog.jpg">
<img class="load-me" data-rsp-img="fish.jpg">
<img data-rsp-img="cat.jpg">
<img data-rsp-img="monkey.jpg">
<img class="load-me" data-rsp-img="elephant.jpg">
<img data-rsp-img="giraffe.jpg">

After running rsp.load():

<img src="dog_small.jpg" class="load-me" data-rsp-img="dog.jpg"> <!-- match! -->
<img src="fish_small.jpg" class="load-me" data-rsp-img="fish.jpg"> <!-- match! -->
<img data-rsp-img="cat.jpg">
<img data-rsp-img="monkey.jpg">
<img src="elephant_small.jpg" class="load-me" data-rsp-img="elephant.jpg"> <!-- match! -->
<img data-rsp-img="giraffe.jpg">
	

Contextual image-loading

var rsp = new Respeto();

// load our "large" images inside of elements with id of 'page-1'
rsp.load('large', {
	context: '#page-1'
});

Before running load():

<section id="#page-1">
	<img data-rsp-img="dog.jpg">
	<img data-rsp-img="fish.jpg">
</section>

<section id="#page-2">
	<img data-rsp-img="cat.jpg">
	<img data-rsp-img="monkey.jpg">
</section>

<section id="#page-3">
	<img data-rsp-img="elephant.jpg">
	<img data-rsp-img="giraffe.jpg">
</section>

After running load():

<section id="#page-1">
	<img src="dog_large.jpg" data-rsp-img="dog.jpg"> <!-- match! -->
	<img src="fish_large.jpg" data-rsp-img="fish.jpg"> <!-- match! -->
</section>

<section id="#page-2">
	<img data-rsp-img="cat.jpg">
	<img data-rsp-img="monkey.jpg">
</section>

<section id="#page-3">
	<img data-rsp-img="elephant.jpg">
	<img data-rsp-img="giraffe.jpg">
</section>