TML – A Plugin for Using Taxonomy Tags on WordPress Media Library Items

April 20, 2017
I have suspended active development of this plugin as I need to work on other things. However, this plugin is still fully supported and I intend to maintain the existing feature set of this plugin for the foreseeable future. This includes compatibility with future versions of WordPress. However as I no longer personally use this product I will not know about a problem unless a user reports it. You can report a problem using this plugin’s support forum. But, for the quickest response in addition you should also contact me using the contact form on my website. I hope to restart active development of this plugin sometime in the future as I have some more ideas I would like to try.
There now exists a demo of TML’s gallery viewer. TML’s gallery viewer is a plug compatible replacement for the standard WordPress gallery viewer for the [gallery] shortcode. This gallery viewer can be used independently of the other features of TML and supports five different views of a gallery.
TML – Tags for Media Library was originally developed for porting NextGEN Gallery 1.9 to WordPress Media Library but has evolved into something that may be useful to anyone trying to use taxonomy tags on WordPress Media Library items. TML supports dynamically generating galleries using a criteria based on taxonomy tags, multiple tag taxonomies for media items, the bulk assignment/removal of taxonomy tags to/from media items, filtering the Media Library by taxonomy tags, sorting the media items based on a priority tags, a search widget for media items using a criteria based on taxonomy tags, an alternate high density view of the Media Library and alternate views of a gallery.

What’s Coming in version

The search widget will be integrated into the gallery viewer, i.e., it is no longer necessary to have the search widget displayed in the sidebar.

Introduction for Users of NextGEN Gallery 1.9

I am a user of NextGEN Gallery 1.9. However, I do not want to upgrade to 2.0 so I am trying to find an alternative.  In particular, I would like to use WordPress’s built-in Media Library. But, this has turned out to be a significant problem because I am dependent on NextGEN Gallery’s ‘nggtags’ shortcode. So what I wanted was a plugin that will convert a NextGEN Gallery image database to a WordPress Media Library image database and and also implement NextGEN Gallery’s ‘nggtags’ shortcode. Since, I did not find exactly what I wanted I have implemented this plugin myself.

The important feature about this plugin is that it converts NextGEN Gallery’s non-standard, proprietary image database into a standard WordPress Media Library media database. The main disadvantage of NextGEN Gallery’s proprietary image database format is that you cannot use plugins that are written for WordPress’s standard Media Library database format. In particular, you are locked in to NextGEN Gallery since other gallery plugins do not understand NextGEN Gallery’s proprietary image database format. Although, it may have been all right to use a non-standard format when WordPress support for media was weak, now that WordPress has decent support for media it probably is better to use WordPress’s standard format. You can read more about this in my Design Objectives page.

This plugin also implements the NextGEN Gallery shortcodes "nggallery", "nggtags", "singlepic", "album" and "slideshow". The plugin implements these shortcodes by dynamically translating them into a equivalent standard WordPress gallery shortcode.

For NextGEN Gallery 1.9 Users: First Do the Conversion

The plugin is very simple. It has a conversion utility that you must initially use to convert your NextGEN Gallery image database to a WordPress Media Library image database. Since, NextGEN Gallery uses mostly its own proprietary file directories and its own proprietary MySQL tables most of this conversion is done non-destructively by copying data to the corresponding WordPress file directories and MySQL tables. However, the ‘NGG Tags’ data is stored directly in WordPress’s taxonomy MySQL tables and this data will be permanently modified to work with the newly copied Media Library images and will no longer work with the original NextGEN Gallery images. Further, the conversion utility may create many new WordPress posts. Therefore it is imperative that you backup your MySQL tables so that you can easily restore your original environment. Before the conversion you may want to set the image sizes using the Dashboard menu item “Settings->Media”. The conversion will be done in seven phases. These phases can take significant time. Please wait until you see the message ‘The conversion of NextGEN Gallery to WordPress Media Library is done’.update

After the Conversion

media-libraryAfter the conversion NextGEN Gallery images and galleries will become WordPress Media Library images and galleries. Also, the taxonomy ‘NGG Tags’ is created for WordPress Media Library images and the NextGEN Gallery image tags is stored in this taxonomy. The taxonomy ‘Priority’ is created for WordPress Media Library images and NextGEN Gallery’s sortorder (multiplied by 100) is stored in this taxonomy. The ‘Priority’ taxonomy will control the display order of images in a gallery.

