Lightbox

This component allows you to build dynamic lightboxes visually in Oxygen. The contents of the lightbox is added dynamically on the page. This allows for adding custom HTML, content from other posts/pages via AJAX, showing iFrames (parts of pages) or simply building image lightboxes for existing galleries or carousels you already have on the page.

Can be used inside/with repeaters to pull in content/data dynamically from other posts & pages.
Provides a simple way to load video/image lightboxes that only load on click.
Can be used to replace the modal that is triggered with a click (has better animation control & doesn’t suffer from the overflow issues)
Visually style all aspects of the lightbox.

Quick preview of the component in action

There are currently five parts to this video, we’ll be adding more use cases.

Screencast showing how to visually build a grid of thumbnails using Oxygen’s Repeater component. Clicking on a thumbnail will open the corresponding video in a Lightbox.

We are going to use Advanced Custom Fields Pro version and set up a Repeater-type of custom field having three sub fields: Video, Title and Image.

Getting Started

For the most part, the workflow is backward compared to how you create a modal – Instead of adding in the contents using elements inside the component and choosing a trigger from the settings, the click trigger is placed inside of the component in the structure panel and then the contents of the lightbox is configured in the settings.

This is because the content that is loaded inside of the lightbox is dynamically added to the page when it’s triggered.

The only exception to this is if you’re choosing ‘inline’ as your content source and also choosing ‘display elements inside lightbox’. (The only instance where you are likely to need to find this option useful is if you’re inside of a repeater and you wish to create a custom design built with custom elements)

Choosing the Trigger & Content source

For each lightbox, you need to be able to answer these three questions to know the best way to configure..

1. What is the click trigger?

For single lightboxes where the trigger is one element, the best way is to wrap the element inside a lightbox component like you would with a link wrapper.

If the click trigger is going to be a link inside a different component, like an Easy Post or Carousel or Gallery, you can use the selector of the links (the ID or class) to tell the lightbox what the trigger is. (Manual mode).

2. What content needs to display?

Are you wanting just an image or video, or is it content that exists already on the page, or another page that you wish to display?

3. What’s the best source for this content?

You can often show the same thing, in a number of different ways, so it’s important to know the differences.. see below for description and benefit of each source type.

Each content type is useful for different situations.

AJAX

This settings allow you grab HTML from a particular part of another post or page on your site. If you’re just needing images, text from another page and not needing any dynamic elements that require code blocks or JS libraries to function, AJAX is a good option.

The benefit of AJAX is that the content loads pretty quickly as you’re only fetching the HTML. (If you need the CSS from the other page to also load because there are some page-specific styles, there’s an option to load that CSS also in the config settings).

iFrame

This will pull in the entire contents of the URL you provide. If you’re using a URL that is part of the same domain (eg just another page on your site) then you also have the option to only display part of the page inside the lightbox using the selector of the container.

The benefit of iFrame is, all the assets needed for more dynamic elements will be available. So everything will look & work exactly the same as it does on the original page.

Screencast (no sound)

Image / Video

The allows for dynamic loading of both Youtube & Vimeo videos.

The benefit of just pulling up the image or video direct from the URL is that you don’t need them to already be output on another page (like is true for iFrame & AJAX)

Inline

Inline is for any elements or containers that exist on the current page.

There are two options;

Display elements inside the lightbox – You’ll be placing the elements that you wish to appear inside the lightbox, inside of the component itself in the structure panel. Similar to how you’d add elements inside of a modal.

Another element on page – You’ll be adding in the ID of an other element on the page that is hidden, but the contents of which you wish to display inside the lightbox.

The benefit of inline is that it’s the fastest option in terms of loading, as the element isn’t coming needing to load from an external source. It’s also useful for inside repeaters as the inline elements can have dynamic data added to them from inside the repeater query.

Manual

To cover all use cases, manual mode allows you to tell the lightbox to follow any links on the page by using just their selector (class or ID). This means existing components such as Easy Posts, Product List, Repeaters, Galleries, or elements from third party plugins etc can have your custom lightboxes added to them.

