Last updated 27 May 2017. Created on 21 May 2013.
Edited by colorfield, Yashaswini.Trivedi, rjacobs, zenkul. 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 (7.x and 8.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/themes.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 (7.x and 8.x)

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.

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.

Comments

xeM8VfDh’s picture

The "Installation (7.x and 8.x)" section above indicate that the Libraries API module is required. While that module has an 8.x-3.x-dev release, the module page is showing:

"This module is currently being ported to Drupal 8, but is not usable yet."

And yet, the Juicebox HTML5 Responsive Image Galleries module page indicates that their Drupal 8 release "should be feature complete and stable enough for real-world usage and testing".

So, does the 8.x-2.0-beta3 release of Juicebox HTML5 Responsive Image Galleries not require the Libraries API module, or does it somehow work with the "not usable" 8.x-3.x-dev version of Libraries API module?

Thanks!

EDIT 1:
I should note, after installing the Juicebox 8.x-3.x-dev release, I am unable to enable it without first installing Libraries API, which is listed as a requirement in the module's info section. So, does it really work with the "not usable" D8 version of Libraries API. If so, should we expect it to break as development on Libraries API 8.x-3.x-dev continues?

EDIT 2:
It seems to work with the "not usable" D8 version of Libraries API. Is this really a dependency for the D8 version of Juicebox HTML5 Responsive Image Galleries? If not, it should be removed from the requirements lists so that the module can be installed without installing Libraries API. The documentation should also be updates. If not, should we expect that Juicebox HTML5 Responsive Image Galleries will break as development on Libraries API continues?

Thanks for the awesome module, btw.

rjacobs’s picture

The Librareis API module is indeed being used by the Juicebox module, so the dependency is certainly valid. Some of the specifics about how this affects things going forward gets a bit nuanced but if you are tracking the most recent versions of each module you should be in good shape. There is more info on this at https://www.drupal.org/node/2770255

smartcow’s picture

Any suggestions as we have installed as mentioned, but it only allows one image to be uploaded.