Using the Juicebox field formatter

Users who want to add Juicebox galleries to individual nodes/entities can use the Juicebox field formatter.

The notes on this page assume you are using a 7.x-2.x or 8.x-2.x version of the Juicebox module. Not all options/features outlined here will be available in 7.x-1.x, though the same general concepts still apply.

Step-by-Step Setup Example

If you are familiar with other Drupal field formatters this technique should be fairly straightforward. The steps below outline the basic usage of the Juicebox field formatter in a use case where a node is used to display a gallery. Though this is a very common use case note that the field formatter can also be used in may other contexts. Almost anywhere fields can be used, a gallery can be inserted.

1. Ensure the Juicebox module is properly installed.
2. Create a content type to represent a full gallery/album object. Within the "manage fields" tab you can add any fields that you like but you must include one "image" or "file" field to hold your gallery images. If you have the Media module installed (7.x-2.x only) you'll probably also want to choose the "Media file selector" as your input widget, as this will allow you to use your global media library. In the related image or file field options be sure to:
   • Set the "number of values" option to a value greater than one (e.g. "unlimited"). This will allow you to add multiple images to the field, thus making a gallery.
   • If available, check the "enable alt field" and "enable title field" boxes (for image fields) and the "enable description field" (for file fields). These values can be used later to hold caption or title information. Note that depending on your input widget these options may not always be available. Furthermore, these are not the only sources that can be used for titles and captions (see the "Titles and Captions" notes below).
3. Within the "manage display" tab, find the entry for your image field and under the "format" options choose "Juicebox Gallery". Then click on the gear/cog button to the right to open the Juicebox-specific display options. Here you can:
   • Specify which image styles to use when displaying images and thumbnails. Note that first you may need to create a new style at /admin/config/media/image-styles if none of the available options are suitable. See the Managing Image Styles notes for more information about selecting image styles.
   • Specify which parts of the field data to use as caption and title sources (if any). The options that you see here will depend on your specific configuration (see the "Titles and Captions" notes below).
   • Customize a variety of Juicebox configuration options for this gallery in the remaining fieldsets.
4. For each gallery that you would like to create, add a new node of the type you just setup. Upload the various images that you want for each gallery into the image or file field that you configured above.

Titles and Captions

A variety of data sources from each image can be used for the title and caption details shown in your gallery. The specific sources that are available will be automatically detected based on your configuration. Compatible sources include:

• Image title text. Available for image fields when the "Title" field has been enabled in the field settings.
• Image alt text. Available for image fields when the "Alt" field has been enabled in the field settings.
• Image field caption (7.x-2.x only). Active only when the Image Field Caption module is enabled. Available for image fields.
• File description text. Available for file fields when the "Description" field has been enabled in the field settings.
• Filename. Available for both image or file fields.
• Any text-based fields added to the "Image" file field type (7.x-2.x only). Active only when the File Entity module (often installed with the Media module) is enabled. Available for both image or file fields, but will only be applied to individual files in the gallery that have an "image" mimetype. Image file fields can usually be managed at /admin/structure/file-types/manage/image/fields

All title and caption values will be processed by one of your Drupal text formats before output in a gallery. Text formats can be configured at /admin/config/content/formats. The specific text format used depends on the source:

• Sources that don't automatically expose text format options to editors will be processed by your Drupal fallback text format (affected sources are noted during source selection). For these sources this typically means that the text will be displayed in Juicebox without the formatting applied (the html tags will be escaped). This behavior can be altered in most cases by following these notes.
• Any text sources that do expose text format options to editors (such as Image field captions and custom Image file fields) will make use of the text format configured during editing.