Demo
To see properly this plugin in action you need 2 different devices to see the difference between a common or high res display.
This plugin is useful to auto load a double size image for high resolution displays. Simply it search for an img with a specific (that you can choose) suffix to use in case of Retina or other high density displays.
To see properly this plugin in action you need 2 different devices to see the difference between a common or high res display.
To use jQueryHDimg first include jQuery library and plugin inside your document.
Best pratic is better to include the files before the closure body tag (</body>) but is also good inside the <head>
...
<script src="your-libs-path/jquery.min.js"></script>
<script src="your-plugin-path/jquery.HDimg.js"></script>
</body>
The second thing to do is prepare all images you need to affect by the plugin.
Rename your original image as you want, then make the double image and rename it with a specific suffix as @2x.
A sample of image renaming can be img-01.jpg for the original image and img-01@2x.jpg for high density display image.
WARNING: both images must be placed on the same directory!
You can choose the suffix you want, but if you customize the suffix, you must declare it with the specific plugin option.
To learn more about custom suffix usage see the proper chapter below.
If you use the default options, you don't need to do anything in you html code, simply add the images as usual
<img id="image1" src="img/img.jpg" alt="Image Title">
To obtain a correct image substitution (both images, normal and double, with the same sizes), some css coding is needed.
To do this you must assign an univoc ID to each image and use it for specify sizes by css rules.
On the example above I used id="image1" so the css rule can be something like this:
#image1 {width: 100px; height: 100px;}
If you have more images with the same size, you can use a class instead many different ID.
It's possible to use this plugin for a single image or for all images inside a dom element.
On exsample below each image inside the div with attribute id="#retina" will be affected by the plugin.
$("#retina img").HDimg();
On exsample below all images inside the document will be affected by the plugin.
$("img").HDimg();
This plugin haven't many option that make you crazy to use it.
The dafault options are sufficient to make a great job, but if you need some different settings you can use the following custom options
Option Name |
Option Allowed Values |
| imgReplacement | boolean - default: true - accepted: true/false (option added from version 1.1.3) |
| imgAssignment | boolean - default: false - accepted: true/false |
| densityLevel | int - default: 1.25 - accepted: 1.25 - 1.3 - 1.5 - 2 |
| imgSuffix | string - default: "@2x" - accepted: any string you want |
| autoResize | boolean - default: false - accepted: false, true This property works only if imgReplacement option has value true |
| addClass | boolean/string - default: false - accepted: false, true and any string you want as class name. |
| devForce | boolean - default: false - accepted: false/true (option added from version 1.1.2) |
The default way is Replacement technique that works leaving the image unreplaced in case of common display and replacing it only if necessary.
This technique, in case of high density display, force the dom to load before the original image and then the double size one.
Replacement allow you (if you want) to use the auto resizing of the images, without any css rule. For do this use the option "autoResize: true" (see below the usage).
Replacement is the dafault technique so you don't need to specify it on plugin options
Because this plugin is thinked as "mobile first" we provide the Assignment technique, that works charging only the image that is needed for the current scenario and not before the original image (with bandwidth consuming) and then replacing it, if is needed by the high resolution display.
For this reason you must put the original img url on a data attribute and not inside src attribute.
The plugin executes a media query and then assigns the right image to the src attribute.
This method needs the css size rules.
If you use the image assigment (see below the difference) place inside the page all the img tags you need but leaving empty the src attribute, and specify the original (not duoble) image url with the data attribute data-src="".
<img id="image1" data-src="img/img.jpg" src="" alt="Image Title">
WARNING: if you choose the assignment technique instead the default replace technique, remember that this cause a W3C validation error for the empty "src" attribute.
Assigment technique can be declared with the option imgAssignment: true or with the option imgReplacement: false
$("#demo > img").HDimg({
imgAssignment: true
});
is equivalent of
$("#demo > img").HDimg({
imgReplacement: false
});
This option allow you to specify a particular density to start the image sunstitution.
The default value is 1.25 but you can specify alternative values such as 1.3 - 1.5 and 2
See the example below:
$("#demo > img").HDimg({
densityLevel: 1.25
});
The default suffix for the double size image is @2x
but you can customize this parameter with the option imgSuffix
You can use the suffix you want.
In the example below will be used the prefix _double. Using this prefix, the double size image must be renamed in this way: imgname_double.jpg
$("#demo > img").HDimg({
imgSuffix: "_double"
});
By the option addClass it's possible to add a particular class to the double size img
The option accept boolean value (true and false) or a string used as class name. If you use true value instead a class name, will be used the default class hd-image
$("#demo > img").HDimg({
addClass: "doubleImage"
});
By the option autoResize it's possible to resize the image without any css rule.
This option is available only if imgReplacement is turned on true value.
This option accept only boolean value (true and false). Default value is false.
$("#demo > img").HDimg({
imgReplacement: true,
autoResize: true
});
Option added from version 1.1.2
By the option devForce it's possible to force the plugin to switch images to hd version.
This option is useful during site developing to see how your site appears once the images are changed by plugin.
This option accept only boolean value (true and false). Default value is false.
$("#demo > img").HDimg({
devForce: true
});
As you can see, the following 3 images are loaded as 2x also in non hd displays
To provide old ie version compatibility it's necessary to use two different polyfills:
# respond.js
# matchmedia.polyfill.js