The BB Gallery Shortcode

This site is now deprecated and will be removed in the future. The current documentation of BB Gallery is now at

April 27, 2017
I have quit active development of this plugin. This means no new features will be added. If you are intending to become a new user of this plugin I recommend you try another product. If you are an existing user don’t worry. This plugin is still fully supported and I intend to maintain the existing feature set of this plugin for the foreseeable future. This includes compatibility with future versions of WordPress. However as I no longer personally use this product I will not know about a problem unless a user reports it. You can report a problem using this plugin’s support forum. But, for the quickest response in addition you should also contact me using the contact form on my website.
This is a mobile-friendly plug-compatible replacement for the built-in WordPress gallery shortcode. You can view a sample working page using this plugin at my portfolio website. It is implemented using a Backbone.js Model-View-Presenter (MVP) populated via the WordPress REST API, styled by a Twitter Bootstrap 3 stylesheet and with touch support provided by components from jQuery Mobile. The MVP paradigm allows you to switch instantaneously (i.e. without doing a HTTP request) between multiple views of a gallery. The default implementation supports a gallery view, a carousel view, a tabs view and a dense view of the gallery. The WordPress REST API also makes it possible without reloading the page to dynamically load a collection of images from some preset galleries or dynamically create and load a collection of images specified by some search criteria. The view is styled by a Twitter Bootstrap 3 stylesheet so it is automatically responsive. If the browser supports the CSS3 Flexbox the gallery view is implemented using a flexbox. You can easily modify the Backbone templates to create your own customized views of the gallery. The user can also configure the options to suit his preferences.


This plug-in can be downloaded from the WordPress repository. A beta release (version 1.8) of this plug-in can be downloaded from GitHub.

It is easy and safe to try this plugin. Simply install the plug-in. Visit the "Dashboard > Settings > Media" page and check the "Enable BB Gallery" option in the "BB Gallery" section and save the settings. The defaults for all other options should work reasonably well. Visit any page which has a gallery shortcode. If you are not happy simply uninstall this plugin. Your website will not be changed in any way.


This plug-in is configured by setting options on the "Settings > Media" page of the Dashboard. Enabling the "BB Gallery" option replaces the built-in WordPress gallery shortcode implementation with this plug-in’s implementation. If you do not enable this option you can still invoke this plug-in’s gallery shortcode implementation using the shortcode "bb_gallery" e.g. "[bb_gallery]". If you have enabled this option but want to invoke the built-in WordPress implementation you can specify the shortcode parameter "mode" with value "wordpress" e.g. "[gallery mode='wordpress']". If the WordPress REST API v2 is available (i.e., the WP REST API plugin is installed and activated) and the "Use the WP REST API" option is enabled the plugin will use the WP REST API to populate the Backbone.js collections otherwise it will use its own proprietary API. Beware the WP REST API requires pretty permalinks. The "Table View" is primarily for developers and should be disabled for production environments. You can click on the image to get a larger, clearer image.

The Tabs View

tabs view
An advantage of the "Tabs View" is that it uses the image description which may be longer than the image caption and may contain HTML. If the image does not have a description then the fallback is to use the image caption.

The Dense View


This is my solution to showing titles with small images. The (yellow) highlighting of the titles and images are synchronized. This view is intended for displaying a large number of images and requires a large browser viewport and a mouse interface and is not available on touchscreen devices.

The Overlay


A full browser viewport overlay view of an image in the "Gallery" or "Dense" view can be displayed by clicking on its expand icon found in the upper right corner of the image. On devices with a mouse the title and caption can be hidden by hovering anywhere outside of the image. On touch devices a left/right swipe will hide/show the title and caption. You can exit the overlay by clicking or tapping anywhere in the overlay.

Dynamically Loading Galleries

BB Gallery’s menu can have menu items that allows the user to dynamically load galleries via the WordPress REST API (or via my proprietary AJAX API if the WP REST API is not available). The dynamically loaded gallery replaces the current gallery.


Optionally by setting the "Use Gallery Tabs" option the titles of the dynamically loadable galleries can be displayed as tabs in a visible tabs bar.


Optionally, by using the gallery shortcode parameter mode="galleries" the dynamically loadable galleries can be displayed as clickable representative images in a gallery.


The GALLERIES menu can be populated using the BB Gallery Menu Settings section on the Dashboard‘s Settings->Media page. You can click on the image below to get a clearer full size view of the image.


