What is MBBox?
MBBox is a jQuery based lightbox that supports IE9+ and all major browsers, as well as mobiles.
MBBox was developed at MBMedia for usage in client projects and premium projects for sale. It turned out to be so versatile and easy that we’re releasing it here for public usage under the very permissive MIT license, for free. Not to mention, (as of V 2.0.0 anyways) It’s about 10 kb minified. That’s a lot of power for not a lot of weight.
It supports a myriad of features, from showing images to URLs in iframes to embedded iframe video (automatically detecting YouTube and Vimeo videos and handling them appropriately).
It can be switched from dark to light themed with the switch of a property, is object oriented, has pagination, supports mobile swiping for large galleries, is retina ready with simple universal svg graphics that go with any design, etc. etc. I’ll get into the features now. This page can, for all intents and purposes, be considered the documentation for MBBox.
How to Use
When you open up the download you’ll notice an mbbox folder. The intent is that you put that entire folder up on your server and import mbbox/mbbox.js, mbbox/mbbox.css, etc. So let’s look at an example. Let’s say we have some HTML that looks like this:
<!DOCTYPE html> <html> <head> <title>Fake Page!</title> </head> <body> <div class="gal"> <a href="feature-image1.png" title="A Title">Item 1</a> <a href="https://www.youtube.com/watch?v=ngElkyQ6Rhs">Item 2</a> <a href="https://vimeo.com/137925493">Item 3</a> </div> </body> </html>
To make the lightbox apply itself to all 3 of those
<a> tags all we’d need to do is call
mbbox.initialize('.gal a'); Notice that you just pass a jQuery-like selector string to tell it what to apply itself to. You can also just pass a jQuery object itself. You can call it on a page load event, or just place it after the markup you want it applied to. So at the end it looks something like this:
<!DOCTYPE html> <html> <head> <title>Fake Page!</title> <script src="wherevermyjqueryis/jquery.min.js"></script> <script src="mbbox/mbbox.min.js"></script> <link href="mbbox/mbbox.css" rel="stylesheet" type="text/css"> </head> <body> <div class="gal"> <a href="feature-image1.png" title="A Title">Item 1</a> <a href="https://www.youtube.com/watch?v=ngElkyQ6Rhs">Item 2</a> <a href="https://vimeo.com/137925493">Item 3</a> </div> <script>mbbox.initialize('.gal a');</script> </body> </html>
If the selector you pass matches a bunch of elements then it’ll make a gallery of all of them and have pagination buttons, etc. If it matches only 1 element then it’ll just set up to open that 1 element without any pagination type features showing.
Notice that to embed a YouTube or Vimeo video all you need to do is put the URL to the video. Even for users with JS turned off they’ll still go to the video. And notice the title attribute on the first item. That one will show with a title.
It is also perfectly legit to call
mbbox.initialize(selector) multiple times. For example, if you’ve got multiple galleries on one page you can set it up so that it initializes them on the fly so that there’s multiple “groups” of pagination.
More Advanced Usage
You can also work the MBBox totally from script as well. You do still need to call
mbbox.initialize(); before you can open the lighbox, but you just don’t pass it any parameters.
For such usage we have a number of functions. This basically leaves the “tutorial” phase of this page and enters into “documentation".
- Public Static Methods -
mbbox.initialize([selector]) - Initializes the MBBox. Must be called after the setting of mbbox properties (those are explained later) and before actually opening the lightbox. The selector may be a jQuery selector like string or a jQuery object itself. It may be left blank if initializing with the intent of opening the lightbox programmatically instead of with user interaction.
mbbox.show(url, [title], [pagination]) - Once
mbbox.initialize is called with no parameters (for opening single items at a time programmatically) this can be used to manually open an item. You can include a title and you can also send the pagination parameter and determine the exact text that will show in what is normally the pagination field.
mbbox.hide() - Closes an open MBBox. The user will still have the ability to close it, but this gives you the added ability to do it programmatically.
- Public Static Properties -
mbbox.theme [String default=’light’] - Determines a class that will be added to the CSS to allow different styles to be applied for a different look. Specifically it adds
.mbtheme-themestring. The two theme strings supported with the included CSS are
mbbox.useArrowKeys [Boolean default=true] - Determines if a paginated gallery will accept arrow key input to navigate.
mbbox.useEscapeKey [Boolean default=true] - Determines if pressing the escape key will close the lightbox.
mbbox.useMouseWheel [Boolean default=true] - Determines if a paginated gallery will accept mouse wheel movements to navigate.
mbbox.margin [Number default=70] - Set this before initializing to determine the minimum margin that is left around the lighbox image when opening one that is too large for the current viewport. Keep in mind that the title/pagination/button controls show outside of the image and need some space to show. This does not account for them automatically, so if you need to show those things use a number high enough to leave space for them. If the image is not too large for the viewport then this number does nothing.
mbbox.showPaging [Boolean default=true] - Used to determine if the “1 / 12” type paging text appears when a paginated gallery is in use.
mbbox.useHistory [Boolean default=false] - Determines if a #hash fragment is added to the URL on open, and will close the box if removed (basically allows the back button to close the lightbox; going forward again won’t reopen it though).
mbbox.titleAttribute [String default=’title’] - When initializing with a selector this determines what attribute it will take the title from. By default it just looks for a title attribute, but you could change it to look for a custom HTML5 attribute if you want.
mbbox.featureAttribute [String default=’href’] - When initializing with a selector this determines what attribute it will take the URL to the intended lightbox feature image/video/iframe from. By default it just looks for a href attribute, but you could change it to look for a custom HTML5 attribute if you want.
mbbox.defaultWidth [Number default=640] - When opening video/iframes this will determine the default size that is used for URLs that don’t declare one with a GET var (which is something that gets explained later).
mbbox.defaultHeight [Number default=360] - When opening video/iframes this will determine the default size that is used for URLs that don’t declare one with a GET var (which is something that gets explained later).
mbbox.assumeAbsolutePathsIframe [Boolean default=false] - Determines if every absolute URL (i.e. one that starts with http:// or https:// as opposed to a relative URL) is assumed to be intended as an iframe. By default this is false and you determine if something opens as an iframe via a GET variable in its URL, which is explained further down the page.
mbbox.debug [Boolean default=false] - For devs messing with stuff you can turn this on and it will log data about what’s going on.
- URL Variables -
The URL to the feature content can be used to specify some settings for that particular item via GET variables.
isIframe=true - Will make it open the URL in an iframe.
lightboxWidth=500 - Will make it open a URL or video iframe with a specified width.
lightboxHeight=400 - Will make it open a URL or video iframe with a specified height.