Imadaem — JS Daemon for Responsive Images
JavaScript Ruby CSS Shell
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
js
script
site
test
.gitignore
.gitmodules
.travis.yml
CONTRIBUTING.markdown
Gemfile
LICENSE
README.markdown
Rakefile

README.markdown

Imadaem

Build Status

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:

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.

© 2014 Anatol Broder