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.

Ideally, we want a disposition of the images without cropping them. But, to dispose all the images, minimizing their cropping parts, can be reduced to the “Knapsack Problem”, known to be an NP-complete problem. We can’t do miracles, but we can try to minimize the cropping parts of the images. Furthermore, we need a good appealing disposition: we need that all the images of a row to have the same height.

See it in action

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.

San Vito Lo CapoPonte del DiavoloThe SpringCat firmnessInto The SeaFirst Sunset of the Year in BolognaBologna's T-DayAlone in the SnowWhat's your destination?Just in a dream PlaceIl Capo at PalermoEriceA painter in San VitoPescherie VecchieA question of perspective

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

How to use the plugin

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>

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 row height. If you have an height of 70px, the algorithm first resizes the images to have this height:

If the row is full, the algorithm removes the images that can’t stay in the same row. Then, it resizes the other images fill the entire row width.
This changes the row height, or cuts the images if you have configured the plugin to have a fixed height.┬áNotice that, despite you don’t have the “fixed height” option, an image can be cut a little to have the same height of the other images in the same row.
All the images that can’t stay in the same row are placed in the next row. This algorithm examines 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.

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.

63 comments on “Justified Gallery

  1. Thanks for making this great plugin!

    Is there a callback that would run when the page is resized and rows are remade rather than just when the plugin is initially loaded?

  2. Hi Miro,

    Awesome Plugin. I’m looking to use this on a local restaurant website. What would you require/want for attribution? Is the source code comment enough or do want a link on the website itself?

    Thanks!
    Jordan

    • Yes, you can use it wherever you want. I only require that my names remain in the sources, only if you want you can put a link to the project. I’m searching for more informations to change the license to be more clear.

  3. Hi… miro.mannino, thanx for amazing plugin…can i use this plugin with dynamic data(images) which is stored in database…if yes…. then please write some demo……..

    • yes, you can get the images from everywhere! An example? Search examples to how create galleries, not necessary related to my plugin. Another example is the Flickr Photostream plugin that uses Justified gallery.

Leave a Reply

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

*