justifiedGallery - Documentation

Introduction

What is justifiedGallery?

justifiedGallery is a jQuery plugin designed to create beautiful, responsive, and easily customizable photo galleries. It arranges images in a justified layout, meaning images are sized and positioned to fill the available width evenly, resulting in a clean and visually appealing presentation. Unlike traditional grid layouts, justifiedGallery adapts dynamically to different screen sizes and window resolutions, maintaining its aesthetic appeal on desktops, tablets, and mobile devices. It’s ideal for showcasing images, portfolios, or any visual content where a balanced and responsive presentation is crucial.

Key Features

Getting Started

To use justifiedGallery, you’ll need to include jQuery and the justifiedGallery script in your HTML file. Download the plugin from [insert download link here] and include it as follows:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script> <!-- Or your jQuery source -->
<script src="justifiedGallery.min.js"></script>

Then, create a container element for your images. This container will be targeted by the plugin. Example:

<div id="myGallery">
  <img src="image1.jpg" alt="Image 1" />
  <img src="image2.jpg" alt="Image 2" />
  <img src="image3.jpg" alt="Image 3" />
  <!-- ... more images ... -->
</div>

Finally, initialize the plugin on your container using a simple jQuery call:

$("#myGallery").justifiedGallery();

This will create a justified gallery using the default settings. For more advanced customization, refer to the options section in this manual [link to options section].

Installation and Setup

Installing via npm or yarn

justifiedGallery is available via npm and yarn. To install it, use the following command in your terminal:

npm install justifiedgallery
# or
yarn add justifiedgallery

After installation, you can import it into your project using your preferred module bundler (e.g., Webpack, Parcel). For example, using ES6 modules:

import justifiedGallery from 'justifiedgallery';
import $ from 'jquery'; //Ensure you also import jQuery

$(document).ready(function() {
    $('#myGallery').justifiedGallery();
});

Remember to adjust the selector #myGallery to match the ID of your gallery container.

Including justifiedGallery in your project

If you prefer not to use a package manager, you can download the justifiedGallery.min.js file directly from [Insert download link here]. Include it in your HTML file after including jQuery:

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>  <!-- Or your jQuery source -->
<script src="justifiedGallery.min.js"></script>

Place this script tag just before the closing </body> tag, or within a $(document).ready() block to ensure jQuery is loaded before the plugin.

Basic HTML Structure

Your HTML should include a container element to hold your images. This container will be targeted by the justifiedGallery plugin. You can use any suitable HTML element, such as a <div> or a <ul>. Images within the container can be added using <img> tags. For example:

<div id="myGallery">
  <img src="image1.jpg" alt="Image 1">
  <img src="image2.jpg" alt="Image 2">
  <img src="image3.jpg" alt="Image 3">
  <img src="image4.jpg" alt="Image 4">
</div>

Remember to replace "image1.jpg", "image2.jpg", etc., with the actual paths to your images. The alt attributes are crucial for accessibility.

Configuration Options

justifiedGallery offers several options to customize the gallery’s appearance and behavior. These options are passed as a JavaScript object to the justifiedGallery() function.

Example usage with custom options:

$("#myGallery").justifiedGallery({
  rowHeight: 150,
  margins: 5,
  lastRow: 'nojustify',
  captions: true
});

Refer to the complete list of options and detailed explanations on [Insert link to detailed options documentation here]

Usage and API

Creating a justifiedGallery instance

The core functionality of justifiedGallery revolves around creating an instance of the gallery. This is done by calling the justifiedGallery() method on a jQuery selection containing the images you want to display. The method accepts an optional configuration object as its argument. For example:

$("#myGallery").justifiedGallery({
  rowHeight: 120,
  margins: 8
});

This code selects the element with the ID “myGallery” and initializes a justifiedGallery instance with a row height of 120 pixels and 8-pixel margins between images. If no options are provided, the plugin uses default settings. Remember to include jQuery and the justifiedGallery script in your HTML before using this code (as described in the Installation and Setup section).

Image Loading and Display

justifiedGallery handles the loading and display of images efficiently. By default (waitThumbnailsLoad: true), it waits for all images to load before calculating and applying the justified layout. This ensures the gallery renders correctly. If you have a large number of images, you might consider setting waitThumbnailsLoad to false to improve initial rendering speed. The layout will then readjust once the images are fully loaded. You can also manage image loading manually using the API methods (see below).

