The TopBox stack has existed for many years. Version 5 (the latest version) brings major changes including:
TopBox has also gone open source. This means the codebase is open to anybody wanting to make improvements and share those changes back with everyone else. Versions of TopBox that work with other publishing platforms are already under development. TopBox is going primetime!
- A huge amount of work has been done to extensively re-write much of the underlying codebase for TopBox. Not only does this mean TopBox will be totally jQuery v3 compatible going forwards, but it has provided an opportunity to scrap a lot of older hacks and messy prefixes for obsolete web browsers.
- Smartphone and tablet devices now equate to the vast majority of traffic visiting websites. With this in mind, TopBox works better on these devices and brings brilliant features like swipe support for gallery sets.
- Four methods for changing the appearance of your TopBox stacks. 1) Choose from any of 25+ preset skins. 2) Use the 'DIY' option to quickly edit the default skin. 3) Use custom CSS code in the page to override TopBox code. 4) Use a code editor to design your own skin and load it into TopBox. Powerful styling methods to suit all levels of customisability and skill!
- Big emphasis on making TopBox more accessible, which is often a substantial downfall of many lightbox and modal effects. TopBox places ARIA labels on triggers and lightbox content. It will also 'lock' tab focus when the lightbox opens and return it seamlessly back to the page afterwards when closed again.
- Support for many more different content types. So in addition to what was previously offered, you now have Dailymotion, SVG, TED Video, Brighteon, PDF embed and WebP image support, to name a few. The new 'iframe-video' type is perfect for other video like Twitch, Wistia and Vidyard. Plus improved support for stacks dragged and dropped into TopBox, like Image and Site Image stacks.
- HTML5 audio, HTML5 video, YouTube and Vimeo content can now be presented with custom video controls. Gorgeous, customisable player controls that fade in and out of view and display only the the most essential controls to your end users.
- An all-new complimentary 'TopBox Dialog' stack. This free stack can be placed inside TopBox (with the TopBox content type set to 'Stacks') and allows you to create beautiful dialog message popups for items like terms and conditions, a newsletter signup, shopping cart buttons, social media sharing buttons, and various other tasks.
TopBox has also gone open source. This means the codebase is open to anybody wanting to make improvements and share those changes back with everyone else. Versions of TopBox that work with other publishing platforms are already under development. TopBox is going primetime!
Examples
Here are some great examples of what the TopBox stack can do. Click the buttons to open TopBox:
Not demonstrated here, but TopBox can also do AJAX loaded content too, for more sophisticated websites and webapps.
On smartphones and tablet devices, the embedded PDF example gets replaced with a download button. This is because iOS handles PDF files as images, and will only ever show the first page of a PDF. Providing the ability for a user to download the PDF file and open it on their device circumvents this problem.
You can also group TopBox stacks together, to create one or more gallery sets. When a TopBox is allocated to a gallery set, it gains next / previous navigation and swipe navigation support on touch devices. This example places 5 TopBox stacks into a group:
As you can see, you only need to have the first button shown, to start the gallery. The images do not play like a slider in sequence, so this configuration makes a good web gallery for people to browse at their own pace.
Setup
For users migrating from TopBox v4 or earlier, the biggest change you will see in TopBox v5 is that there's now three separate stacks, as opposed to the previous one. This makes TopBox v5 far more 'code efficient' and should also speed-up your deployment of TopBox in websites. TopBox is now compatible with Partials, Templates and Externals in Stacks 4. For anybody new to TopBox, you should find its setup and deployment relatively easy, in comparison with other stacks.Start by adding a 'TopBox 5' stack to your webpage. This stack contains the bulk of the complicated Javascript and CSS code needed to make TopBox work. In the settings for this stack, you can toggle the display of setup instructions shown in edit mode, customise the visual appearance, adjust localisation for the interface and change any core functionality. You should only add a single 'TopBox 5' stack to each page. The settings you change in the 'TopBox 5' stack will apply to all TopBox lightbox or modal effects on that webpage.
At this point, you already have TopBox installed and working on your webpage. If you follow the instructions for manually triggering a TopBox below, it is feasible to manually code buttons or links to open your destination content within TopBox. However we envisage a lot of people will prefer to use the 'TopBox Trigger' stack instead. Add one or more of these stacks to your webpage. You will find that these stacks create a linked area on the webpage to receive a mouse click or finger tap. And you are presented with an area to configure the content you want shown in the TopBox. Of note, TopBox supports many dozens of different content types, so it is worthwhile exploring these different content types available for you to use.
The final stack worth mentioning is the 'TopBox Dialog' stack. This optional stack is designed to go inside the content area of a 'TopBox Trigger' stack, when you have changed the content type to 'Stacks'. The purpose of our 'TopBox Dialog' stack is to provide all the necessary style and functionality controls required to convert a TopBox lightbox into a popup modal / dialog window. This stack can automatically hide normal navigation controls. You can find lots of settings to change the visual appearance of your dialog window.
Manually triggering (opening) a TopBox
This is an alternative to using the supplied 'TopBox Trigger' stack. You can use any HTML link to open a TopBox. If using a third-party button stack, please be aware that some button stacks can be slightly misleading in their function; in that they may display options to supply custom attributes, but never actually write the custom attributes into the page source code! So when opting to use your own button stack, just make sure it supports custom link attributes. Ask the developer, if in doubt.Our EZ Flex Button, ImageWizard, GhostButtons and ButtonMaker stacks are TopBox compatible. The HoverVid stack is great for playing a little video clip on mouseover, and letting the user click the thumbnail to view a full video within TopBox.
Set the URL of the link to the item you want to open. For example, this could be a link to a full-size image, an MP4 video file, a PDF file, a YouTube video or the ID of a page
<div>. If you are using the RapidWeaver Link Dialog window to configure you links, then a typical YouTube link to open inside TopBox might look something like this:
You can hopefully see in this above screenshot how we set the link to our YouTube video, together with custom attributes. The
class custom attribute is used to identify this link as a TopBox trigger and has a value of lightbox. The title custom attribute is optional, and allows us to display a title caption below the lightbox content. There is no need to set the link to open in a new window.Likewise if you were working with links coded with HTML markup, the same link above may look something like this instead:
<a href="https://youtu.be/2xX7RrxyRac" class="lightbox" title="Ben's Party">My video</a>There are other custom attributes you can add to TopBox links or buttons. For example, grouping multiple links together into TopBox sets or providing more specific information about the type of content you are trying to open. The table below illustrates all the available custom attributes available for use.
| Name | Value | Description |
|---|---|---|
| title | My TopBox | Optional - the title of the TopBox, normally shown in the lightbox below the content. |
| data-lightbox-gallery | myGallery | Optional - used for grouping multiple TopBox stacks together with previous / next buttons. |
| aria-haspopup | dialog | Recommended - tells screen readers and other accessibility tools that the link will open a dialog or lightbox window. |
| data-lightbox-type | iframe | Required - if you need to open a webpage or PDF file within an iFrame. |
| data-lightbox-type | AJAX | Required - if you need to open a text file as an AJAX request. |
| data-lightbox-type | inline | Required - for opening a hidden <div> on your webpage within TopBox. |
| data-lightbox-type | video-iframe | Required - for opening a video within an iFrame embed (e.g. Wistia or Veoh). |
If you need to change the class selector name used for trigger TopBox (like if you want to recycle the triggers used for a previous lightbox you used) it is possible to change this in the main TopBox stack Advanced Settings > TopBox Selector. Replace the default value of
.lightbox with your own ID or class selector name. Changing the selector name here does not effect instances of TopBox setup with 'TopBox Trigger' stacks (these run-off a private selector name).TopBox styles
TopBox comes with at least 30 ready-made skins (or themes) ready for selection in the stack settings. These save you the time and trouble of tediously working-through potentially hundreds of style settings to create your own lightbox design. Simply select the skin name from the select menu, and all your TopBoxes on the page will be automatically styled to that design. This makes deployment of professional looking lightboxes and modals really quick and easy.The 'DIY' (do it yourself) skin option is derived from the default 'Darkroom' skin. This provides you a couple of basic style and colour settings to customise. This is a good option to use if the style of the lightbox is not of paramount importance to you, but you still want to change a few simple aspects of it yourself without needing any CSS code!
If you want to custom design your own lightbox (or modify one of the listed skins) with far greater design freedom, this is still perfectly feasible to do. TopBox has a 'Custom' skin option. When this special skin is chosen, you are presented with settings to enter the name of your new skin and link to its CSS file.
The easiest way to create a new skin is to download the TopBox source code from Github. Look in the /src/skins/ directory. You will see that each skin lives inside its own directory. So you can duplicate one of these existing skins, give it a new name, and open it in your preferred code editor. TopBox skins all use regular CSS (nothing complicated or requiring a pre-processor). If you have some basic knowledge of CSS, then you should encounter no difficulties with making modifications to the CSS. Do a search and replace of the existing skin name and give it a new one (e.g. change 'blue_hue' to 'super_skin') in the CSS file. And again you would use 'super_skin' in the TopBox settings, if that was what you were naming your new skin.
Because each skin lives inside of its own directory, it is possible to add additional assets. These could include custom images, embedded fonts, background patterns and other files. Once done, upload the directory to your web server or drag and drop it into RapidWeaver as a resource. Within the TopBox custom skin settings, link to your CSS file and enter the corresponding name of your new skin.
It's worth noting that all skins share the same HTML codebase. So if for example you just wanted to change something quick (like the colour of the backdrop window shade) it can often be feasible to do this with custom CSS added to your page like this:
.topbox_overlay {
background: red !important;
}
We can also be hired to create custom skins on your behalf. Please get in touch to discuss availability and costs.
Custom close buttons
You can force a TopBox stack to close, by means of clicking (or tapping) a link or button within the TopBox stack. This link or button simply requires aclass attribute with a value of topbox_dismiss. This can be useful when constructing a custom dialogue window or popup. You could give your 'close' button or 'cancel' button a topbox_dismiss class, which would do the same as clicking the regular close button on the lightbox.Another approach (if using the TopBox Dialog) is to place CookieManager or MiniCookie stacks in here, to capture button presses. Then you can use cookies to remember what option someone has clicked.
