Category: JavaScript

A client was recently looking for options to improve on SharePoint’s OOB ability to display pictures. One way to do this is to use jQuery and SharePoint’s REST API to connect a Picture Library to one of several jQuery gallery libraries that generally provide lots of display options (most of them are responsive as well which is very cool in this cloud-first, mobile-first world).

I did the following example using an image gallery plug-in called UniteGallery (http://unitegallery.net), but a similar approach of dynamically getting the images from a SharePoint REST query should work with other gallery/lightboxes as well. (For example, this one also looks promising but I haven’t had a chance to try it yet: http://andreknieriem.de/simple-lightbox/ ).

Picture Library Basics

Picture Libraries in SharePoint 2013 and SharePoint Online (Office 365) make it easy to drag and drop pictures into the library where they then can be tagged with metadata, sorted, filtered, versioned, etc. SharePoint Picture Libraries also provide some basic views of images including list views, and thumbnail views, and a basic slideshow capability. To improve performance of SharePoint own UI components, SharePoint automatically creates a thumbnail and a midsize version for each uploaded picture and uses those in their UI.

Also for performance reasons, most of the image lightbox and gallery plug-ins I found had the option to specify a separate thumbnail file to render in the gallery view. Of course, this requires that separate, thumbnail-sized images have been created for each picture. Doing it manually would be an extra amount of work for each image but the result is better performance. If we take advantage of the automatically generated thumbnails that SharePoint generates, we can improve performance without adding any extra work for the person uploading the pictures.

[BTW, the FTG URL’s in this article are not publicly accessible … just meant to illustrate a real world example running in a typical O365 environment].

After uploading an image (or maybe during the upload?), SharePoint generates the additional thumbnail and midsize images. The thumbnails go in a subfolder named ‘_t’ that’s located directly under the picture library. The midsized images go in their own sub-folder called ‘_w’ (also a direct child folder of the picture library).

Since the thumbnails and midsize images are stored in separate folders they can each be named the same, which is how SharePoint in fact does it. The filename is constructed by taking the picture’s original file name without the extension, followed by an underscore, followed by the original file extension, followed by .jpg as shown here:

PictureFilenameNoExtension_OriginalFileExtension.jpg

For an example, the original flower picture in the library above is named IMG_1368.jpg and is 2592 x 1936px.

I uploaded both JPG and PNG files and the thumbnails and midsize images generated for both of them were in the JPG format. So SharePoint appears to generate JPG images regardless of initial image type. For example, if you start with a .PNG file called Sample.png, the auto generated thumbnails and midsize images would be JPG images called Sample_PNG.jpg.

If you need to handle images files with 4-character extensions (e.g. JPEG) you’ll need to add a little extra logic to the javascript below to test for that case. As an example, a image named Image01.JPEG would be named Image01_JPEG.jpg after conversion. (I bumped into this once but eliminated that test to focus the code on getting the images and feeding them to UniteGallery).

I used the free version of UniteGallery in this article, and they have a ton of paid “themes” that can style a gallery every which way. From their home page, you can display a test gallery in a variey of styles.

Start by clicking on the red DOWNLOAD button to get the unitegallery-master.zip file:

Unzip the contents and upload the folder united-master\package\unitegallery to your SharePoint site (in this article, I’m putting unitegallery in a document library called Scripts).

In addition to the unitegallery folder, the ‘package’ folder also contains several .html files which each show one of the style samples that are shown on the UniteGallery home page. I liked the way that the “Tiles – Justified” example looks, so I reviewed the sample file to see what was required in the markup for each image. (We’ll need to recreate this markup using jQuery).

So we can see that each image in the above tiles-justified example is basically an anchor tag with optional properties that surrounds an image tag. I wanted to find the minimum that was required in the img tag and after some experimentation found that you could get away with a hashtag for the href and an empty string for the alt tag. I also found that I could eliminate the description entirely. You’ll need to add these back in if you want to support some of the more advanced features in UniteGallery, e.g. sliding image name and description.

So unlike the above example file in which the gallery and image DIV’s are hardwired in the HTML, the approach we’ll take is to create an empty gallery div and use jQuery and SharePoint REST API to grab the images and thumbnails from the image library to populate the gallery div. Once the div is created, then call the unitegallery function to do it’s magic and we’re done. Here’s the script I used (of course, you’ll need to replace https://futuretechnologygroup.sharepoint.com and make other changes to match your environment):

Adding The Gallery To A Page

Once you’re done adjusting the URL’s in the text file above, save it to the Scripts library (or wherever you want). Then add a Content Editor Web Part to a page and reference the script file as the source. After saving the web part settings, the image library is displayed like so:

Unite Gallery is responsive so that if you shrink the browser window it dynamically resizes and repositions the images like so:

And when you click on an image it shows it in a full browser overlay with next/prev arrows:

And that’s it! Now you can display the images in your Picture Library in a customizable, responsive, gallery and lightbox. Pretty good for a half page of code … gotta love jQuery and REST!