The Justified Gallery module arranges images in evenly aligned rows as a block. Each row has the same height, but the images inside a row can have different widths. Because every image keeps its original shape, landscape and portrait photos sit together without being cropped, and each row is stretched so it fills the full width of the page. This is the layout style you see on photo sites like Flickr or Google Photos.

The Justified Gallery API is the set of options, methods and events you can use from JavaScript to build and control a gallery. In the J1 Template you normally do not call this API yourself. Instead, you write a few YAML settings and the J1 Gallery adapter turns them into the correct JavaScript for every gallery on the page. Reading this manual is still useful, because the options you set in YAML use the same names as the API options described on the following pages.

In J1, a gallery is configured with three YAML files. They are merged together in the order shown below, and later files override earlier ones (this is called the inheritance chain). A key you leave out of a higher file is simply inherited from the file above it:

Every gallery has a type that decides what it shows:

When the gallery’s HTML is on the page, Justified Gallery is started by calling justifiedGallery() on the gallery element and passing the options you want:

You can also react to the moment the layout is finished by listening for the jg.complete event:

This page shows how Justified Gallery works with plain HTML and a small <script>. It is useful for understanding the options, even though in a J1 site you do not write this code by hand.

Here we have a div, with the id basicExample, that holds a list of links pointing to full-size images. Inside each link there is a thumbnail. When Justified Gallery runs, the thumbnails are resized so they fill the whole row (this filling is called justification).

The most important option of the module is rowHeight (see Properties). Say you set a height of 160px — the algorithm then tries to build rows about that tall:

Justification may resize the images a little, so the real row height can end up slightly different from 160px. In other words, rowHeight is your preferred height (a lower bound). You can use the maxRowHeight option to put an upper limit on the row height; but remember that this option can crop images if they would have to be bigger to be justified.

The algorithm builds one row after another until it reaches the last one. That last row may not have enough images to fill the whole width. With the lastRow option you decide what happens: leave a blank space, justify the images anyway, or hide the last row if there would be too much empty space.

The next example uses smaller images (rowHeight: 70), does not justify the last row (lastRow: 'nojustify'), and uses a margin of 3px between images (margins: 3):

In a J1 site you would write the same settings as YAML instead. Note that in J1 the spacing key is called gutters (the adapter maps it to the library’s margins option for you):

Properties (also called options) control how a gallery is built and how it behaves. You set them once, when the gallery is created. In J1 you write them as YAML under the gallery_options key of a gallery in gallery_control.yml; the adapter passes them on to Justified Gallery.

The table below lists the options you will use most often.

Commands let you control a gallery after it has been created. You call a command by passing its name (a string) to justifiedGallery() on the same element:

Events let your own code react to things that happen inside the gallery, such as the layout being finished. You listen for an event with jQuery’s .on() on the gallery element: