AtkinsSlider: Extending WordPress’s Galleries with Plugins

For a while now, WordPress has included features for organising and displaying images as a gallery. However, I noticed that the built-in carousel I was using wasn’t resizing with the rest of the page. I couldn’t easily find any existing plugins that would do what I wanted, so I decided to write my own.

The source for this project, dubbed ‘AtkinsSlider’ because I have no imagination, is on GitHub.

My goals were as follows:

  • It must make use of WordPress’s gallery feature. It has a pleasant admin interface already, and building my own would be too time-consuming.
  • It must display nicely if javascript is disabled. By default WordPress displays galleries as a grid of thumbnails with captions, so this should be preserved.
  • Integrate a lightbox, so clicking thumbnails will display the full image without leaving the page.
  • It should animate between the images over time.
  • If the mouse cursor is over the slider, pause the animation. Websites that don’t give you long enough to look at a slide are very frustrating.
  • Have dots that let you jump to a specific slide.

For the lightbox part, I decided to use Lightbox2, but of course there are many lightbox scripts available.

The WordPress documentation is generally pretty useful, but information about the gallery in particular is pretty lacking. Fortunately, the Jetpack plugin does some work with galleries, so I could look through its source code and figure things out, using some experimentation.

The filters I used are as follows:

By default, the gallery puts a <style> tag just before the gallery HTML. By returning false to this filter, you can prevent this.
This is the place to put your wp_enqueue_sript() and wp_enqueue_style() calls, so that these scripts and styles are only included in pages with a gallery.
This is passed the HTML for the beginning of the gallery, including the <style> tag if you don’t return false to use_default_gallery_style. I simply used it to increment a ‘gallery index’.
This is called for each image in the gallery, with the HTML for the gallery entry and an ID. Gallery items are actually stored as posts in WordPress’s database, so you use get_post(ID) to get the image information. The image caption is stored as the ‘post excerpt’. What I do here is add the caption as the <a>’s title attribute, and set the ‘data-lightbox’ attribute to ‘gallery-‘ plus the gallery index. This is just so the lightbox behaves correctly – Lightbox2 uses the title as the caption, and groups images with the same ‘data-lightbox’ attribute together.

At this point, we have a working lightbox. Next is to set-up the slider with Javascript. This involves several small steps:

  • Create the caption and ‘dots’ html
  • Hide the existing captions
  • Resize the image thumbnails to the full images
  • Define a function to animate to a given slide
  • Set-up an interval to switch the slide after a given delay.
  • Finally, hook-up mouseEnter and mouseLeave events, so that the animation stops hen you hover over the slider, and starts again when you leave it.

The CSS involves some tricks. We want the gallery to maintain its aspect ratio, and images should be centred.

Keeping an aspect ratio on an element can be accomplished by setting its height to 0, and its padding-bottom to a percentage. For instance, setting it to 75% will make the element’s height 3/4s of its width.

Images are kept centred horizontally with a ‘text-align: center’ declaration on the containing element. I attempted to vertically centre them too, but this proved more troublesome. If you set an element to display: table-cell, you can then you vertical-align: middle – this does centre the image, but images that are too tall will now overflow rather than resizing.

A second way of centring images is to instead set them as the background-image of their container. Using background-size: contain, the image will shrink to fit its element. However, this does not work in IE8 and below. In the end, I decided having wide images align to the top of the slider was not a problem.

The plugin code, again available on GitHub, requires manual tweaking if you wish to change the timings or the size, etc. As it was primarily for my own use, I did not spend time including a settings page. Hopefully though, it will prove useful for you either to use directly, or just to see how the gallery filters work.