Drupal 7 Juicebox HTML5 Responsive Image Galleries Module

Juicebox HTML5 Responsive Image Galleries

Last updated January 10, 2014. Created by rjacobs on May 21, 2013.
Edited by jlindsey15. Log in to edit this page.

The Juicebox module helps integrate the Juicebox HTML5 responsive gallery library (http://juicebox.net/) with Drupal. Juicebox is in many ways the successor to Simpleviewer and offers a powerful and responsive image gallery front-end that's based on HTML5. See the project page for a detailed feature overview.

Installation

  1. Install and enable the required Libraries API module (version 2.0 or above) from http://drupal.org/project/libraries.
  2. Download the 3rd party Juicebox library from http://www.juicebox.net/download/ and extract it to a temporary location. Both the Lite (free) and Pro versions should work fine with this module, and the one you should choose depends on how much formatting flexibility you require.
  3. Copy the appropriate core Juicebox library files that you just extracted to Drupal's library directory. Typically, this means you will create a new directory called /sites/all/libraries/juicebox and then copy the full contents of the the Juicebox "jbcore" directory to this library directory. You will end up with a structure like /sites/all/libraries/juicebox/juicebox.js and /sites/all/libraries/juicebox/classic/themes.css, etc.
  4. Install and enable this Juicebox module.

If for any reason you enable the Juicebox module (step 4) before installing the Juicebox library (step 3), or if you make changes to the Juicebox library itself, please be sure to clear your Drupal cache at /admin/config/development/performance. This will ensure that the correct Juicebox library information is detected by the Libraries API.

Advanced installation note: If you plan to use Juicebox galleries with anything other than Drupal nodes, users or views (e.g. special/custom entity types) you may also need to install the Entity API module. Please see these notes for more about this (this is less common and most users can ignore this step).

Usage and Configuration

This module integrates with Drupal on many levels but conceptually it operates just like any other display formatter. It's designed to let you easily turn groups of Drupal-managed image data into Juicebox galleries without making too many assumptions about how your site is structured or what media management strategy you use.

Basic Field-Based Galleries (the Field Formatter)

Users who simply want to add galleries to individual nodes/entities, and manage them individually, can use the Juicebox field formatter. With this method most any multiple-value image or file field can quickly be displayed as a Juicebox gallery.

If you are familiar with other Drupal field formatters this method should be fairly straightforward. When working with the "display" options for your entity (such as the "Manage Display" tab for a node content type) you can simply select the "Juicebox Gallery" format option for any image or file field, and then tweak a number of formatter-specific options to your liking. The Juicebox field formatter (7.x-2.x) is also compatible with Media and File Entity, so file fields constructed through Media widgets (e.g. using reusable images from a global media library) can also become Juicebox galleries, and can even leverage file field data for titles and captions.

Browse additional notes and step-by-step directions related to the Juicebox field formatter.

Views and More Advanced Media Management (the Views Style Plugin)

If you need to group image data from multiple nodes/entities/files into galleries, and leverage the flexibility of views to organize everything, you can use the Juicebox views style plugin. This method allows Juicebox to be adapted to more advanced media management setups where image data is stored in dedicated entities/content types and where more complex organizational tools may be needed (taxonomy and contextual filters, etc).

With this formatter any views that lists files, or content containing image/file fields can become Juicebox galleries. These views may be based on your own design and information-architecture, or be provided by other gallery-like modules such as Node Gallery.

Browse additional notes and step-by-step directions related to the Juicebox views style plugin.

Managing Image Styles

The Juicebox module integrates with Drupal's core image styles so you have the ability to automatically scale your images to appropriate dimensions or add effects. Any core image styles that you create at /admin/config/media/image-styles will be available when configuring which image sources to use for your gallery images and thumbnails. For more information about working with core image styles see these notes in the Drupal handbook.

No matter how big your images are, Juicebox will always display them relatively responsively, but some upper-limits apply. This is simply because even large desktop screens may not be able to display the full resolution of your originals. Also keep in mind that even if you use a scaled version of each image for display, the full-resolution (unscaled) version can still be be made available to users by enabling the "Open Image Button" (in the "Lite Config" options for the gallery). In short, it's not worth it to go overboard with your image resolution.

It is also possible to implement adaptive/fluid image concepts with Juicebox. This means that each user's maximum device dimensions are detected and device-appropriate scaled versions of each image are delivered to their browser. This can dramatically reduce bandwidth and load times on small devices. In this reagrd the Adaptive images styles (AIS) module can be used with Juicebox to deliver this functionaltiy. Setting this up is as simple as installing the AIS module and then setting Juicebox to use the "adaptive" image style for your main gallery images. See this post for more info.

Multilingual Considerations

Because the Juicebox module leverages native Drupal elements (fields and file metadata) for image titles and captions, no special techniques should be required for content translation in multilingual sites. As long as your title and caption sources are translated with existing Drupal tools, like the Content Translation or Entity Translation modules, the text within your galleries can be language aware.

It is also possible for the Juicebox interface (tooltips for icons/buttons, etc.) to be translated and toggled automatically with the rest of your Drupal interface. To enable interface translations browse to the global Juicebox settings at admin/config/media/juicebox and check the "Translate the Juicebox javascript interface" option. You will then be able to see and customize the "Base string for interface translation", which represents the base English text that Drupal will attempt to translate (based on the user's active language) before passing it to the Juicebox library. Most users will not need to change this default base string. Once this interface translation option is enabled it's still up to you to actually enter a translation for the base string in your site, typically with the Locale module's "translate interface" tool at admin/config/regional/translate. See here for more details.

Additional Notes from the Issue Queues

  • Compatibility with Theme Developer module. There is a known incompatibility between this module and the Theme Developer module. Nothing serious will happen if the two are enabled side-by-side, but your galleries may not display correctly until Theme Developer is disabled. More details are available here.
  • Launch straight to full-screen. If you are comfortable with custom Drupal theming techniques, you can setup your galleries to launch directly into a "full screen" (full window) mode. See these notes for details.
  • Performance. If your gallery pages receive very high levels of traffic that cannot be serviced by standard Drupal caching, you may be interested in these performance notes.