TopBox

TopBox is derived from Nivo Lightbox. I created a stack addon for the RapidWeaver publishing platform (named TopBox) around 2012, which made use of Nivo Lightbox. I also added Nivo Lightbox to a number of plugins, themes and client websites as things progressed. Along the way, I found and fixed several bugs in the original Nivo Lightbox and made improvements of my own. Because Nivo Lightbox is seemingly no longer actively updated, I have released my variant of Nivo Lightbox opensource, under the name of 'TopBox'.

TopBox is MIT licensed, so you are free to download and use it wherever and however you want.

Some of the things that are different in TopBox, compared with the original Nivo Lightbox:

Fully jQuery v3 compatible.
Swipe support for touch devices (e.g. smartphones and tablets).
Sharper, retina-display optimised navigation buttons with UTF-8 / CSS.
Vimeo and YouTube video embeds support SSL protocol and autoplay.
Major changes to content positioning. Less Javascript, more CSS Flexbox!
Deleted older hacks and prefixes for obsolete web browsers (like Internet Explorer).
Added HTML5 Audio, Dailymotion, SVG, TED, Brighteon, PDF, iFrame video and WebP support.
Easier translation of lightbox user interface tooltips into different languages.
Greater control over the attributes used for lightbox triggering and captioning.
Various accessibility improvements, including features like keyboard focus and ARIA labels.
The page background can be blurred, when the lightbox opens.

TopBox is used in thousands of websites; ranging from small blogs right-up to fortune 100 companies. A durable and flexible lightbox effect you can depend upon. TopBox is maintained on Github as an opensource project.

Using TopBox

Download the source code files from Github. Click here. Use the ZIP download option.

Upload the TopBox files (within the /src/ directory) to your web server.

Add a call to topbox.css stylesheet within the <head> section of your webpage like this:

<link rel="stylesheet" media="screen" href="path/to/topbox.css">

Then add the jQuery Javascript call, topbox.js and your function to the end of your webpage, ideally before the closing </body> tag, like this:

<script src="path/to/jquery-3.3.1.min.js"></script>
<script src="path/to/topbox.js"></script>
<script>
	$(document).ready(function() {
		$('.lightbox').topbox();
	});
</script>

The chances are that your webpage already includes CSS and / or jQuery. You might not need the extra jQuery call. So feel free to take only what you need and merge the TopBox code into your existing website code.

To make a link (like an image) open in TopBox with a title, the HTML markup is as simple as this:

<a href="path/to/my-image.jpg" class="lightbox" aria-haspopup="dialog" title="My Image">Click me!</a>

By default, any link with a class of lightbox will trigger a TopBox. However this can be changed to another selector name, attribute, or element type, if you prefer.

Tip: We add the aria-haspopup="dialog" attribute to our link, to improve webpage accessibility.

Examples

Much like any lightbox or modal window effect, TopBox is best-used in moderation for the sensible display of simple content types. Here are some examples of what it can do:

Inline Content

This TopBox content type takes the ID selector name on an element on your webpage, like a container with its style set to display:none with CSS. TopBox opens this content within the lightbox and makes it visible. Useful for simple content types, like a contact form.

You can mix both text and images together, without breaking the alignment. Try resizing your screen too!

When creating your link or button to launch inline content, set the href attribute equal to the ID of the element you want to open. e.g. #myDiv

Tip: The HTML5 Audio, HTML5 Video, Vimeo and YouTube examples here use custom controls via the excellent Plyr plugin. Setup of this plugin to work with TopBox is documented here.

Other Attributes

Content Types
A couple of content types require some additional attributes on your 'trigger' link or button, to tell TopBox how you want the target content handled:

iFrames require a data-lightbox-type="iframe" attribute.
AJAX requires a data-lightbox-type="ajax" attribute.
Inline requires a data-lightbox-type="inline" attribute.
Video iFrames require a data-lightbox-type="video-iframe" attribute.

For example, our iFrame example above has the following markup:

<a href="https://wikipedia.org" class="lightbox" title="iFrame Content" aria-haspopup="dialog" data-lightbox-type="iframe">iFrame</a>

You may be wondering what's the difference between iframe and video-iframe lightbox types? The latter has its height permanently locked to 56.25% tall (16:9 ratio) making it good to use for embedded video types like Internet Archive, Veoh, Vidyard, Wistia, and many others. Some of these video providers require additional code adding to your webpage or verification of your webpage link; hence we don't detect these specific video providers automatically like we do with Brighteon, Dailymotion, YouTube or Vimeo.

