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 Gallery View
From version 188.8.131.52 the default view of a gallery displays the images as butt joined square image tiles. The images can "cover", "contain" or "fill" the square tile. The default is "cover" where the smaller of the image width or height is set to the tile size. The image is then cropped to fit in the square tile preserving the aspect ratio. The difference between the tiles view in "cover" mode and the flexbox gallery view is that in the flexbox view the image is never cropped but scaled to fit in the cell width preserving the aspect ratio. In "contain" mode the larger of the image width or height is set to the tile size and the image is scaled to preserve the aspect ratio. This results in horizontal margins for landscape images and vertical margins for portrait images. In "fill" mode both the image width and height is set to the tile size. The aspect ratio is not preserved. You can enable this globally for all galleries by setting the "Use Tiles" option on the Settings page or individually on specific galleries using the ‘flags="tiles"‘ shortcode option.
The Carousel View
The "Carousel View" uses the entire browser viewport. However, there may be either large vertical or horizontal margins in order to preserve the aspect ratio. Instead of dragging the scrub bar it may be easier to click or tap on the slide at the desired position. On tablets you can also use swipe motions to move to the next or previous slide. The close button will return you to the "Gallery View". The administrator can optionally make the "Carousel View" as the initial view of the gallery by globally setting the "Default View" option to "Carousel" or individually using the ‘view="carousel"‘ shortcode option.
The carousel can be embedded in the post content instead of using the entire browser viewport.
The administrator can optionally embed the "Carousel View" in the post content by globally enabling the "Use Embedded Carousels" option or individually using the ‘flags="embedded-carousel"‘ shortcode option.
The 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.
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.
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.
[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"]
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 Flexbox Gallery View
If the "Use Tiles" option is disabled the gallery is displayed using a CSS3 Flexbox. This was the previous default view of a gallery. The "Flexbox Gallery View" is responsive and is different depending on the size of the browser viewport.
On mouse devices hovering over an image displays the image caption and the expand icon. Clicking on the expand icon displays a full browser viewport overlay of the image.
On a smaller browser viewport the number of columns will be reduced.
In a small browser viewport view – e.g., a mobile tablet in portrait mode – the gallery navigation bar is normally hidden and can be displayed by tapping on the expand icon in the upper right corner.
The Table View
This 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
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.