Justified Gallery

Category: JQuery plugin
Release Date: 10/2012
Technologies: Javascript, CSS, HTML, JQuery
Download from: Github
 

This is a JQuery plugin that allows you to create an high quality justified gallery of images. Fill all the spaces!
A common problem, for people who create sites, is to create an elegant image gallery that manages the various sizes of images. Flickr and Google+ manage this situation in an excellent way, the purpose of this plugin is to give you the power of these solutions, with a new fast algorithm.

Demo

This is an example of use of this plugin. As you can see, the photos becomes from Flickr, imported with the Flickr Photostream wordpress plugin. Try to resize the page, see how it reloads the images and adapt the layout.

More examples can be found in the zip file, downloadable from Github.

How to use

The plugin accepts a standard format for a gallery: a series of links with a thumbnail inside, and where each link leads to the original image.

<div id="mygallery" >
  <a href="path/to/myimage1_original.jpg">
    <img alt="Title 1" src="path/to/myimage1_t.jpg"/>
  </a>
  <a href="path/to/myimage2_original.jpg">
    <img alt="Title 2" src="path/to/myimage2_t.jpg"/>
  </a>
  <!-- other images... -->
</div>
If you don’t need links on photos, you can also use div instead of anchors a.

Files to include

The plugin needs JQuery. Then you can include the plugin files as the following:

<link rel="stylesheet" href="css/justifiedGallery.css" />
<script src="js/jquery.justifiedGallery.js"></script>

Just a Call

Now, you only need to call the plugin that will justify all the images, with the default options.
$("#mygallery").justifiedGallery();

Important configurations

An important configuration of the plugin is the rowHeight. Consider that you have set an height of 160px; the algorithm tries to build rows with that height:

However, the justification may resize the images, and, as a consequence, the row height may be a little bit different than 160px. This means that the row height is intended as your preferred height, and it is not an exact measure. If you want that the row height remains strictly fixed, you can use the fixedHeight option. However, this option will crop the images a little bit to make sure that the row height doesn’t change.

This algorithm builds each row until it reaches the last. But, this last row may not have enough images to fill the entire width. In this case you can decide (with the lastRow option) to leave a blank space, to justify the images, or to hide the last row if there is too much blank space. But, note that, if you decide to justify the last row, and you don’t have the fixed height option, the last images can be much larger than the others (you can use the maxRowHeight option to control this behavior).

High quality galleries

The plugin is based on the concept that you have various thumbnails for a single image. In fact, you can configure the gallery to show your images in different sizes, and also the plugin may decide to resize some images to fill the remaining empty space. Hence, the plugin needs thumbnails with different sizes to guarantee always an high quality; we don’t want that small thumbnails are resized to be very big (low quality) and we also don’t want that large thumbnails are resized to be very small (low performance).

In practice, you must resize your images in the upload phase (e.g. WordPress and Flickr work in this way). The plugin uses, by default, the Flickr Size Suffixes:

"_t": thumbnail, 100px on longest side
"_m": small, 240px on longest side
"_n": small, 320px on longest side
"" : medium, 500px on longest side
"_z": medium 640, 640px on longest side
"_c": medium 800, 800px on longest side
"_b": large, 1024px on longest side

With this settings you need to have 7 thumbnails for a single images: "myimage_t.jpg", "myimage_m.jpg", and so on.

As we have seen, a gallery is a container with a list of links. Each link points to the original image, and contains a thumbnail. The Justified Gallery plugin, when it is called, needs to know the with and height of each thumbnail: it needs to download them the at least once. To start, it downloads the thumbnails that are specified in the HTML (e.g."path/to/myimage1_t.jpg"). Then, if the plugin needs a bigger thumbnail (e.g. the one with the "_m" suffix), it downloads the bigger thumbnail changing the URL (e.g."path/to/myimage1_m.jpg").

If you don’t want to provide all the sizes, you can configure the settings sizeRangeSuffixes. For example, to have only one thumbnail for each image, with the suffix '_t', you can set the plugin to have '_t' for all the suffixes.

Options

