Clearing

Since we didn't intend Orbit to handle variable-height content, we decided to create a plugin that would. Clearing makes it easy to create responsive lightboxes with any size image.

Build Your Clearing Lightbox

There is only one way to build a Clearing lightbox, using our predefined class and data-attribute structure. We've made it really easy: gather some images, decide on their order, and put them into an ul with a .clearing-thumbs class. In order to get Clearing to build itself properly, you'll need to have JavaScript properly included. We outline Clearing JS a bit further down the page.

Once you get your JS hooked up, you'll need to add data-clearing to your list container. Here's an example of the most basic markup needed:

HTML

<ul class="clearing-thumbs" data-clearing>
  <li><a href="path/to/your/img"><img src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img"><img src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img"><img src="path/to/your/img-th"></a></li>
</ul>

Styling the List

We're using the .th class from Foundation to style the thumbnails in the Clearing example at the top of the page. You can also use @include thumb; in SCSS to use those same styles.

Using Responsive Images

To use responsive images add data-clearing-interchange to your links:

HTML

<ul class="clearing-thumbs" data-clearing>
  <li><a href="path/to/your/img" data-clearing-interchange="[path/to/default/img, (default)], [path/to/bigger/img, (large)]"><img src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img" data-clearing-interchange="[path/to/default/img, (default)], [path/to/bigger/img, (large)]"><img src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img" data-clearing-interchange="[path/to/default/img, (default)], [path/to/bigger/img, (large)]"><img src="path/to/your/img-th"></a></li>
</ul>

The rules for the interchange list are the same as described in the Interchange documentation.

Start From a Featured Image

Sometimes you don't want to show a gallery full of images on your site, but you want to open the gallery from a single image. By including all of your images in a .clearing-feature list and using .clearing-featured-img on the <li> of your choice, you'll be able to hide the rest of the images in the on-page gallery. If you want to show more than one, try using our .hide class to set the ones you don't want to display: none;.

HTML

<ul class="clearing-thumbs clearing-feature" data-clearing>
  <li><a href="path/to/your/img"><img src="path/to/your/img-th"></a></li>
  <li class="clearing-featured-img"><a href="path/to/your/img"><img src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img"><img src="path/to/your/img-th"></a></li>
</ul>

Including Captions

Another common use-case for Lightboxes is to include a caption per image. We've made this quick and easy by using data-attributes to hold the content. You'll just attach this attribute to the image it belongs to and voila! Here's the code example:

Note: You can now use HTML inside the data-caption attribute.

HTML

<ul class="clearing-thumbs small-block-grid-4" data-clearing>
  <li><a href="path/to/your/img"><img data-caption="caption here..." src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img"><img data-caption="caption 2 here..." src="path/to/your/img-th"></a></li>
  <li><a href="path/to/your/img"><img data-caption="caption 3 here..." src="path/to/your/img-th"></a></li>
</ul>

Accessibility

This component is not yet accessible. Stay tuned for updates in future releases.

Available SCSS Variables

We opted not to create mixins for this plugin because it relies on classes in the JS to work. These variables should give you the control you need to change styles as you see fit:

SCSS

$include-html-clearing-classes: $include-html-classes;

// We use these to set the background colors for parts of Clearing.
$include-html-clearing-classes: $include-html-classes;

// We use these to set the background colors for parts of Clearing.
$clearing-bg: $oil;
$clearing-caption-bg: $clearing-bg;
$clearing-carousel-bg: rgba(51,51,51,0.8);
$clearing-img-bg: $clearing-bg;

// We use these to style the close button
$clearing-close-color: $iron;
$clearing-close-size: 30px;

// We use these to style the arrows
$clearing-arrow-size: 12px;
$clearing-arrow-color: $clearing-close-color;

// We use these to style captions
$clearing-caption-font-color: $iron;
$clearing-caption-font-size: 0.875em;
$clearing-caption-padding: 10px 30px 20px;

// We use these to make the image and carousel height and style
$clearing-active-img-height: 85%;
$clearing-carousel-height: 120px;
$clearing-carousel-thumb-width: 120px;
$clearing-carousel-thumb-active-border: 1px solid rgb(255,255,255);

Using the Javascript

Just add foundation.clearing.js AFTER the foundation.js file. Your markup should look something like this:

HTML

<body>

  ...

  <script src="js/vendor/jquery.js"></script>
  <script src="js/foundation/foundation.js"></script>
  <script src="js/foundation/foundation.clearing.js"></script>
  <!-- Other JS plugins can be included here -->

  <script>
    $(document).foundation();
  </script>

</body>

Required Foundation Library: foundation.clearing.js

Optional Javascript Configuration

Clearing supports data-options on-the-fly configuration:

JS

{
  // specify the classes or IDs will close clearing when clicked.
  close_selectors : '.clearing-close',

  // specify the classes or IDs that will open clearing when clicked, defaults to the entire li element
  open_selectors : '',

  // specify the classes or IDs that will be skipped in carousel
  skip_selector : '',

  touch_label : '← Swipe to Advance →'
}

Available Javascript Events

Clearing supports several javascript events that you can listen to:

• open.fndtn.clearing before a thumbnail is expanded
• opened.fndtn.clearing after the large image has opened
• close.fndtn.clearing before the large image is closed
• closed.fndtn.clearing after the large image has closed
• change.fndtn.clearing when the large image changes
• resized.fndtn.clearing after the large image is resized, before it becomes visible

Here is an example of binding to the open event.

JS

$(document.body).on("open.fndtn.clearing", function(event) {
  console.info("About to open thumbnail with src ", $('img', event.target).attr('src'));
});

Adding New Clearing Content After Page Load

If you add new content after the page has been loaded, you will need to reinitialize the Foundation JavaScript by running the following:

$(document).foundation();

Reflow will make Foundation check the DOM for any elements and re-apply any listeners to them.

$(document).foundation('clearing', 'reflow');

Sass Errors?

If the default "foundation" import was commented out, then make sure you import this file:

SCSS

@import "foundation/components/clearing";