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:

nextgen-gallery/products/photocrati_nextgen/modules/ngglegacy/view/

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.