optiondefault valuedescription
rowHeight120The approximately height of rows.
maxRowHeight0Negative value to haven’t limits. Zero to have a limit of 1.5 * rowHeight
sizeRangeSuffixes {'lt100':'_t',
'lt240':'_m',
'lt320':'_n',
'lt500':'',
'lt640':'_z',
'lt1024':'_b'}
Describes the suffix for each size range. By default the Flickr suffixes are used.
lastRow'nojustify'Decide if you want to justify the last row (i.e. 'justify') or not (i.e. 'nojustify'), or to hide the row if it can’t be justified (i.e. 'hide')
fixedHeightfalseDecide if you want to have a fixed height. This mean that all the rows will be exactly with the specified rowHeight.
captionstrueDecide if you want to show the caption or not, that appears when your mouse is over the image.
margins1Decide the margins between the images
randomizefalseAutomatically randomize or not the order of photos.
extension/.[^.]+$/Specify the extension for the images with a regex. Is used to reconstruct the filename of the images, change it if you need. For example /.jpg$/ is to detect only the “.jpg” extension and no more.
refreshTime250The time that the plugin waits before checking the page size, and if it is changed it recreates the gallery layout
relTo rewrite all the links rel attribute with the specified value. For example can be ‘gallery1′, and is usually used to create gallery group for the lightbox (e.g. Colorbox)
targetTo rewrite all the links target attribute with the specified value. For example, if you don’t use a lightbox, specifying '_blank', all the images will be opened to another page.
justifyThreshold0.35If available space / row width < 0.35 the last row is justified, without considering the lastRow setting.
cssAnimationfalseUse or not css animations. Using css animations you can change the behavior changing the justified gallery CSS file, or rewriting that rules.
imagesAnimationDuration300Image fadeIn duration.
captionSettings { animationDuration: 500,
  visibleOpacity: 0.7,
  nonVisibleOpacity: 0.0 }
Caption settings

Events

EventDescription
jg.completeWhen the algorithm finished to create the gallery layout.
jg.resizeWhen the algorithm finished to resize the gallery.
jg.rowflushWhen the a new row is ready.

Example

$("#callbacktest").justifiedGallery().on('jg.complete', function (e) {
    alert('on complete');
});

Choosing the right initial thumbnails (advanced topic)

How we can choose the initial thumbnails to put in the HTML? It’s simple: if we want a small gallery, we choose a small rowHeight (e.g. 70), and we also choose to put small thumbnails in the HTML (e.g. the ones with the suffix ‘_t’, with a longest side less than 100px).
Choosing the right initial thumbnails is an advantage, because the plugin probably will not load other thumbnails: the thumbnails you put in the HTML code are probably the ones that are used after the justification. This will result in an huge performance improvement: low bandwidth, low memory and speed.
You can choose which thumbnails to put in the HTML code, reasoning as this pseudocode (with the assumption that the images has an aspect ratio of 4:3):

if rowHeight <= 75:
  #thumbnail sizes must be with longest side = 100
  #suffix to put in HTML is '_t' (considering the default suffixes)
elif rowHeight <= 180:
  #thumbnail sizes must be with longest side = 240
  #suffix to put in HTML is '_m' (considering the default suffixes)
elif rowHeight <= 240:
  #thumbnail sizes must be with longest side = 320
  #suffix to put in HTML is '_n' (considering the default suffixes)
#...

Help the project!

This is an open source project, and I don’t earn anything from it. You can help the project to grow in various way:

  • Talking about it (in blogs, social network, …)
  • Writing your personal features, and making a pull request, as someone did. If you want to do this, go to the github project page.
  • Donate! I will be more motivated to implement your requested features.

Any Issue?

If you have any issue, please send me your question to the github issues page. In this page you can find your answer. If you don’t have a github account, and if you don’t want, write a comment in this page or write me an email.

86 comments on “Justified Gallery

  1. Hi, This library is awesome!
    Do you know with which library can I use Justified Gallery to make pictures B&W on the page? I tries with jQuery.BlackAndWhite but it does not seem to work fine. Thanks a lot!

Leave a Reply

Your email address will not be published. Required fields are marked *

*