Creating a custom gallery template for NextGEN Gallery

NextGEN Gallery is one of the easiest to use image gallery plugins for WordPress, so we now try to use it wherever a website needs to have user-managed sets of images: sliders/carousels, trade/media galleries, scenic galleries, you name it. We can do that easily because NextGEN allows you to create custom gallery templates.

You can find the standard gallery templates in the “view” folder inside the nextgen-gallery plugin. There are templates for albums, galleries, image browsers, and showing a single picture. You can customise these templates by taking a copy and editing, in one of two ways: for themes, and for plugins. This post addresses making a custom gallery template.

Edit: NextGEN Gallery 2.0 is a radical rebuild of the plugin, and these “legacy” template files can now be found in this folder within the plugin instead:


Customising for a theme

If you want to customise one of the standard templates for your theme, or create a whole new template, just copy a gallery template from NextGEN’s “view” folder into a folder called “nggallery” in your theme. If you want it to be a new template and not override a standard template, give it a new name starting with “gallery-“.

For example, let’s say we want to create a new gallery template called “awesomeness”. Because it’s going to be just full of it. So here is an outline of the process:

  1. create the folder “nggallery” inside the theme folder
  2. copy the file “gallery.php” from NextGEN’s “view” folder to the new “nggallery” folder
  3. rename the new file to “gallery-awesomeness.php”
  4. edit “gallery-awesomeness.php” to customise it full of awesome
  5. use our new template, e.g. with a shortcode: [[nggallery id="1" template="awesomeness"]]
  6. ???
  7. profit!

That’s it, job is done. Well OK, step #4 has a few wrinkles in it, but you’ll sort that bit out in no time flat now that you know how to get NextGEN to load a custom gallery template.

NB: the template filename must start with “gallery-” but you leave that bit out when referencing it in shortcodes!

Customising for a plugin

If you want to make a plugin that adds a custom gallery template to NextGEN Gallery, the process is very similar but without the “nggallery” folder. You just need a way to tell NextGEN about your new template (because it knows to look in theme folders but not your plugin’s folder). For that, like so many things in WordPress, there’s a hook:

add_filter('ngg_render_template', 'nggTemplateAwesomeness', 10, 2);

* tell NextGEN about our custom template
* @param string $custom_template the path to the custom template file (or false if not known to us)
* @param string $template_name name of custom template sought
* @return string
function nggTemplateAwesomeness($custom_template, $template_name) {
    if ($template_name == 'gallery-awesomeness') {
        // see if theme has customised this template
        $custom_template = locate_template("nggallery/$template_name.php");
        if (!$custom_template) {
            // no custom template so set to the default
            $custom_template = dirname(__FILE__) . "/$template_name.php";

    return $custom_template;

No AJAX pagination!

So, now the bad news: if you create a custom gallery template, you can forget about using AJAX pagination. This is because in NextGEN Gallery v1.anything, AJAX pagination only works for the default gallery. It won’t even work for the captions gallery. Basically, the process is broken.

I’ve mentioned this to Photocrati, and they tell me it might be fixed in the forthcoming v2.0, sometime early 2013. We all look forward to it!

No custom attributes!

The other bad news is that as currently written, the nggallery shortcode doesn’t pass any custom attributes on to galleries, so you’re stuck with the standard shortcode attributes. This is a real nuisance, and I hope that Photocrati change this situation soon.

But it isn’t terminal; job is still getting done with custom gallery templates, and the clients love it because they only have to deal with one image gallery builder.

  • I’m trying to get gallery id from $gallery->ID, but after update NGGallery it returns inly codes like “52acb18344de3647f92568358d34d1bf”. Do you know how to get gallery ID now?

    • G’day Dmytro,

      Sorry, I don’t know. I’m mostly waiting by the sidelines to see whether Photocrati can make the new version stable before I venture in again. I have actually shelved a project that was going to be based on NextGEN Gallery, and am likely to make it stand-alone with very simple integrations with NGG instead now.


  • Rob

    Hi Ross, did you get anywhere with NGG v2? Keen to get a decent v2 imagebrowser custom template running

    • G’day Rob, the discussion above was about gallery IDs which are not so important in NGG2. When working with a template, you’re typically working with a set of selected images, which may be from one gallery, many galleries, a tagged selection of images, or individually selected images.

      The main problem at present is that recent versions stopped allowing you to type in the legacy template name. A future version will allow you to add your plugin’s template folder into the drop-down list, however.

  • ainsworthstudio

    Howsit Ross? The plugin is really incredible and I appreciate all the work you’ve put into it.

    I’ve got a question regarding the download all button – is there a way to place it onto an archives page?

    As an example, let’s say there’s a page that a user has with their favorite galleries they’ve selected (archive page has 8 favorite galleries on it). Can I place a download all button onto this archives page for each gallery (this way the user can download all the images in that particular gallery without having to go into each of the 8 galleries to download all). Is this possible? How would I accomplish it?


    • G’day, not quite sure what you’re asking exactly, because I’m not sure what you mean by an “archive page” in this instance. This isn’t really the place for support questions either, so perhaps you can start a topic on the NextGEN Download Gallery support forum instead. Be sure to explain exactly how you created your archive page.

      Short answer though: if you can get the gallery ID for your gallery, then you can create a download button for it.