Galleries
The example TopBoxes presented above open and close singular items. By giving two or more items a data-lightbox-gallery data attribute, you can effortlessly 'chain' multiple items together like this, with next and previous buttons, and swipe support on touch screens:

<a href="path/to/my-image.jpg" class="lightbox" aria-haspopup="dialog" data-lightbox-gallery="gallery1">Click me!</a>

Touch Device Support

Swipe Support
Swipe support lets the end user navigate through a TopBox gallery using finger swipe gestures on their smartphone or tablet device. Swipe to the right to navigate to the previous gallery item or swipe to the left to navigate to the next gallery item.

Swipe support is already enabled by default; there is nothing further you need to add. We are using the excellent TouchSwipe jQuery Plugin to accomplish this.

On the rare occasions you wish to disable swipe support, remove the TouchSwipe plugin code from the top of your topbox.js file and everything within the 'swipe support' comments towards the bottom of your topbox.js file.

PDF Support
Support for embedded PDF files is historically quite poor on devices like the iPhone and iPad. iOS handles a PDF similar to an image. It will only display the first page of a PDF and will restrict the ability to scroll through a PDF file.

To circumvent these problems, we detect common tablet and mobile devices. The embedded PDF file iFrame will be replaced with a simple text instruction and download button. The message displayed is customisable within the API, using the pdfMessage and pdfButton options (documented below). The button works to simply open the PDF in a new browser tab.

Settings

TopBox continues to reuse many of the former Nivo Lightbox options and hooks. Some new ones have been added too. You can pass these options to the plugin like this:

<script>
$(document).ready(function() {
	$('.lightbox').topbox({
		effect: 'fade',
		skin: 'blue_sky',
		keyboardNav: false
	});
});
</script>

Here is a complete list of the options available to you:

Name	Type	Default	Description
effect	String	'fade'	The opening CSS transition effect. Can be one of either `none`, `fade`, `slideLeft`, `slideRight`, `slideDown`, or `slideUp`.
backgroundBlur	Boolean	false	Blurring takes the contents of the page body and wraps them inside a new `topbox_blur_wrapper` divisional container. A skin is able to blur or change the opacity of this content using CSS filters, when the lightbox is opened. This can have performance implications in certain setups, so please use with care.
skin	String	'darkroom'	Name of the skin (theme) to use.
keyboardNav	Boolean	true	If enabled, a person can navigate through the lightbox using their keyboard left, right and escape keys.
clickImgToClose	Boolean	false	Closes the lightbox when the image is clicked or tapped.
clickOverlayToClose	Boolean	true	Makes the lightbox close when its window shade is clicked or tapped.
closeToolTip	String	'Close'	Title tooltip text displayed on the lightbox close button.
previousToolTip	String	'Previous'	Title tooltip text displayed on the lightbox previous arrow button.
nextToolTip	String	'Next'	Title tooltip text displayed on the lightbox next arrow button.
titleSource	String	'title'	The attribute to use for your titles. Can be a simple `title` attribute or an HTML5 data attribute like `data-lightbox-title` if you want something different.
pdfMessage	String	'View the PDF in a new window:'	The message displayed on touch devices, where embedded PDF files are not supported.
pdfButton	String	'Tap Here'	The button label for the PDF button, displayed on touch devices.
errorMessage	String	'The requested content cannot be loaded. Please try again later.'	Message displayed if the content cannot be loaded.

TopBox also has a number of hooks. Code you place between the opening and closing braces will be run, when the lightbox is in that particular state:

onInit: function(){}
beforeShowLightbox: function(){}
afterShowLightbox: function(lightbox){}
beforeHideLightbox: function(){}
afterHideLightbox: function(){}
beforePrev: function(element){}
onPrev: function(element){}
beforeNext: function(element){}
onNext: function(element){}

Hooks are added in the same way you add options. They can perform various tasks during different states of the lightbox like this:

<script>
$(document).ready(function() {
	$('.lightbox').topbox({
		effect: 'fade',
		skin: 'blue_sky',
		keyboardNav: false,
		afterShowLightbox: function(lightbox){
			$("form").submit(function(){
				$('.topbox_close').trigger('click');
			});
		}
	});
});
</script>

Skins

Skins (or themes) offer a quick method towards restyling TopBox. By its nature, TopBox is extensively customisable. If you know the basics of CSS, then you are already well on your way towards designing your own lightbox styling! Alterations like changing colours are quite simple to do.

The default skin used by TopBox is called 'Darkroom'. As the name suggests, this offers a light-on-dark colour scheme. By taking the CSS for Darkroom (towards the end of topbox.css) you can use this as a basis for creating your own skin. Or take one of the skins listed below to rework. The name of our new skin can be passed via the TopBox function (see API for details).

