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.

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>
You can use also use div instead of anchors a if you don’t need links on photos.

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.
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.
captionsAnimationDuration500Caption fadeIn/fadeOut duration.
imagesAnimationDuration300Image fadeIn duration.
captionsVisibleOpacity0.7Final opacity for captions.

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.

80 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.

  4. Hello, further to my previous comment I have managed to get the jquery plugin to work with WordPress galleries. I still can’t get infinite scroll to play well with it (this is probably due to my limited programming knowledge), but if it is loading up a finite number of images it seems to work very well for me. For anyone curious, I posted the function I use to achieve this over at Stack Overflow: http://stackoverflow.com/questions/19802157/change-wordpress-default-gallery-output/23386372#23386372

    Thank you for the plugin, Miro!

  5. Hi There,

    Thanks for this amazing plugin! Works like a charm.

    Hope you can help me with couple of quick questions;

    One, I’m working with the swipebox and am having trouble adding a hyper link to a details page either from the top – title caption or the bottom action caption

    Two, how can I permanently keep the two (top and bottom) captions visible?

    Again, excellent work and good luck on your future endeavours.

    Thanks

    • You can build your own caption on top the images (just jQuery appendTo), disabling the justified gallery captions.

  6. May seem like an odd question, but I only need the resizing / row distribution features. I don’t need a linked image. Is there a way to make this work with a simple unordered list or images (or div tags) instead of anchor tags? I can just kill the links with CSS/JS but that feels hack-y.

  7. Excellent work, very useful. However, for my application the Flickr Suffix method does not map well – I have different sized images, but they have totally different names so changing a suffix does not select another size.

    I’d suggest a replacable function that selects the sized image given the suffix code – the built-in being the Flickr-style, but I could overrule that and write my own to “new image src-getter” to use for example HTML5 data attributes for my different url:s ( )

  8. Hi, awesome grid! Is there a way to align images vertically? So all of them have the same width and different height.
    Thanks!

  9. Hello, congratulations for the plugin! Is there a way to attach a filter to the images? So as to divide them into categories.
    Thanks

    • You can reproduce any behavior that you want. With a “jg.complete” (or something else) event listener, you can modify the gallery as you want (I do the same to build a Colorbox gallery).

  10. Hi Miro,

    Thanks for this great plug in, i’ve been using it for a while, but i was wondering if you can help me to add facebook share button below the title when its thumbnails mode, and when its zoom mode.
    Thanks, im looking forward for your reply.

    Regards

Leave a Reply

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

*