The format is the title enclosed in double quote marks, followed by a colon, followed by the gallery parameters which are the same format as the WordPress gallery shortcode, e.g. – "Title of My Gallery":id="17" orderby="title" order="ASC". This sets the default GALLERIES menu.

An individual gallery shortcode can override this default menu for its own navigation bar by specifying altgallery shortcodes as the content of an enclosing gallery shortcode.


The options of the altgallery shortcode are the same as WordPress’s gallery shortcode with one additional required option title which will be used as the menu item label.

The mode="galleries" version of the gallery shortcode displays a gallery of galleries. The images are specified by the contained altgallery shortcodes. The altgallery shortcode has two additional options – image and caption which specify the image to use to represent the gallery and the caption to display for the gallery. You can click on the image below to get a larger, clearer view of the image.


If the image option is not specified the first image of the gallery is used as the representative image. If the caption is not specified the title is reused as the caption. The representative image must be unique i.e., two galleries cannot share the same representative image (since the image id is the Backbone.js model id which must be unique). In "galleries" mode the id, ids, include, exclude, … options of the gallery shortcode are ignored since the images are specified by the contained altgallery shortcodes.

Shortcode Options

In addition to the id, ids, include, exclude, orderby, and order options of standard WordPress gallery shortcode the gallery shortcode of this plugin also has its own proprietary options mode, view and flags.

Option Value Description
mode galleries This is a gallery of galleries. This mode overrides the Settings ‘Use Gallery Tabs’ option.
view gallery This sets the initial view of the gallery and overrides the Settings ‘Default View’ option.
flags embedded-carousel Embed the carousel inside the post content instead of using the entire browser viewport. This mode overrides the Settings ‘Use Embedded Carousels’ option.
tiles The images of the gallery are displayed as butt joined square tiles in "cover" mode. This mode overrides the Settings ‘Use Tiles’ option.
contain Modify the "tiles" option to use the "contain" mode. This mode overrides the Settings ‘Use Tiles’ option.
fill Modify the "tiles" option to use the "fill" mode. This mode overrides the Settings ‘Use Tiles’ option.


[gallery ids="163,166,168,170,172,174,176,178" view="tabs"]
[gallery id="77" view="carousel" flags="embedded-carousel"]
[gallery id="77" view="carousel" flags="tiles,no-embedded-carousel"]
[gallery id="77" view="carousel" flags="tiles,contain"]

User Options


Setting the "Minimum Width for Gallery Images" too small will disable the display of captions. The "Dense View" is not available on touchscreen devices. The "Auto" setting of the "Bandwidth" and "Interface" options does not always work. You may need to set these options manually. Using the WP REST API the maximum number of images returned by a search must be less than or equal to 100. Cookies must be enabled for these settings to be saved permanently.

The Table View

settingsThis view is intended primarily for developers. It displays the field names exactly as you would use them in Backbone.js templates. This view can be displayed by enabling the "Table View" option of the "Settings > Media" page.

Roll Your Own

Backbone.js templates consists of HTML with placeholders for the values of the model e.g. "<img src='{{{ data.url }}}'>". Here "url" is the name of a field in the model. You can modify or create your own Backbone.js templates without knowledge of PHP or JavaScript (some JavaScript is needed for more advanced templates). You can get the available field names of the model from the "Table View". See "…/bbg_xiv-gallery_templates.php" for the implementation of the default views. You can modify these views or create your own by editing this file. The simplest template is the template for the CCS 3 Flexbox view of the gallery. You should study this template first.


For each image in the gallery the plug-in’s front-end code will instantiate the "Flex Item Template". Then using the concatenation of all these instantiations as the value of data.items the "Flex Container Template" is instantiated.


The dropdown view menu doesn’t appear.

Clicking on the ‘View’ nav item does not show the dropdown view menu. This may be caused by multiple installations of bootstrap.js. If another theme or plugin is also using bootstrap then multiple copies of bootstrap.js may be included on the webpage. This will cause the ‘View’ nav item to stop functioning. A workaround for this problem is to remove the file ‘js/bootstrap.js’ from this plugin’s folder.

The page loads slowly.

BB Gallery can preload full size images for better user interactivity. This does not work well for low bandwidth connections and/or devices with slow cpus. You can set the bandwidth option to “low” to prevent preloading and force the use of low resolution images.