The /src/skins/ directory (within the TopBox source code download) provides a few ready-made lightbox styles to experiment with or modify. Skins included TopBox include:

Blocky (blocky)
Blue Hue (blue_hue)
Deck (deck)
Engraved (engraved)
Eye Watering (eye_watering)
Fancyboxish (fancyboxish)
Forest (forest)
Framed (framed)
Ghost (ghost)
Half Way (half_way)
Impact (impact)
Intense Kiss (intense_kiss)
Keyboard (keyboard)
Minimal (minimal)
Mint (mint)
Monospace (monospace)
Night Mode (night_mode)
Pulse (pulse)
Shadeless (shadeless)
Scribble (scribble)
Script (script)
Smart (smart)
Social (social)
Spring Pop (spring_pop)
Stripes (stripes)
traditional (traditional)
Vivid (vivid)
Whiteout (whiteout)
Zest (zest)

Some of these skins are visual clones from other lightbox plugins. You can either copy the CSS (and any other assets like images or fonts) into your existing website theme or template. Or upload the desired skin directory to your web server and call it like this in your page:

<link rel="stylesheet" media="screen" href="path/to/skins/ghost/styles.css">

Within the Javascript function for TopBox, you will want to switch the skin from darkroom to skin_name replacing 'skin_name' with the name of the actual skin you want to use.

Extras

Basic Copy Protection
You can impose basic copy protection on your TopBox content by means of disabling mouse events with CSS:

.topbox_content {
        pointer-events: none;
}

This will stop the 'save image as' option showing, when a user right-clicks on an image. Obviously this will not stop the user still getting the image via other methods (like screengrabs or from the source code)! Pointer events should not be used for content that requires interaction with, such as video.

Change the lightbox size
TopBox makes use of simple and modern CSS markup to control content sizing. We use a mixture of CSS Flexbox, transforms and viewport units of measurement. In essence, the markup to control lightbox sizing is as simple as this:

.topbox_content {
	width: 80vw;
	height: 80vh;
}

As you can see, we use viewport units of measurement (viewport width and viewport height). This provides us a perfectly flexible box and avoids content clashing with lightbox navigation controls or titles. Through this configuration, our completed lightbox is completely fluid on different screen sizes, it responds to the screen changing size or orientation, and there is unlimited space reserved for the lightbox titles of any length. Single images and video scale proportionally to fit. If content (like iFrames, Inline or AJAX) does not fit within the viewable area, they will display scroll bars. Media breakpoints could potentially be used too.

Disable on mobile
Lightboxes serve little purpose on mobile. Disable their triggers below a certain breakpoint width, with simple CSS like this:

@media screen and (max-width: 460px) {
	.lightbox {
		pointer-events: none;
	}
}

In this instance, thumbnail images continue to show but won't do anything when clicked or tapped on screens less-than 460px wide.

Disable scrolling
You can prevent the page background scrolling when the lightbox is open, using some CSS like this:

body.topbox_open {
	overflow: hidden;
}

When the lightbox is opened, the webpage will no longer scroll. Scrolling resumes again, when the lightbox is closed.

Trigger from a URL hash
Make a TopBox open on page load via a 'hash' in the page URL. Add this jQuery within your $(window).on("load", function () handler:

if(window.location.hash) {
	var hashValue = location.hash.replace(/^#/, '');
	$("." +hashValue).trigger('click');
}

For example, https://example.com/#mountain would do a 'virtual' click on the TopBox link that has a class of mountain applied to itself.

Custom video controls
Content types like HTML5 Video, YouTube and Vimeo support custom player controls, using a plugin like Plyr. You may choose to use custom video controls, to give your embedded video's a bit more professionalism. Per the setup instructions for Plyr, add a CSS call to the top of your page:

<link rel="stylesheet" href="path/to/plyr.css">

Then before your TopBox Javascript code at the bottom of the page, call your Plyr script:

<script src="path/to/plyr.js"></script>

The final stage is to initiate the Plyr plugin, when TopBox is opened. This is done by passing the Plyr initialisation through our afterShowLightbox hook, like this:

$(document).ready(function() {
	$('.lightbox').topbox({
		skin: 'darkroom',
		afterShowLightbox: function(lightbox){
			const player = new Plyr('#player', {
				/* Player options */
				autoplay: true
			});
		}
	});
});

Now you should find that HTML5, YouTube and Vimeo video are shown with customisable player controls. Other video types (like Dailymotion, Brighteon and TED) are not supported by Plyr, and we'll display their standard player controls, as normal.