Bentobox: Advanced User Guide

This is a full summary of Bentobox’s features and how to use them, intended for those who have already digested the Getting Started guide, or those who already know their way around a WordPress shortcode-based plugin.

Usage

As detailed on the Getting Started page, Bentobox uses a simple shortcode to transform your images into a perfectly proportioned gallery.

The approaches here differ from those on the Getting Started page in that they include the unenclosed (simple) version of the shortcode, which requires an understanding of WordPress Media Attachments. Once you’ve got your head around that, the unenclosed version is actually simpler to use than the enclosed version mentioned elsewhere.

Default usage: showing attached images

The default Bentobox will fit the width of the containing paragraph and the height of the browser window. It will display all images attached to the post in a random order.

Just enter:

[bentobox]

And see the result:

By default, the images can be clicked to display the full-sized version in a lightbox. To turn this off use:

[bentobox lightbox=off]

Full-width galleries

Add the term fullwidth to the shortcode and the gallery will stretch across the full width of the screen. The default height is applied, making the gallery fit itself to the browser window.

[bentobox fullwidth]

Showing custom images

To display any set of images other than those attached to the post, use the [bentobox] shortcode, insert your images, then close the box using [/bentobox]:

[bentobox]
<img src="..."> <img src="..."> <img src="..."> etc.
[/bentobox]

You can also include links around the images, which can link to images or other URLs. Image links will be displayed using the plugin’s built-in lightbox effect. Any other content within the shortcode will be discarded:

[bentobox]
<a href="..."><img src="..."></a> etc.
[/bentobox]

NB. This is the same approach outlined in the Getting Started guide.

Setting the height

You can specify a custom height for the gallery using the height parameter like so:

[bentobox height=250px]

Adding gaps between the images

You can add a gap or margin around the images using the gap parameter. Specify the number of pixels. Don’t include a unit.

[bentobox gap=7]

The result:

Applying styles

You can add any other CSS you like to the gallery using the style parameter:

[bentobox gap=5 style="background: #999; border: 5px solid #333; margin: 0 4em 2em;"]

Adding classes

Apply your own CSS classes to the output gallery using the class parameter.

[bentobox class="foo"]

Shortcode summary

[bentobox] Default usage. Display all attached images.
[bentobox lightbox=off] Turn off image links with default usage.
[bentobox fullwidth] Stretch across the width of the screen.
[bentobox]<img><img>[/bentobox] Enclose a custom set of images (with or without links).
[bentobox height=300px] Specify a height.
[bentobox gap=5] Add a gap between the images.
[bentobox style="..."] Add CSS styles.
[bentobox class="..."] Add CSS classes.

Using Bentobox outside WordPress

You can use the scripts that generate Bentoboxes in your designs outside WordPress. Instructions for doing so can be found here.

Notes

You can include other shortcodes within a Bentobox shortcode. For example:

[bentobox][instagram-feed][/bentobox]

This is fairly experimental and can’t be guaranteed to work with all other plugins and shortcodes. It depends on how the other plugin(s) has/have been constructed.


To include a Bentobox in your theme template, just use:

<?php do_shortcode('[bentobox]'); ?>

If you want to use a mix of Bentoboxes on the same page, containing both attached images and a custom set of images, you cannot use the shortcode in its simple form. Instead, to produce the default (attached images) version, you need to use the opening and closing shortcode with nothing in the middle. i.e.

[bentobox][/bentobox]

You can use the same lightbox effect used by Bentobox elsewhere in your site by adding the following Javascript, or something like it:

$(window).load( function() {
	$('a[href$=\'.jpg\'], a[href$=\'.jpeg\'], a[href$=\'.png\']').bentolightbox('article');
});

The article selector within the bentolightbox() function is the scope of the lightbox, meaning the element within which it cycles through images. If this is omitted, it defaults to body, thus cycling through all the images on the page.

You’ll need to have loaded jQuery as well for this.


Photos on this page are from FlickR, used under CC licenses.