Responsive Design and Behavior

justifiedGallery is inherently responsive. It recalculates the justified layout whenever the browser window is resized. This ensures that the gallery always looks its best regardless of screen size. No additional code is required for responsive behavior – it’s built-in. The layout adjusts automatically to maintain an even distribution of images across the available width.

Customizing the Appearance

You can customize the appearance of your justifiedGallery using CSS. The plugin applies default classes to the gallery container and its elements, allowing you to style it precisely. You can target the following classes to control aspects of the layout:

You can also customize aspects of the appearance through configuration options like rowHeight, margins, border, and lastRow (as detailed in the Configuration Options section). Use these options to fine-tune spacing, row heights, and the handling of the last row.

API Methods and Events

justifiedGallery provides a few API methods for controlling and interacting with the gallery instance:

Events:

justifiedGallery triggers the following events:

Example of using the rejustify() method:

$("#myGallery").justifiedGallery();
// ... later, after adding new images ...
$("#myGallery").justifiedGallery('rejustify');

You can listen for events using jQuery’s .on() method:

$("#myGallery").on("jg.complete", function() {
  console.log("justifiedGallery rendering complete!");
});

Remember to consult the complete API documentation [Insert Link Here] for further details and examples.

Customization Options

Margin and Row Height Adjustment

The core visual aspect of justifiedGallery is controlled by rowHeight and margins. These options directly impact the spacing between images and the overall look.

Image Sizing and Scaling

justifiedGallery doesn’t offer direct control over individual image dimensions before justification. It calculates the optimal dimensions for each image to fit the justified layout based on the rowHeight and margins. However, you can influence the final displayed size by:

Caption and Title Handling

justifiedGallery supports captions. To enable captions, set the captions option to true during initialization:

$("#myGallery").justifiedGallery({ captions: true });

The plugin will then automatically use the alt attribute of each <img> tag as the caption. If you need more complex caption handling, you can add custom caption elements to your HTML alongside the images. You can also customize the caption appearance using the captionClass option which defaults to 'jgallery-caption'.

If you don’t want to use alt text for captions, ensure each image has a sibling element (e.g., a <p> tag) that will be treated as the caption. The sibling needs to be right after the <img> tag. The content of this sibling will be used as the caption.

Titles are not directly supported; the title attribute of the image is not used by the plugin. If title information is required, it should be handled separately, possibly by adding it to the custom caption.

CSS Customization

justifiedGallery uses a set of default CSS classes. You can fully customize the gallery’s appearance through CSS. The main class is .justified-gallery, which targets the gallery container. Images within the gallery are selected using .justified-gallery img. Captions are styled via the .jgallery-caption class (when captions are enabled). Use these classes to target elements and modify their properties like colors, fonts, margins, padding, and other visual aspects.

Accessibility Considerations

Advanced Usage

Working with Different Image Sizes

justifiedGallery is designed to handle images of varying sizes. It automatically calculates the optimal dimensions for each image to maintain the justified layout. However, significant differences in image aspect ratios can affect the visual balance. For best results:

Handling Large Image Sets

With large image sets, performance becomes crucial. To optimize performance:

Integration with Other Libraries

justifiedGallery is a jQuery plugin and is designed to work well with other jQuery libraries and plugins. Some potential integrations include:

Performance Optimization

Beyond the strategies mentioned above (lazy loading and handling large image sets), you can further optimize performance by:

Debugging and Troubleshooting

Examples and Use Cases

This example shows a simple implementation of justifiedGallery. It requires only including the necessary scripts (jQuery and justifiedGallery) and initializing the plugin on a container holding your images:

<!DOCTYPE html>
<html>
<head>
<title>justifiedGallery Example</title>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="justifiedGallery.min.js"></script> </head>
<body>

<div id="myGallery">
  <img src="image1.jpg" alt="Image 1">
  <img src="image2.jpg" alt="Image 2">
  <img src="image3.jpg" alt="Image 3">
  <img src="image4.jpg" alt="Image 4">
</div>

<script>
$(document).ready(function() {
  $("#myGallery").justifiedGallery();
});
</script>

</body>
</html>

Remember to replace "image1.jpg", "image2.jpg", etc., with the actual paths to your images.

To display captions below each image, set the captions option to true and ensure your images have alt attributes:

<!DOCTYPE html>
<html>
<head>
<title>justifiedGallery with Captions</title>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="justifiedGallery.min.js"></script>
<style>
  .jgallery-caption {
    font-size: 14px;
    color: #333;
    text-align: center;
  }
</style>
</head>
<body>

<div id="myGallery">
  <img src="image1.jpg" alt="A beautiful sunset">
  <img src="image2.jpg" alt="A majestic mountain range">
  <img src="image3.jpg" alt="A vibrant city skyline">
</div>

<script>
$(document).ready(function() {
  $("#myGallery").justifiedGallery({ captions: true });
});
</script>

</body>
</html>

The added CSS styles the captions. You can also use sibling elements for more complex caption control, as described in the Customization Options section.

justifiedGallery is inherently responsive. No additional code is needed for a responsive gallery. The layout will automatically adapt to different screen sizes:

<!DOCTYPE html>
<html>
<head>
<title>Responsive justifiedGallery</title>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="justifiedGallery.min.js"></script>
</head>
<body>

<div id="myGallery">
  <img src="image1.jpg" alt="Image 1">
  <img src="image2.jpg" alt="Image 2">
  <img src="image3.jpg" alt="Image 3">
</div>

<script>
$(document).ready(function() {
  $("#myGallery").justifiedGallery();
});
</script>

</body>
</html>

This example will work responsively without any additional code because justifiedGallery automatically adjusts its layout on window resize.

Custom Styling Example

This example shows how to customize the gallery’s appearance using CSS:

<!DOCTYPE html>
<html>
<head>
<title>Custom Styled justifiedGallery</title>
<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
<script src="justifiedGallery.min.js"></script>
<style>
  #myGallery {
    border: 5px solid #ccc;
    padding: 10px;
  }
  #myGallery img {
    border: 2px solid #eee;
    margin: 5px;
  }
</style>
</head>
<body>

<div id="myGallery">
  <img src="image1.jpg" alt="Image 1">
  <img src="image2.jpg" alt="Image 2">
  <img src="image3.jpg" alt="Image 3">
</div>

<script>
$(document).ready(function() {
  $("#myGallery").justifiedGallery({ margins: 10 }); // Example of using the margins option
});
</script>

</body>
</html>

This CSS adds a border and padding to the container and a border to the individual images, demonstrating how to style the gallery beyond the default appearance. Remember to adjust paths to your images.

Contributing

We welcome contributions to justifiedGallery! Whether you’re reporting bugs, suggesting improvements, or submitting code changes, your help is valuable.

Reporting Issues

If you encounter a bug or have a feature request, please follow these steps:

  1. Search for existing issues: Before creating a new issue, search the issue tracker ([Insert Link to Issue Tracker Here]) to see if the problem has already been reported.

  2. Provide detailed information: When creating a new issue, provide as much information as possible, including:

  3. Use a descriptive title: Choose a title that accurately reflects the issue you’re reporting.

Submitting Pull Requests

If you’d like to contribute code changes, please follow these guidelines:

  1. Fork the repository: Fork the justifiedGallery repository on GitHub ([Insert Link to GitHub Repository Here]).

  2. Create a new branch: Create a new branch for your changes. Use a descriptive branch name that reflects the changes you’re making (e.g., “fix-bug-123” or “feature-new-option”).

  3. Make your changes: Make your changes and ensure they are well-documented. Follow the coding style guide (see below).

  4. Test your changes thoroughly: Test your changes to make sure they work correctly and don’t introduce new bugs.

  5. Commit your changes: Commit your changes with clear and concise commit messages. Follow conventional commit message guidelines (e.g., feat: add new option, fix: resolve bug in caption handling).

  6. Push your branch: Push your branch to your forked repository.

  7. Create a pull request: Create a pull request on the main justifiedGallery repository, referencing the issue (if applicable) and providing a clear description of your changes.

Coding Style Guide

To ensure consistency and readability, please follow these coding style guidelines when submitting pull requests:

Before submitting a pull request, please ensure your code passes all tests and follows the style guidelines. We appreciate your contributions and look forward to reviewing your changes!

License

License Information

justifiedGallery is released under the [Insert License Name Here, e.g., MIT License]. You can find the full license text in the [Insert Path to License File, e.g., LICENSE file] of this project. In short, this license grants you the right to use, modify, and distribute justifiedGallery, subject to the terms and conditions specified in the license agreement. Please review the license carefully before using this software.