Generally, the lightbox will follow the href of the links you give the selector for. So for galleries, if the images are linking to the image file, the lightbox will contain the full images. Using Oxygen’s dynamic data options, this means you can store the data in custom fields and only load the contents up when the user clicks a specific element.

Likewise, for post loops where there may be links to the post URL, this can be used to either fetch content via AJAX or via iFrame. (Note – with both AJAX & iFrame you’ll need to manually tell it which one you want, see the ‘force content type’ setting).

Grouping

When attaching the lightbox to galleries or elements inside a loop (say from a repeater, easy posts or a code block) you may want to make the content from each accessible to the user by sliding from left to right.

Enabling grouping with display navgiation arrows that can be customised in the navigation tab.

Config Settings

Small close button – Aswell as the large close button inside the toolbar, there is the option to include a small close button inside of the lightbox content.

iFrame Preload – Enabling the preloading of the iFrame before it is displayed is what allows us to use features such as auto-height and only showing part of the iframe with a selector. This is recommended to remain enabled unless you have your own reasons for disabling.

Iframe auto height – If enabled, will ensure the lightbox content will take up the exact height of the iframe, to prevent the user needing to scroll the content.

Infobar – Displays or hides the infobar that appears inside the lightbox on the top left of the viewport. It’s used to show the pagination number if you’re grouping together elements as slides.

Include Page/Template CSS – Useful if you’re adding content via AJAX and need some of the styling from another template CSS file. (A better way is to avoid using IDs when styling so the CSS is all global and this setting isn’t needed)

Prepend in footer – If needing to add lightboxes inside containers that have transformed applied (such as inside carousels, or inside sections that have scroll animations) then you can enable this to make sure the actual lightbox content is outside of this container when the lightbox is revealed. This will ensure the fixed positioning isn’t effected when the lightbox is opened. Note that it’s important to style the lightbox using a class if using this option, not by ID.

Video Aspect Ratio – Videos from Youtube & Vimeo will take up the width of the lightbox content, the height is determined by the aspect ratio chosen here.

Focus Controls – Control what happens to the user focus when the lightbox is triggered. By default..

The focus will jump to the first focusable element inside of the lightbox, eg a link, input or button.
The focus will remain trapped inside of the lightbox until it’s closed.
The focus will return to the previous element when it’s closed

With the in-builder visibility set to visible. The lightbox can be styled inside Oxygen using familiar style controls.

Note – the width & height can be left blank for auto height.

For AJAX & inline, the height will be determined based on the content inside. This is also true for iFrame if auto height is enabled in the config settings.

Content spacing – Refers to the lightbox content itself.

Slide spacing – Refers to the actual slide, containing the content. This is taking up the entire viewport. Change the padding here to prevent the content from being too close to the edge on smaller screens. There’s a default of 20px already applied for convenience.

Navigation arrows

These arrows will only be visible when grouping into slides. The icons can be changed and styled to taste.

These are the controls for the toolbar in the top right of the viewport in the lightbox.

The icons are dynamic, so for eg the zoom and the download options will only show if the lightbox is currently showing an image. But inside Oxygen they’re all visible for easier styling (or disabling completely).

Animation

The reveal animation can be customised by setting the starting position of the lightbox when it’s hidden. (similar to how the mega menu animations work).

For eg.. if you wish for the lightbox to start very small and at further down the page, then you’d set the Translate Y to say 400px and then scale to 0.5.

Tips & Tricks

If wanting to include more dynamic elements inside lightboxes, such as carousels, counters, etc that will need JS files to function. Stick to using either iFrame or Inline as the content source. This way the correct JS libraries are already there.
If using AJAX to pull in some content from an existing page, the styles will be preserved where you’re using classes, but not with IDs. This is because styles added via ID are page specific and will only load on that particular page where the content is. If you’re using classes mostly, then it’s all global so it won’t make a difference. If you do need some extra styles to load in the lightbox, see the config > include page/template CSS.
If using iFrame to pull in a page from your site and you wish to include some extra styles that are not found on the original page, we’ve added a class ‘extras-inside-lightbox’ to the html. This means you can target the elements ONLY when they appear inside the iframe.

Tutorials

Other Info

API to control the fancybox, the script used by the component.