Custom WordPress jQuery slider with NextGen Gallery

nextgen-jquery-cycle-gallery

How to create your own image slider or fade slideshow with the jQuery cycle plugin using NextGen Gallery for image management.

See a more recent article about using Flexslider with NextGen Gallery here.

Create the image slideshow markup

Before I start customising WordPress files, I like to build a mockup or demo page to make sure that I have the concept working first and I know what markup I want NextGen Gallery to output. Let's start with this simple page:

jQuery Cycle demo page →

This page consists of an unordered list with each list item containing an image, like so:

<ul id="slideshow">
  <li><img src="slide1.jpg" alt="some text"></li>
  <li><img src="slide2.jpg" alt="some text"></li>
  <li><img src="slide3.jpg" alt="some text"></li>
  <li><img src="slide4.jpg" alt="some text"></li>
</ul>

There's a div wrapper around the <ul>, and that's it for the markup.

Add three parts jQuery

You need to have three jQuery scripts to make the animation work:

  1. jQuery library (I have used the CDN version of jquery-latest.min.js)
  2. jQuery Cycle plugin
  3. The script with the selector (I have put this just above the closing </body> tag.

There's a dash of style for the page - this can obviously be replaced with your own style rules.

The script at the bottom of the page targets the list by its ID "slideshow" and attaches the jQuery cycle function. Inside this function you can specify your effects options. Here's what I have used:

<script type="text/javascript">
$(document).ready(function() {
	$('#slideshow').cycle({ 
		fx: 'fade', 
		timeout: 100
	});
});
</script>

There are a number of different fx options available such as scrollUp, scrollDown, scrollLeft, scrollRight, wipe, fadeZoom, etc. See a list of them here, although many aren't practical: http://jquery.malsup.com/cycle/browser.html plus many other option listed here: http://jquery.malsup.com/cycle/options.html

Prepare the NextGen gallery.php file

Now that we have a working demo, it is time to make NextGen Gallery output the markup that we need. The file we need to modify is gallery.php which is located in the /plugins/nextgen-gallery/view/ directory.

Create a directory inside your theme called /nggallery/ and copy the gallery.php from the NextGen plugins directory to this new directory. This file will override the plugin's own copy of the same file and when you update the NextGen plugin, your customised file will remain unchanged. Now you're ready to start customising.

Look for the div with class "ngg-galleryoverview" (line 17 in my file) and add the following code immediately above this div

<?php //begin custom code
  if ( condition goes here ) { ?>
  
      // custom gallery code goes here
  
<?php } else { // end custom code and remember to complete this else statement below ?>

and then complete the if/else statement immediately below the closing div tag for "ngg-galleryoverview" div (line 60 in my original file) and above the final line of the file, a php endif statement.

<?php } // end if/else ?>

What you have just done if maintained the default gallery function for use in any situation other than the custom slideshow that we are creating.

Customise the NextGen gallery.php file

Now it is time to add our custom code. Replace the 'custom gallery code goes here' comment with the following code:

<ul id="slideshow">
  <!-- Thumbnails -->
  <?php foreach ( $images as $image ) : ?>
  
    <li>
      <?php if ( !$image->hidden ) { ?>
      <img src="<?php echo $image->imageURL ?>" alt="<?php echo $image->alttext ?>" />
      <?php } ?>
    </li>

<?php endforeach; ?>
</ul>

Next you need to add a suitable condition to the if/else statement. Amend the beginning of the custom code like so:

<?php //begin custom code
  if ( is_front_page() ) { ?>

This will output the custom code only to the homepage of your site, according to your settings in the General > Reading page of the WordPress admin.

View the final customised gallery file here.

Add the jQuery and style

To make it all work, you will need to add the three parts jQuery from above and some essential CSS. Let's assume that the jQuery library is already included in your theme, so now we will add the cycle plugin. Upload the jquery.cycle.js file to your theme directory and the add the following code to your header.php file:

<script src="<?php bloginfo('template_directory'); ?>/jquery.cycle.js" 
type="text/javascript"></script>

...followed by this code:

<script type="text/javascript">
  $(document).ready(function() {
    $('#slideshow').cycle({ 
        fx: 'fade', 
        timeout: 100 
    });
  });
</script>

Lastly, some basic CSS:

ul#slideshow {
    margin: 0;
    padding: 0;
}
    #slideshow li {
    list-style: none;
}

Add your NextGen Gallery to your homepage

Finally, you need to create a gallery in NextGen, add your images and then drop it in your page using the shortcode or template tag. I will assume that you know how to do that bit already.

All done!

Extra credit: load jQuery Cycle via wp_head() function

The code below outlines how to load the jquery.cycle.js file via the wp_head() function in your header.php file. Note the example below references the file in the /your-theme/js/ directory.

The code also shows how to disable the default WordPress javascript libraries and then load jQuery via the Google CDN. If you prefer a different CDN version just replace the reference below with another from http://docs.jquery.com/Downloading_jQuery#CDN_Hosted_jQuery

// load Google hosted jQuery plus include jQuery Cycle in wp_head()
if (!is_admin()) {
	// disable default WordPress javascripts
    wp_deregister_script( 'prototype' );
	wp_deregister_script( 'scriptaculous' );
	wp_deregister_script('jquery');
	// load jQuery via Google CDN
	wp_register_script('jquery', ("http://ajax.googleapis.com/ajax/libs/jquery/1.7.1/jquery.min.js"), false);
	wp_enqueue_script('jquery');
	// load jQuery Cycle from /js/ directory in theme
	wp_register_script('jquery-cycle', get_bloginfo('template_directory') . '/js/jquery.cycle.js', false);
	wp_enqueue_script('jquery-cycle');
}

Don't forget, you will still need to add the jQuery function which targets the slideshow selector (see #3 in 'Add 3 parts jQuery' above).

6 Responses to “Custom WordPress jQuery slider with NextGen Gallery”

  1. paco says:

    sorry but i donĀ“t know how to do the last (“Finally, you need to create a gallery in NextGen, add your images and then drop it in your page using the shortcode or template tag. I will assume that you know how to do that bit already.”).

    Can you say me how to do this please??

    Thank you.

  2. nick says:

    Hi Tim,

    This looks very promising in sorting out some issues I’ve been try solve.
    Would you mind briefly explaining where the js <script etc. should reside in header.php?
    I tried it before wp_head(); but keep getting a parse error.

    Many thanks

    • Tim says:

      Hi Nick,

      It could be the you’re loading the jQuery Cycle plugin before the main jQuery library, which will prevent it from working. I have added an extra note to the end of the article which shows how to load the jquery.cycle.js file via your wp_head() function, plus how to replace the default WordPress jQuery with the Google hosted version.

      If you’re still stuck, send me a link and I’ll take a look at your page.

      Tim.

  3. nick says:

    Excellent it works brilliantly! … I’m so grateful to you for this Tim …
    Before I was calling the slideshow with the function:

    ‘nggSlideshowWidget(id,width,height);’

    That method doesn’t let you define a template but with your method you can and have complete flexibility of the slideshow.

    Note that with my child themes I had to put the jQuery function which targets the slideshow in the footer.php before the ” tag

    Many thanks

    / \ / ; ) c / <

  4. ime says:

    hello

    I am trying to find a way to get a fullscreen background gallery that uses nextgen gallery for its image handling source. Any idea on how to do that? I guess I could partly use your tips, right?

    great site!