Installation
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.
Configuration
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 1.7.3.1 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.
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. | |||
| carousel | |||||
| tabs | |||||
| 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. | |||
| no-embedded-carousel | |||||
| tiles | The images of the gallery are displayed as butt joined square tiles in "cover" mode. This mode overrides the Settings ‘Use Tiles’ option. | ||||
| no-tiles | |||||
| contain | Modify the "tiles" option to use the "contain" mode. This mode overrides the Settings ‘Use Tiles’ option. | ||||
| no-contain | |||||
| fill | Modify the "tiles" option to use the "fill" mode. This mode overrides the Settings ‘Use Tiles’ option. | ||||
| no-fill | |||||
Examples
[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 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.
Large 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.
Medium Viewport
On a smaller browser viewport the number of columns will be reduced.
Small Viewport
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
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.
Problems
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.
BB Gallery 