jPictura is a simple jQuery plugin for responsive alignment of images.
Table of contents
Quick start
Installation
- Download the latest release.
- Install with npm:
npm install jpictura.
The following two files have to be used in your solution:
jpictura/
└── dist/
├── css/
│ └── jpictura.min.css
└── jpictura.min.js
Setup
Include jpictura.min.css inside of your head tag and jpictura.min.js just before the closing body tag. Be sure to include jQuery before jpictura.min.js.
<head>
<title>Your Intergalactic Website</title>
<link rel="stylesheet" href="jpictura/dist/css/jpictura.min.css">
</head>
<body>
<script src="http://code.jquery.com/jquery-2.2.0.min.js"></script>
<script src="jpictura/dist/jpictura.min.js"></script>
</body>Create a target gallery element with divs inside, one for each image. jPictura targets div tags with class item (can be changed in the options) inside of the selected element.
<div id="my-gallery">
<div class="item"><img src="foo.png" /></div>
<div class="item"><img src="bar.png" /></div>
</div>Initialization
Simply select the gallery element and call the jpictura method. It is that simple!
$(document).ready(function(){
$("#my-gallery").jpictura();
});Options
Customize your gallery by passing an options object as a single parameter to the jpictura method.
$(document).ready(function(){
$("#my-gallery").jpictura({ layout: { itemSpacing: 5, justifyLastRow: false } });
});The complete options object looks like this:
var options = {
selectors: {
item: '.item',
image: 'img'
},
classes: {
container: nameInLowerCase,
item: nameInLowerCase + '-item',
image: nameInLowerCase + '-image',
lastRow: nameInLowerCase + '-last-row',
firstInRow: nameInLowerCase + '-first-in-row',
lastInRow: nameInLowerCase + '-last-in-row',
invisible: nameInLowerCase + '-invisible',
hidden: nameInLowerCase + '-hidden',
offContentFlow: nameInLowerCase + '-off-content-flow'
},
layout: {
rowPadding: 0,
applyRowPadding: true,
itemSpacing: 5,
applyItemSpacing: true,
idealRowHeight: 180,
minWidthHeightRatio: 1 / 3,
maxWidthHeightRatio: 3,
stretchImages: true,
allowCropping: true,
croppingEpsilon: 3,
centerImages: true,
justifyLastRow: false
},
effects: {
fadeInItems: false
},
responsive: {
enabled: true,
onWindowWidthResize: true,
onContainerWidthResize: true,
containerResizeInterval: 50,
debounce: 200
},
waitForImages: true,
heightCalculator: jpictura.heightCalculator,
algorithm: {
epsilon: 0.01,
maxIterationCount: 50
},
debug: false
};The options are described in details in the following sections.
selectors.item
A jQuery selector that is used to locate the gallery items within the container.
<div id="my-gallery">
<a href=""><img src="foo.png" /></a>
<a href=""><img src="bar.png" /></a>
</div>
$(document).ready(function(){
$("#my-gallery").jpictura({ selectors: { item: 'a' } });
});selectors.image
A jQuery selector that is used to locate the images within the gallery items.
<div id="my-gallery">
<div class="item"><img src="ANOTHER IMAGE" /><img class="chosen-image" src="foo.png" /></div>
<div class="item"><img src="ANOTHER IMAGE" /><img class="chosen-image" src="bar.png" /></div>
</div>
$(document).ready(function(){
$("#my-gallery").jpictura({ selectors: { image: '.chosen-image' } });
});classes
CSS classes that are automatically applied by the plugin to specific elements.
| Option | Description |
|---|---|
classes.container |
CSS class applied to the gallery container (the element which the jpictura was applied to). |
classes.item |
CSS class applied to the gallery items. |
classes.image |
CSS class applied to the images. |
classes.lastRow |
CSS class applied to the gallery items in the last row. |
classes.firstInRow |
CSS class applied to first gallery item in each row. |
classes.lastInRow |
CSS class applied to last gallery item in each row. |
layout.rowPadding
Specifies the amount of blank space at the start and at the end of each row.
$(document).ready(function(){
$("#my-gallery").jpictura({ layout: { rowPadding: 5 } });
});The row padding is achieved by applying margin to the gallery items. The property is closely related to property layout.applyRowPadding. If layout.applyRowPadding was false, the margin would not be applied. However the width/height of the gallery items would be still calculated as if the margin was there. This advanced set up allows you to write custom CSS for proper image alignment - e.g. using flex box.
layout.itemSpacing
Specifies the amount of blank space between the gallery items.
$(document).ready(function(){
$("#my-gallery").jpictura({ layout: { itemSpacing: 5 } });
});The spacing is achieved by applying margin to the gallery items. The property is closely related to property layout.applyItemSpacing. If layout.applyItemSpacing was false, the margin would not be applied. However the width/height of the gallery items would be still calculated as if the margin was there. This advanced set up allows you to write custom CSS for proper image alignment - e.g. using flex box.
layout.idealRowHeight
The desired row height. The application will try to arrange the gallery item so the heights of the rows are as close as possible to the layout.idealRowHeight value.
$(document).ready(function(){
$("#my-gallery").jpictura({ layout: { idealRowHeight: 80 } });
});layout.stretchImages
Whether the images should be stretched to fully fill the space of the respective gallery item or not. However, stretching an image beyond its actual width/height decreases the image quality.
Without stretching
$(document).ready(function(){
$("#my-gallery").jpictura({ layout: { stretchImages: false } });
});With stretching
$(document).ready(function(){
$("#my-gallery").jpictura({ layout: { stretchImages: true } });
});layout.allowCropping
Images whose aspect ratio is beyond the specified limits (smaller than layout.minWidthHeightRatio or bigger than layout.maxWidthHeightRatio) might not fit their gallery items very well - in other words, the aspect ratio of the calculated gallery item might differ from the aspect ratio of the contained image. Therefore if the image is stretched to fill in the entire space of its gallery item, the image will be cropped - either at the top/bottom (the image is too high) or at the sides (the image is too wide). To prevent cropping of images with non-standard aspect ratios, set the property layout.allowCropping to false.
With cropping
$(document).ready(function () {
$("#my-gallery").jpictura({ layout: { stretchImages: true, allowCropping: true } });
});Without cropping
$(document).ready(function () {
$("#my-gallery").jpictura({ layout: { stretchImages: true, allowCropping: false } });
});💡 You may notice that the rectangular red image was stretched to fill in the given space because its aspect ratio is within limits and no cropping occured. The image with water polo players on the other hand was not stretched due to the fact it would be cropped in such a case.
layout.centerImages
Whether the images should be centered within the given space defined by their gallery items or not.
$(document).ready(function () {
$("#my-gallery").jpictura({ layout: { centerImages: false } });
});layout.justifyLastRow
Whether the images in the last row should be justified (i.e. - stretched to take the full width of the row or not). If the property is set to false, the images in the last row may still take the full width of the row if they are wide enough, but they will not be forced to do so if they are not wide enough.
Without justification
$(document).ready(function () {
$("#my-gallery").jpictura({ layout: { justifyLastRow: false } });
});With justification
$(document).ready(function () {
$("#my-gallery").jpictura({ layout: { justifyLastRow: true } });
});effects.fadeInItems
If true, the gallery items will smoothly fade in once they are loaded - instead of simple appearing on the screen.
$(document).ready(function () {
$("#my-gallery").jpictura({ effects: { fadeInItems: true } });
});responsive.enabled
If true, the gallery will behave responsively. The responsive behavior is further defined by the responsive. settings below.
responsive.onWindowWidthResize
If true, the gallery will adapt itself to the actual window width whenever the window width is changed.
This option has effect only if responsive.enabled is set to true.
responsive.onContainerWidthResize
If true, the gallery will adapt itself to the actual width of its container whenever the container's width is changed.
This feature may hinder the performance a bit, respectively increase the CPU consumption.
This option has effect only if responsive.enabled is set to true.
responsive.containerResizeInterval
Interval (in milliseconds) that specifies how often is the gallery's container width checked.
This option has effect only if responsive.onContainerWidthResize is set to true.
responsive.debounce
Specifies the debounce interval (in milliseconds) for the gallery redraw calls. This means that the gallery will not be redrawn while its container/window width is being changed. It will be redrawn only after the specified amount of millisecond since the container/window width has stopped being changed. You can read more about the debounce pattern on the CSS tricks website.
This option has effect only if responsive.enabled is set to true.
waitForImages
If true, the plugin waits until all images are loaded and only then performs the calculations and displays the gallery. The images cannot be processed any sooner because the knowledge of their nutural widths and heights is crucial.
However it is possible to speed up loading of the gallery if the image dimensions are known. In this case it is possible to apply data parameters on the gallery item HTML tags and specify the image dimensions (in pixels) so the plugin does not have to wait for the images and can start processing the gallery as soon as DOM is ready.
<div id="my-gallery">
<div class="item" data-jpictura-width="300" data-jpictura-height="200"><img src="foo.png" /></div>
<div class="item" data-jpictura-width="200" data-jpictura-height="300"><img src="bar.png" /></div>
</div>
$(document).ready(function () {
$("#my-gallery").jpictura({ waitForImages: false });
});heightCalculator
This property allows you to supply your own algorthim which is supposed to calculate row height for the given row (array of gallery items which should appear in a single row).
algorithm
Options used by the heightCalculator algorithm.
debug
If true, the plugin will log useful messages to the console.