The built-in WordPress gallery shortcode is enhanced to support the alternate TML views: large, slideshow and titles. From version you can specify the TML options: tml_view and tml_views individually as parameters of the WordPress gallery shortcode

[gallery id="150" tml_view="large" tml_views="standard large slideshow"]

or globally using the "WordPress gallery options" of the Settings page.


If you only want the original WordPress gallery view then set both tml_view and tml_views to standard.

[gallery id="150" tml_view="standard" tml_views="standard"]

The "nggtags" Shortcode

The shortcode "nggtags" dynamically generates a standard WordPress gallery using the taxonomy tags of the media items to select which items to include in the gallery. (If you are not a former NextGEN Gallery user do not let the name mislead you. "nggtags" was the generic taxonomy tags facility for NextGEN Gallery and now "nggtags" is the generic taxonomy tags facility for Tags for Media Library and is not in anyway dependent on anything from NextGEN Gallery.) The gallery parameter is a comma separated list of taxonomy tags. The generated gallery consists of images from the Media Library which have the specified tags. The other parameters to this shortcode are the same as the WordPress ‘gallery’ shortcode options.

[nggtags gallery="brahma,coleman,rustler" link="file" size="thumbnail" columns="4"]

Using the plugins setting page – from the Dashboard select ‘Settings’ -> ‘Tags for Media Library’ – you can set WordPress Gallery options that will be used on all your ‘nggtags’ shortcodes. Enter the options as you would using the ‘gallery’ shortcode e.g. – size="thumbnail" link="file" – using spaces to separate the options.settings
TML has enhanced the "gallery" parameter of the "nggtags" shortcode to support a limited form of boolean expressions.

For NextGEN Gallery 1.9 Users: This plugin also directly implements the NextGEN Gallery shortcode ‘nggtags’ using WordPress’s builtin ‘gallery’ shortcode. So post content with the shortcode ‘nggtags’ should still work. However, except for the options ‘gallery’ and ‘album’ all the other options are now WordPress’s ‘gallery’ shortcode options. For the option ‘album’ to display correctly, the image used as the featured image of the album should have a caption.

For NextGEN Gallery 1.9 Users: The NextGEN Gallery Shortcodes "nggallery", "slideshow" and "singlepic"

edit-pageThis plugin also has a basic implementation of the NextGEN Gallery shortcodes "nggallery", "slideshow" and "singlepic" using WordPress’ builtin "gallery" shortcode. It also translates the id parameter. (The nggid parameter is the original id but this parameter is for your information only and is ignored by the plugin.) So post content with the shortcodes "nggallery", "slideshow" and "singlepic" should still work. However, all the options are now WordPress’s "gallery" shortcode options. For "singlepic" you may want to set the option size=”full”.

[nggallery id="154" columns="5"]

[singlepic id="175" size="full" columns="1"]

Using the plugins setting page – from the Dashboard select "Settings" -> "Tags for Media Library" – you can globally set WordPress Gallery options that will be used on all your "nggallery", "slideshow" and "singlepic" shortcodes. Enter the options as you would using the "gallery" shortcode e.g. – size=”thumbnail” link=”file” – using spaces to separate the options.

Using Display Priorities to Order Images

priorityThe display order of images can be controlled by setting a priority using the tag taxonomy “Priority”. The tag should be a positive integer. Lower numbered images will be displayed before higher numbered images in a gallery. You can also use the bulk priority editor to assign priorities to a set of media items by drag and drop. Currently, priorities only work with the ‘nggtags’ and ‘nggallery’ shortcodes. Priorities do not work with the WordPress ‘gallery’ shortcode since WordPress does not understand priorities – however, I may override the ‘gallery’ shortcode in a future version to fix this.

Additional Taxonomies for Media Library

new-taxonomyIn addition to the default ‘ngg_tag’ taxonomy you can create your own taxonomies for Media Library images. For example for images of shoes I can have taxonomies: maker (Sears, Brahma, Rustler), upper-material (leather, polyurethane, PVC), outsole-material (polyurethane, PVC, TPR) and construction-method (Goodyear welt, cement, injection molded). These taxonomies can be used with the ‘gallery’ parameter of the ‘nggtags’ shortcode. The taxonomies can be created using the setting page – from the Dashboard select "Settings" -> "Tags for Media Library".

The Enhanced "nggtags" Shortcode

The "gallery" parameter of the "nggtags" shortcode supports filtering on multiple taxonomies using a limited form of boolean expressions.

The value of the gallery parameter is of the form:

tax1:term1,term2,...;tax2:term3,term4...;... tax9:term5,term6,...term9

where tax1, tax2, … are taxonomy slugs and term1, term2, … are taxonomy term slugs from the taxonomy tax1 and term3, term4, … are taxonomy term slugs from the taxonomy tax2. The taxonomy slug can be omitted if the taxonomy is ‘ngg_tag’. The comma represents ‘OR’ and the semicolon represents ‘AND’ with the comma having higher precedence. E.g.,

[nggtags gallery="ngg_tag:leather,polyurethane"]

specifies images of shoes that are made of leather OR polyurethane.

[nggtags gallery="ngg_tag:leather;ngg_tag:steel-toe"]

specifies images of shoes that are made of leather AND have a steel-toe. Since ‘ngg_tag’ is the default taxonomy, this could have been written more concisely as

[nggtags gallery="leather;steel-toe"]

If a taxonomies ‘upper’ and ‘maker’ have been created then

[nggtags gallery="upper:leather;maker:brahma,sears"]

specifies images of shoes with uppers made of leather AND made by brahma OR sears

Tags for Media Library Admin Page

Selecting the Tags for Media Library (1) menu item from the Dashboard displays a modified WordPress Media Library page that has been enhanced to support filtering on tag taxonomies and bulk addition/removal of taxonomy tags. Checking the ‘Use Alternate High Density Media List View’ (2) checkbox will set the default view of the media library as a grid of thumbnails – the same as clicking the grid (3) icon. The ‘Show on screen’ options (4) specify which taxonomy filters (5) and which taxonomy table columns (6) are displayed. Hovering over a title (7) or a thumbnail (8) gives the image the focus. The image with the focus is highlighted with a magenta border for the icon and with a magenta background for the title. The WordPress table row (9) of the image with the focus is displayed above the gallery. You can lock the focus by clicking on the lock icon. Clicking on the image icon or the image title will display an overlay with the full image and the image attributes. From this overlay you can also select the ‘Edit’, ‘Delete Permanently’ or ‘View’ operations. Checking the ‘Use Checkbox Overlay for Filters’ (10) checkbox will replace the multiple selection box with an overlay of checkboxes when the mouse is clicked over the selection box. Please click on the image for a full size view.

Bulk Assignment and Removal of Taxonomy Tags

bulk-tag-editorSelecting the action ‘Add/Remove Tags’ from ‘Bulk Actions’ will display a bulk editor for assigning/removing tags to/from the set of selected images. The tags to be removed (3) from the selected images (1) is the union of the tags in the selected images. Deleting a tag from this set will delete this tag from all of the selected images which actually have this tag. New tags may be added using the input textbox (2) or the tag cloud (4). Please don’t forget to click on the "Add" button after typing a new tag in the input box.

The Bulk Priority Editor

The bulk priority editor allows you to set the priorities – sort order – by drag and drop. Selecting ‘Set Priorities’ from ‘Bulk Actions’ (1) will show the ‘Bulk Priority Editor’. First set the starting priority (2) and the increment (3). You can then order the images by drag and drop (4). The images will be assigned priorities according to the starting priority and the increment.

TML’s gallery viewer supports 5 different views of a gallery: 1. Gallery – the standard WordPress view; 2. Miro’sMiro’s Justified Gallery; 3. Titles – a split view of small images and titles; 4. Large – a three way split view of small images, titles and the selected large image; 5. Slide – an automatic or manual slideshow. You can view a demo page of this gallery viewer here. You can click on an image below to get a full size view of the image.





You can specify the initial view of a gallery by setting the shortcode option tml_view to "standard", "miro", "titles", "large" or "slideshow". You can specify the list of gallery views shown to the user by setting the shortcode option tml_views to a space separated list of views.

[gallery columns="5" tml_view="large" tml_views="miro large slideshow"]

The settings page has options to enable "stretch to fit", "preserve aspect ratio" and "full browser window view".

For NextGEN Gallery 1.9 Users: Cleanup

If you are satisfied with this conversion you can delete NextGEN Gallery’s image directory – usually ‘wp_content/gallery’ and NextGEN Gallery’s MySQL tables – usually ‘wp_ngg_pictures’, ‘wp_ngg_gallery’ and ‘wp_ngg_album’ – to save space on your server.


This plugin can be downloaded from the WordPress Plugin Repository.

How to report problems, ask questions, make comments, …

Please post your problem reports, questions, requests and comments to the nggtags for WordPress Media Library Support Forum.