Imadaem

Imadaem is a javascript daemon for responsive images built with jQuery and Timthumb.

Imadaem replaces the placeholder image by the dedicated size image on every significant browser window event: load, resize, rotate. The website feels pretty fast. The visitor sees the low quality file nearly immediately and can start to interact with the site: scroll, zoom, etc. After the right resolution file is loaded, all the visitor maybe notices is the blurry image gets sharp.

The small overhead by loading two images instead of one is negligible. In return you get low latency user experience.

Visitors with no javascript still see everything as long as you provide sufficient placeholders.

Reason

Read what wise men think about the technique Imadaem provides:

Introducing LQIP — Low Quality Image Placeholders by Guy Podjarny, Chief Product Architect at Akamai
I ♥ Image Bytes by Steve Souders, Head Performance Engineer at Google
Cheating or Good Design? by Dmitry Fadeyev, Creator of Usaura

Examples

Visit one of following sites, resize your browser’s window and see what happens to images.

My personal website. My portrait’s height follows the header’s height. The portrait’s aspect ratio is limited to 2.
Geisterstunden — graffiti illustrated stories in German. All images are ratio-driven. The website is hosted on a cheap 1&1 hosting.

Setup

You can make things run in 15 minutes.

Dependencies

PHP library Timthumb (GPL license)
Javascript library jQuery (MIT license)

1. Timthumb

Download the timthumb.php file and put it on your server. Follow the official instruction. You can put your default options inside the timthumb-config.php file. For questions read the documentation inside of timthumb.php.

Make sure you can resize an image with your Timthumb installation before next steps.

2. jQuery

Download the jquery.js file and put it on your server.

3. Imadaem

Download the jquery.imadaem.js file and put it on your server.

4. Data in Images

Change the src attribute to a placeholder image, e. g. a low quality version.

The data-imadaem attribute holds the information about the original image. If you know the image’s URL only, you can put it as a string:

<img
    alt='Image'
    src='/path/to/image-placeholder.jpg'
    data-imadaem='/path/to/image-original.jpg'
/>

If you want Imadaem takes full effect, pass more information about the image as a JSON object. Example:

<img
    alt='Image'
    src='/path/to/image-placeholder.jpg'
    data-imadaem='{
        "url": "/path/to/image-original.jpg",
        "gravity": "tl",
        "heightGuide": "#guide"
    }'
/>

Learn about available data options in the API description.

Use double quotes inside of JSON object and single quotes outside of it for HTML.

5. Javascript in HTML

You must put the 3 files from the previous steps into the include definition of your HTML file. Pass a CSS selector, e. g. $("img[data-imadaem]") to Imadaem.

<script src='/path/to/jquery.js'></script>
<script src='/path/to/jquery.imadaem.js'></script>
<script>
    $(function() {
        $("img[data-imadaem]").imadaem({
            timthumbPath: "/path/to/timthumb.php"
        });
    });
</script>

Learn about available javascript options in the API description.

API

Javascript Options

Options you can pass to the initialization call.

Parameter	Meaning	Values	Default
`dataAttribute`	Data attribute that holds image’s options.	string	`imadaem`
`timthumbPath`	Path to Timthumb script	string	`/timthumb/timthumb.php`
`verticalRhythm`	Keep image height according to a vertical scale	`null`, `line-height`	`null`
`windowEvents`	One or more space-separated event types	string	`resize orientationchange`

Data Options

Options you can pass to an image by setting the data-imadaem attribute. Without it Imadaem will not affect the image. It must be a valid JSON object with the following properties:

<tr>
  <td><var>gravity</var></td>
  <td>Position of the most important piece</td>
  <td><code>l</code>, <code>r</code>,
    <code>t</code>, <code>tl</code>, <code>tr</code>,
    <code>b</code>, <code>bl</code>, <code>br</code>
  </td>
  <td><code>"gravity": "tr"</code></td>
</tr>

<tr>
  <td><var>ratio</var></td>
  <td>Aspect ratio</td>
  <td>number</td>
  <td><code>"ratio": "1.5"</code></td>
</tr>

<tr>
  <td><var>maxRatio</var></td>
  <td>Maximum aspect ratio. If <var>ratio</var> is set, <var>maxRatio</var> is ignored.</td>
  <td>number</td>
  <td><code>"maxRatio": "2.4"</code></td>
</tr>

<tr>
  <td><var>heightGuide</var></td>
  <td>Selector of elements to copy the height from</td>
  <td>string</td>
  <td><code>"heightGuide": "#header"</code></td>
</tr>

Property	Meaning	Values	Example
`url`	Path to the original	string	`"url": "/path/to/image.jpg"`

License

Released under the MIT license.

bernard-leech/imadaem