Juicebox HTML5 Responsive Image Galleries

Towards Drupal 10

The Juicebox module helps integrate the Juicebox HTML5 responsive gallery library (http://juicebox.net/) with Drupal. As of April 2023, the focus of the Drupal Juicebox maintainers is on developing a stable version of Juicebox for Drupal 10.  A dev version of this was provided on April 1, 2023 and is being tested.  If you have a "test" version of Drupal 10 running, you are welcome to help with this testing and post any issues you find here.  Many sites are in various stages of transition from Drupal 7, 8 and 9 to Drupal 10.  Generally these transitions need to be completed by December 2023.  

Starting with 8.x-3.0-alpha2 released 17 December 2020, the dependency on a separate Drupal Libraries API module was removed.  The documentation in the "Legacy section" below,  for Juicebox versions prior to 8.x-3.0-alpha2 is temporarily being retained to assist users of those versions during a transition period.  The Legacy section may be removed when Drupal 7, 8 and 9 are no longer supported.  Bottom line is that Juicebox does its own library detection starting with alpha2.  Given the few issues that have been reported with alpha2 we could probably make a stable version, but that would just take time from what is really needed:  a stable version of Juicebox for Drupal 10.  

Don't confuse libraries with libraries.  The Drupal Libraries API module is a Drupal module.  It lives at: https://www.drupal.org/project/libraries.  It is entirely separate from the Juicebox Javascript library that is a prerequisite to use the Juicebox module here.  This Javascript library will continue to be a prerequisite for the Drupal Juicebox module going forward to Drupal 10.  To save you from digging into the Legacy section here are the instructions:

1. 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.
2. 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 /libraries/juicebox on Drupal 8 and then copy the full contents of the Juicebox "jbcore" directory to this library directory. You will end up with a structure like /libraries/juicebox/juicebox.js and /libraries/juicebox/classic/theme.css.

If you are still using Drupal 7, you will also need the Drupal Libraries API module (see instructions in the legacy section).  We would strongly discourage new installations under Drupal 7 though.  If you are using the Drupal 8 alpha release, the Juicebox program will detect the presence (or absence) of the Juicebox library.  

Legacy section ... Installation (7.x)

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 on Drupal 7 or /libraries/juicebox on Drupal 8 and then copy the full contents of 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. (or /libraries/juicebox/juicebox.js and /libraries/juicebox/classic/theme.css on Drupal 8).
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 (7.x-2.x only): 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 (All versions including Drupal 10)

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 and Adaptive Images

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.

It is also possible to implement adaptive image concepts with Juicebox. This means that each user's device dimensions are detected and appropriately-scaled versions of each image are delivered dynamically. This can greatly reduce bandwidth and load times for small devices. If you have the PRO version of the Juicebox library (>=v1.4) its multi-size scaling feature delivers this functionality and is supported by this module. Simply select the special "Juicebox PRO multi-size" image style and the module will automatically map appropriate Drupal image styles to Juicebox screen modes (which even account for retina-style devices). The specific image styles used for each screen mode can also be customized in the global settings at admin/config/media/juicebox. If you don't have a PRO version of the library, or need more fine-grained control over adaptive source selection, the Adaptive images styles (AIS) module is a compatible alternative for implementing this feature. See this post for more info.

Note that no matter how big your images are, or what Drupal image styles you use, Juicebox will always display them relatively responsively. 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).

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 (with 7.x-2.x and 8.x-2.x) 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 (7.x). 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.
• Compatibility with AdvAgg Modifier module (7.x). Some settings offered by the Advanced Aggregation module (specifically the AdvAgg Modifier sub-module) may not be compatible with Juicebox. See here for specifics.
• Launch straight to full-screen (7.x). 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.
• Juicebox Javascript API Usage. Some users of the PRO library may want to utilize the Juicebox Javascript API for their own client-side customizations, which requires access to each gallery's javascript object. The easiest way to do this is through the global juicebox_instances array. See these notes for more information.