Go back to home page of Unsolicited Advice from Tiffany B. Brown

Using FlexSlider 2 with WordPress

I'm currently working on a WordPress-theme development project that requires a simple gallery. WordPress makes this easy with built-in support for photo galleries, but the layout is limited to a sort of slides-on-a-light-box layout. This project called for a slider.

My go-to sliding gallery script of choice has been WooThemes' FlexSlider 2 because of its simple setup and open source license. But the markup that FlexSlider requires is radically different than that of WordPress’ default gallery. Merging the two — and merging them in a way that makes it easy for the client to manage — would take a little more effort than copy-and-paste.

WordPress gallery shortcode

Creating a gallery in WordPress is actually pretty simple to do. You can do it visually, buy selecting photos from the media panel (Add media → Create Gallery). Or you can do it by adding a gallery short code to your post (Figure 1). 

[gallery link="none" columns="1" ids="20,21,22,23,24,25,26,27"]

Figure 1: An example of a WordPress gallery shortcode.

A gallery short code starts with a left square bracket, and the word gallery. Next come the attributes of that gallery. These may include link, what each photo should link to; columns, or how many columns to use for this gallery; and ids, a comma-separated list of the media library image id numbers for each image.

By default, WordPress uses a series of <div> and <figure> elements to mark up galleries. However, FlexSlider expects a list, with a class attribute value of slides nested within a parent element with a class attribute value of flexslider.

The good news, of course, is that WordPress provides a mechanism for adjusting the output of short codes, including that of galleries.

Overriding the WordPress gallery shortcode

Though possible to override a short code handler by adding a new one with add_shortcode, the correct way is to use a filter, specifically, the post_gallery filter.

We can add a filter using the add_filter function. add_filter accepts two arguments: the filter to replace, and the name of a function that returns replacement markup.

That may sound complicated, but here's what it looks like. First, the code that returns the replacement markup. It is modeled on the gallery_shortcode function found in wp-includes/media.php.

function build_gallery_content( $attrs ){

    static $instance = 0;
    $instance++;

    /* 
    Limiting what the user can do by 
    locking down most short code options.
    */
    extract(shortcode_atts(array(
            'id'         => $post->ID,
            'include'    => '',
            'exclude'    => ''
    ), $attrs));

    $id = intval($id);

    if ( !empty($include) ) {
         $params = array(
                    'include' => $include,
                    'post_status' => 'inherit',
                    'post_type' => 'attachment',
                    'post_mime_type' => 'image',
                    'order' => 'ASC', 
                    'orderby' => 'menu_order ID');
            $_attachments = get_posts( $params );
            $attachments = array();
            foreach ( $_attachments as $key => $val ) {
                    $attachments[$val->ID] = $_attachments[$key];
            }
    } elseif ( !empty($exclude) ) {
            $params = array(
                    'post_parent' => $id,
                    'exclude' => $exclude,
                    'post_status' => 'inherit',
                    'post_type' => 'attachment',
                    'post_mime_type' => 'image',
                    'order' => 'ASC', 
                    'orderby' => 'menu_order ID');
            $attachments = get_children( $params );
    } else {
            $params = array(
                    'post_parent' => $id, 
                    'post_status' => 'inherit', 
                    'post_type' => 'attachment',
                    'post_mime_type' => 'image', 
                    'order' => 'ASC',
                    'orderby' => 'menu_order ID'); 
            $attachments = get_children( $params );
    }

    if ( empty($attachments) )
            return '';

    $selector = "gallery-{$instance}";

    $gallery_div = sprintf("<div class='flexslider'><ul id='%s' class='slides gallery galleryid-%d gallery-columns-1 gallery-size-full'>", $selector, $id);
    $output = $gallery_div;


    foreach ( $attachments as $id => $attachment ) {
        /* 
        Use wp_get_attachment_link to return a photo + link 
        to attachment page or image
        http://codex.wordpress.org/Function_Reference/wp_get_attachment_link 
        */
        $img = wp_get_attachment_image( $id, 'full', false);

        $caption = '';

        /*
        Set the caption string if there is one.
        */

        if( $captiontag && trim($attachment->post_excerpt) ){
            $caption = sprintf("\n\t<figcaption class='wp-caption-text gallery-caption'>\n\t<div>\n%s\n\t</div>\n\t</figcaption>", wptexturize($attachment->post_excerpt));
        }

        /*
        Set the output for each slide.
        */  
        $output .= sprintf("<li class='gallery-item'><figure class='gallery-icon'>%s\n\t%s</figure></li>", $img, $caption);
    }
    $output .= '</ul>\n</div>';
    return $output;
}

In this code, we're building the markup we need to add a FlexSlider gallery to each page. The $gallery_div variable holds the markup for the FlexSlider parent container (<div class='flexslider'>) and outer list element (<ul class="slides">). For each image in the gallery, we're adding a figure element inside of a list item. Finally, we add the closing ul and div tags and return the output.

Then we can call it from the function that will be our post_gallery filter.

function custom_gallery_shortcode( $output = '', $attrs){
    $return = $output;

    # Gallery function that returns new markup.
    $gallery = build_gallery_content( $attrs );


    if( !empty( $gallery ) ) {
        $return = $gallery;
    }

    return $return;
}

add_filter( 'post_gallery', 'custom_gallery_shortcode', 10, 2);

You don't have to use build_gallery_content or a similar function, of course. You could just fold that code into custom_gallery_shortcode. But using a separate function is a bit more readable.

Both of these functions should be placed in the functions.php file for your theme. If you're using an off-the-shelf theme, you may want to build a child theme so that you don't override your functions.php changes when you upgrade.

To make it all work, add FlexSlider code to your site's JavaScript file. 

$(window).load(function() {
  $('.flexslider').flexslider();
  $('.flexslider').flexslider("pause");
});

To support multiple FlexSlider galleries on a page, use the code below.

$(window).load(function() {
  $('.flexslider').each( function(ind){
    $(this).flexslider();
    $(this).flexslider("pause");
  });
});