Integration

Photo galleries

You can make a photo gallery editable using the editable-gallery class. If you apply it to a block-level element such as a div, Surreal will output the following HTML structure:

<div id="my-gallery" class="editable-gallery">
    <a href="full.jpg"><img src="thumb.jpg" alt="Description"></a>
    ...
</div>

If you apply it to a ul or ol, the structure will also contain list items:

<ul id="my-gallery" class="editable-gallery">
    <li><a href="full.jpg"><img src="thumb.jpg" alt="Description"></a></li>
    ...
</ul>

Other elements and attributes added to the gallery are not supported and will be stripped out. However, most Lightbox-style galleries and sliders can work with this structure or be shimmed to work pretty easily with JavaScript.

Thumbnails

To have the CMS automatically generate thumbnails, add the following data- attributes to the container:

<div id="my-gallery"
    class="editable-gallery"
    data-thumbnail-width="100"
    data-thumbnail-height="75"
    data-thumbnail-resize="best-fit"
>

Valid options for data-thumbnail-resize are best-fit and trim. When set to best fit, thumbnails will be resized proportionally to fit inside the specified width and height. When set to trim, thumbnails will be resized and trimmed to the specified dimensions.

Thumbnails are only generated when photos are added to the gallery. Existing photos will not be replaced, regardless of their size.

Links

If you don’t want the photo gallery editor to wrap links around each image, you can disable them by adding the following data attribute to your gallery:

<div id="my-gallery"
    class="editable-gallery"
    data-links="false"
>

Integrating with JavaScript plugins

One of the problems with developing a photo gallery editor is that there are a multitude of JavaScript-based galleries and sliders to support. Many of them require a different syntax or code structure to work properly, so it’s impossible for us to generate HTML that will work universally.

We ended up choosing a simple, semantic approach to the markup our photo galleries use. As a result some plugins will work fine out-of-the-box, but others will need a shim since they require certain elements or attributes that won’t be present in the code that Surreal generates. Fortunately, this is pretty easy to do with JavaScript.

Start with a semantic structure

Your photo gallery needs to be structured like one of the two examples shown above. Don’t bother adding additional markup or special attributes because they’ll be removed when you edit the gallery. Just use the closest one that works with your favorite plugin.

Disable it in the CMS

You don’t want your gallery popping up as you try to edit it, so make sure you disable it in the CMS. You can use any of the tips on that page, but the easiest is probably with our special HTML comments.

This is critical for plugins that change your gallery’s HTML. If you don’t disable them, the CMS may publish the resulting changes and prevent your gallery from working.

Shim the markup

If your plugin works with the markup shown above, you don’t need to do anything else. Otherwise, you’ll need to apply a shim before the plugin gets initialized. A shim is just a small snippet of JavaScript that alters the HTML so it works with your favorite gallery or slider.

For example, Lightbox 2 requires each link to have a data-lightbox attribute. Fancybox requires a fancybox class. We’ve written a few tutorials that show how to shim some of the more popular plugins:

If you have any trouble with this part, just send us a help request with a link to the plugin you’re using and we’ll help you out.