# Adaptive-Images Instructions

## Basic instructions

Copy `adaptive-images.php` and `.htaccess` into the root directory of your site. If you already have a htaccess file DO NOT OVERWRITE IT, skip down to the advanced instructions.

Create a directory called `ai-cache` in the root of your site and give it write permissions (CHMOD 777).

Copy the following Javascript into the <head> of your site. It MUST go in the head because it needs to work before the page has finished loading, and before any images have been requested.

    <script>document.cookie='resolution='+Math.max(screen.width,screen.height)+'; path=/';</script>

That's it, you're done.

NOTE: you do not need the `ai-cookie.php` file unless you are using the alternate method of detecting the users screen size. So delete it if you like, no one likes mess.

## You already have a .htaccess file

I strongly advise you to duplicate that file so you can revert to it if things go pear-shaped.

Open your existing .htaccess file and edit the contents. You'll need to look and see if there is a section that begins with the following:

`<IfModule mod_rewrite.c>`

If there is, then you need to add the following lines into that block:

    # Adaptive-Images -----------------------------------------------------------------------------------

    # Add any directories you wish to omit from the Adaptive-Images process on a new line, as follows:
    # RewriteCond %{REQUEST_URI} !some-directory
    # RewriteCond %{REQUEST_URI} !another-directory

    RewriteCond %{REQUEST_URI} !assets

    # Send any GIF, JPG, or PNG request that IS NOT stored inside one of the above directories
    # to adaptive-images.php so we can select appropriately sized versions
    RewriteRule \.(?:jpe?g|gif|png)$ adaptive-images.php

    # END Adaptive-Images -------------------------------------------------------------------------------

If you don't have a code block then simply copy and paste the following into your file instead:

    <IfModule mod_rewrite.c>
      Options +FollowSymlinks
      RewriteEngine On

      # Adaptive-Images -----------------------------------------------------------------------------------

      # Add any directories you wish to omit from the Adaptive-Images process on a new line, as follows:
      # RewriteCond %{REQUEST_URI} !some-directory
      # RewriteCond %{REQUEST_URI} !another-directory

      RewriteCond %{REQUEST_URI} !assets

      # Send any GIF, JPG, or PNG request that IS NOT stored inside one of the above directories
      # to adaptive-images.php so we can select appropriately sized versions
      RewriteRule \.(?:jpe?g|gif|png)$ adaptive-images.php

      # END Adaptive-Images -------------------------------------------------------------------------------
    </IfModule>

## Additional settings and configuration

### .htaccess

Instructions are in the file as comments (any line that starts with a # is a comment, and doesn't actually do anything)

Follow the instructions inside that code to specify any directories you don't want to use Adaptive-Images on.

### PHP

You can now open the php file and have a play with the settings that are in the CONFIG area. By default it looks like this:

    /* CONFIG ----------------------------------------------------------------------------------------------------------- */

    $resolutions   = array(1382,992,768,480,320); // the resolution break-points to use (screen widths, in pixels)
    $cache_path    = "ai-cache"; // where to store the generated re-sized images. This folder must be writable.
    $jpg_quality   = 80; // the quality of any generated JPGs on a scale of 0 to 100
    $sharpen       = TRUE; // Shrinking images can blur details, perform a sharpen on re-scaled images?
    $watch_cache   = TRUE; // check that the responsive image isn't stale (ensures updated source images are re-cached)
    $browser_cache = 60*60*24*7; // How long the BROWSER cache should last (seconds, minutes, hours, days. 7days by default)
    $mobile_first  = TRUE; // If there's no cookie sends the mobile version (if FALSE, sends largest $resolutions version)

    /* END CONFIG ----------------------------------------------------------------------------------------------------------
    ------------------------ Don't edit anything after this line unless you know what you're doing -------------------------
    --------------------------------------------------------------------------------------------------------------------- */

`$resolutions` are the screen widths we'll work with. In the default it will store a re-sized image for large screens, normal screens, tablets, phones, and tiny phones.

In general, if you're using a responsive design in CSS, these breakpoints will be exactly the same as the ones you use in your media queries.

`$cache_path` If you don't like the cached images being written to that folder, you can put it somewhere else. Just put the path to the folder here and make sure you create it on the server.

`$sharpen` Will perform a subtle sharpening on the rescaled images. Usually this is fine, but you may want to turn it off if your server is very very busy.

`$watch_cache` If your server gets very busy it may help performance to turn this to FALSE. It will mean however that you will have to manually clear out the cache directory if you change a resource file

`$mobile_first` If set to TRUE and no cookie is set, Adaptive Images will send the mobile-resolution version of the requested image. If set to FALSE it will send the largest version set in the $resolutions array.

## Alternate method for those who can't rely on JavaScript

One of the weaknesses of the Adaptive Images process is its reliance on JavaScript to detect the visitors screen size, and set a cookie with that screen size inside it. The following is a solution for people who need the system to work without the use of JavaScript, but it does have a major caveat which is why this is not the default method, and why it is "unsupported" (I'm not going to troubleshoot problems you have with this method).

### The alternative method

Do not use the JavaScript as explained above, but instead, ABOVE your normal CSS, add the following into the head:

    <style>
     @media only screen and (max-device-width: 479px) {
       html { background-image:url(ai-cookie.php?maxwidth=479); } }
     @media only screen and (min-device-width: 480px) and (max-device-width: 767px) {
       html { background-image:url(ai-cookie.php?maxwidth=767); } }
     @media only screen and (min-device-width: 768px) and (max-device-width: 991px) {
       html { background-image:url(ai-cookie.php?maxwidth=991); } }
     @media only screen and (min-device-width: 992px) and (max-device-width: 1381px) {
       html { background-image:url(ai-cookie.php?maxwidth=1381); } }
     @media only screen and (min-device-width: 1382px) {
       html { background-image:url(ai-cookie.php?maxwidth=unknown); } }
    </style>

If you use this method you will need to ensure the widths here match those in your adaptive-images.php file, you will also need to have the `ai-cookie.php` file in the root of your website (no one else needs this file).

### The caveat

Using this method instead of the JS method makes it likely that on the very first visit to your site, the images sent to the visitor will be the original full-scale versions. However, ALL subsequent pages on your site will work properly. What that means is that, really, this solution is only viable if you've got $mobile_first set to FALSE. Otherwise, the majority of people who visit your site will experience images too small for their computer on the very first visit.

The reason is to do with how browsers load web pages. The first thing a browser does is load the HTML, in the order it's written - so for a normal AI install it loads the HTML and see's the embeded JavaScript and immediately executes that JavaScript - which writes the cookie. It then carries on loading the rest of the page in the order it finds it. Long story short - it means that when it finds an image tag and asks the server for it, it already has a cookie stored.

That's not likely to be the case if you use the CSS method. Because the CSS method relies on an external file - it has to ask the server for the "background-image", which is really just a bit of PHP to set a cookie. The problem is that when a browser loads external files like that, it doesn't stop loading the HTML, it carries on doing that at the same time as waiting for the external file. Which means that it can get to an image tag before the server has finished loading that PHP file. Which means no cookie is set. Which means that if $mobile_first is TRUE the mobile sized image is sent. But, only on that very first page load.