Creating a Fancybox Gallery

Fancybox is a feature-rich lightbox library for presenting photo galleries. This tutorial shows you how to integrate Fancybox 3 with Surreal CMS using code you can copy and paste.

frame

Requirements

Installing Fancybox

There are two ways to install Fancybox. One is to download it and host the files yourself. The other is to use a content delivery network (CDN). In this tutorial, we'll be using the popular CDNJS.

Add the Fancybox stylesheet by placing the following inside the <head> section of your page.

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/fancybox/3.5.7/jquery.fancybox.min.css" />

Add these scripts just before the closing </body> tag. If the page already has jQuery, omit the first line!

<script src="https://code.jquery.com/jquery-3.3.1.min.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/fancybox/3.5.7/jquery.fancybox.min.js"></script>

Congratulations! You've installed everything you need to make Fancybox work on your page. Now we just need to make it work with Surreal CMS.

Integrating Fancybox

The Fancybox documentation tells you to use certain attributes to initialize it, group photos, show captions, etc. You don't need to do that because we're going to use a script that does it for us. Just create your galleries like you normally would without any proprietary attributes.

You can either copy and paste the following script directly into your page or include it from a separate file (recommended if you're using galleries on more than one page).

Make sure to include the script before the closing </body> tag, but after jQuery and Lightbox.

<script>
  $(function() {
		// Set your custom Fancybox options here. See http://fancyapps.com/fancybox/3/docs/#options
		$.fancybox.defaults.animationEffect = "zoom";
		$.fancybox.defaults.transitionEffect = "slide";

    // Initialize Fancybox on all galleries (but not if we're in the editor)
    if (!window.isCMS) {
      var i = 0;
     	$('.cms-gallery, .cms-editable[data-type="gallery"]').each(function() {
        var gallery = this;
        i++;

        $(gallery).find('a').each(function() {
          var a = this;
          var img = $(a).find('img');
          var caption = $(img).attr('data-caption');
          var alt = $(img).attr('alt');

          $(a)
            .attr('data-fancybox', 'gallery-' + i)
            .attr('data-caption', caption);
        });
      });
    }
  });
</script>

Notice

If you're using the deprecated .editable-gallery syntax, you'll need to change the jQuery selector that loops through each gallery to $('.editable-gallery').

You might notice the window.isCMS conditional — this is one way we can detect the CMS. We're basically telling Fancybox to run on the live webpage, but not in the editor. (We don't want the gallery popping up while we're trying to edit!)

That's it! Now your page is ready to show off its first Fancybox gallery.

Licensing

Fancybox 3 is available to use under the GPLv3 software license. For commercial applications, a commercial license is required. For Surreal CMS users, Fancybox is generously offering 10% off single commercial licenses and 10% off extended commercial licenses.

If you're having trouble getting Fancybox to work, feel free to contact us for help.