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:

a source images directory
image workflow tools (in this case Grunt and ImageMagick)
a destination directory
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>

pkarl/respeto

Respeto

TODO

Usage

A Responsive Image Workflow

1 - Source image management

2 - Image Workflow Tools

3 - Destination image management

4 - Respeto implementation

API

new Respeto(options)

Usage

options

Minimizing Requests/Bandwidth vs. JavaScript support

Advanced

Loading images based on class matching

Before running rsp.load():

After running rsp.load():

Contextual image-loading

Before running load():

After running load():

Before running `rsp.load()`:

After running `rsp.load()`:

Before running `load()`:

After running `load()`: