Taxonomy List Shortcode

The Taxonomy List Shortcode plugin adds a shortcode to your WordPress installation which enables you to display multiple unordered lists containing every term of a given taxonomy.

Usage
Adding [taxonomy-list] to your post content will render a set of three unordered lists containing all terms of a given taxonomy. Custom css will be printed in a style tag to the head of every page view. If this is unacceptable to you, you may turn it off by using the checkbox labeled “Enable CSS” under the “Taxonomy” section of “Settings” in the Administration Panels.

Supported Parameters

tax To define the taxonomy that you would like to list terms from, you will need to specifiy the name of the taxonomy in the tax parameter: [taxonomy-list tax="category"]. In an “out-of-the-box” installation of WordPress, the following taxonomies will be recognized: post_tag, category, and link_category. If you have defined custom taxonomies through use of a plugin or your own hacker-skillz, you can use the name of this taonomy as well: [taxonomy-list tax="fishy-squiggles"]. If the taxonomy cannot be located, due to a spelling error or missing code, the [taxonomy-list] shortcode will return an empty string.
cols To define the number of columns that the [taxonomy-list] shortcode generates, you will want to use the cols parameter. This parameter will accept an integer from 1 – 5. If this parameter is left empty, or a value outside of it’s range is defined, it will default to three columns. Example: [taxonomy-list tax="category" cols="4"].
color Use this to define the color of the text. The color passed should be in hexidecimal notation (ff0000) or short hand (f00) Please do not include the hash character (#).
background Use this to define the color of the background. The color passed should be in hexidecimal notation (ff0000) or short hand (f00) Please do not include the hash character (#).
show_counts (bool) If you would like to disable the counts from displaying after your term name, set this parameter to 0. Default value is 1.
NEW! per_page (int) Using this parameter enables paging for your term list. It accepts a numerical value from 1 to “your hearts desire”. It is suggested that this feature only be activated on pages that display a list of terms from a single taxonomy. No need to worry, if you have 2 or more lists of terms on a page and you add the per_page parameter to both shortcodes, your site will not break. Please refrain from using this parameter on shortcodes within posts.

Examples

Post Tags (default) [taxonomy-list] – Display a three column, list of Post Tags in alphetbetical order. Although this is the default usage, it is synonymous with [taxonomy-list tax="post_tag" cols="3"].
Post Categories [taxonomy-list tax='category'] – Display a three column, unordered list of Post Categories.
Link Categories [taxonomy-list tax='link_category'] – Display a three column, unordered list of Link Categories. Special note: it is rather pointless to use link categories do to the fact that WordPress does not support front-end display of individual links.
Custom Taxonomy [taxonomy-list tax="fishy-squiggles"] – Display a three column, unordered list of the custom taxonomy “fishy-squiggles”.
Two Columns [taxonomy-list cols="2"] – Display a two, horizontally-aligned unordered lists of Post Tags.
Five Columns (maximum) [taxonomy-list cols="5"] – Display a 5, horizontally-aligned unordered lists of Post Tags.
Custom Taxonomy with 5 Columns [taxonomy-list tax="fishy-squiggles" cols="5"] – Display 5, horizontally-aligned unordered lists of the custom taxonomy “fishy-squiggles”.

Notes on post status

Terms containing published, password protected posts will be shown in the list.
Terms containing only private, scheduled, draft or posts pending review will not be displayed in the list.

The XHTML + CSS was Tested in the Following User Agents

Windows XP: Internet Explorer 6
Windows XP: FireFox 3.5.3
Windows XP: FireFox 3.6.3
Windows XP: Opera 9.26
Windows XP: Safari 4.0.3

This Plugin has been tested with the Following WordPress Themes

Twenty Ten
WordPress Classic
Kubrick
Hybrid
Thematic

Download

Latest version: Download Taxonomy List Shortcode Plugin v0.9.1 [zip]

Installation

Download
Unzip the package and upload to your /wp-content/plugins/ directory.
Log into WordPress and navigate to the “Plugins” panel.
Activate the plugin.

Changelog

0.9

Replaced is_taxonmy() with taxonomy_exists() for WordPress 3.0.
Defined taxonomy_exists() for 2.9 branch.
Added edit links to the terms lists.
show_all argument has been added to shortcode. It is set to false by default.
Tested in 3.0-RC3 using the TwentyTen theme.
Shortcode’s ‘args’ argument has been removed.
Pad counts is now always set to true for get_terms().

0.8.1

Fixed bug in form control for css toggle.

0.8

Added Support for paging via the per_page parameter.
Added cutom subpage under “Settings” called “Taxonomy” for 3.0 support. They killed “Miscelaneous” where our setting used to live.
Changed the name of the CSS setting in the database. Sorry, it won’t happen again :)

0.7

Allowed for disabling of term counts via the show_counts argument. Props to nicolas for the suggestion.

0.6

Added parameters for background and color.
CSS bug fixes.
Tested in 3.0 Beta.

0.5

Main plugin file’s name has been changed from “mf-taxonomy-list-shortcode.php” to “taxonomy-list-shortcode.php”.
Style tag has been optimized to only use one line when rendered.
No longer using an object.
Removed the include_css() function.
Added option for CSS. This can be Set under Miscellaneous -> “Enable CSS for Taxonomy List Shortcode Plugin”.
Added PhpDoc style comments to code.
Added “args” attribute to the shortcode.

0.4

pad_counts is now set to true by default for get_terms();

0.3

PHP Bugfix with empty array being passed to array_chunk().

0.2

Added the sanitize_cols() method.

0.1

Original Release – Works With: wp 2.8.6 + wp 2.9 beta 2.

41 Comments Leave a comment

nicolas May 26, 2010 at 3:37 pm
Hello and thanks for this handly plugin :)

I wonder how could I paginate the plugin generated taxonomy lists. Is it possible to undisplay counters at the end of the line ?

Many thanks for your answer;)
Michael Fields May 26, 2010 at 7:45 pm
Hi Nicolas,
Thanks for writing. I have updated the plugin with a new parameter called “show_counts” which, when set to “0″, will allow users to get rid of the numbers at the end of the line. This page should be updating soon with version 0.7. As for pagination, this is currently not supported, but I will look into it.
Best,
-Mike
Michael Fields May 27, 2010 at 11:21 am
Term paging is now supported in version 0.8.
Barry May 27, 2010 at 12:29 pm
Hi Michael,

I had a great list of all my tags that really added functionaly to my website – thanks.

However, I just upgraded your plugin and I got the following error across my site at the top of each page. Any suggestions? I have had to disable to the plugin to remove the error.

regards, Barry

Warning: Cannot modify header information – headers already sent by (output started at /reedmusic.com/html/shop/wp-content/plugins/taxonomy-list-shortcode/taxonomy-list-shortcode.php:23) in /reedmusic.com/html/shop/wp-content/themes/headway-166/library/core/core-head.php on line 440

Warning: Cannot modify header information – headers already sent by (output started at /reedmusic.com/html/shop/wp-content/plugins/taxonomy-list-shortcode/taxonomy-list-shortcode.php:23) in /reedmusic.com/html/shop/wp-content/themes/headway-166/library/core/core-head.php on line 444
nicolas May 27, 2010 at 3:40 pm
Thank you so much ! Great Job :)
Michael Fields May 27, 2010 at 10:53 pm
Hi Barry,

Thanks for writing. I retested the plugin on a local installation of 2.9.2 with the exact parameters that you are sending to the shortcode but unfortunately could not reproduce the errors you are experiencing. It is quite possible that there is an incompatibility with the Headway theme, but do to it’s price tag and licensing, I cannot download it nor can you distribute it to me. Sorry I cannot help you out.

One thing that I can think of trying is to activate the plugin and go to the Administration Panels. Click on “Taxonomy” under “Options” and then un-check the “Enable CSS box”. This is the only feature of the plugin that prints code to the front end. Unfortunately, this will disable the styles, but if it works, I will gladly provide you with the correct styles to add to you stylesheet.

Best wishes Mike.
Michael Fields May 27, 2010 at 10:54 pm
Nicolas, Thanks for the suggestions. They were very helpful and brought this plugin to the next level. Much appreciated.
Barry May 28, 2010 at 2:48 pm
Hi Mike,

Thanks for the suggestions. I don’t seem to have that Taxonomy under Options. I wonder if the install in missing something for me, perhaps due a conflict? I think I can work around the CSS issues if I can tick enable the CSS options. Do you perhaps have a link to the previous version, before the update, just to keep me going?

regards, Barry
Michael Fields May 28, 2010 at 9:33 pm
Barry, hmmm, please try to uninstall and then download the plugin again. If you are not seeing the Taxonomy panel under options, you may have downloaded 0.8 in a small window where I forgot to upload one of the files. Hope fully this will fix everything. please let me know.
Barry May 29, 2010 at 3:46 am
Hi Mike, Back up and running now! I had tried to download this again, but clearly I got the same update. All looks good now at: http://www.reedmusic.com/music-exams
Thanks for your fast assistance. Regards, Barry
nicolas May 31, 2010 at 5:44 pm
Hey Michael !

Thanks to you for improving the plugin so quickly :) It runs really comfortable now. Regards. Nicolas
Torsten June 14, 2010 at 2:48 pm
Hallo,
works fine, good job.
I´ve got only one problem, articles that are private (or in planning or scheduling I don´t know how it is called in the english backend) have zero tags and causes 404, perhaps there is a simple solution for it. You can see an example what I mean here:
http://www.was-liest-du.de/schlagworte
for example “Epochen” or “Glamour” have 0 tags.
Thank you very much.
Torsten
Michael Fields June 14, 2010 at 6:30 pm
Hi, Torsten,
Thanks for reporting this bug, I have updated the plugin to version 0.9 and if you upgrade, I think you will notice a difference. Taxonomy List Shortcode
-Mike
Torsten June 15, 2010 at 12:13 pm
Hallo Mike,
works perfectly!!!
Was it easy to realise? Because I have the same bug by using the custom taxonomy for example:
‘autoren’, ‘separator’ => ‘ ‘, ‘number’ => 20 ) ); ?>
Unfortunately I made an update without safing the old taxonomy-list-shortcode.php therefore I can not see the difference. Perhaps you also know a easy way to fix it.
Thank you very much.
Torsten
Michael Fields June 15, 2010 at 12:24 pm
Not sure…. unfortunately, your code example was eaten up by the comments form. What I changed that would effect your issue is I turned off ‘get’ = ‘all’ for the shortcode… this is the main reason that the scheduled post’s terms were appearing in the lists. This is something that I never tested for, so thanks for pointing it out! Another thing that the shortcode has always done is set ‘pad_counts’ to a Boolean true if you post back, please wrap your code in a php short code: [ php ] //your code [/ php ]
Torsten June 15, 2010 at 2:04 pm
Hallo Michael,
it must be something else that you changed. If I turn the “pad_counts” to false and delete the next 2 lines in your script, it still works fine.

The code I posted is just the normal way of “custom taxonomies” like Justin Tadlock explain it
```
 // <?php wp_tag_cloud( array( 'taxonomy' => 'autoren', 'separator' => ' ', 'number' => 20 ) ); ?> 
```
These tag_clouds has the bug of an empty string. Perhaps you could send me your version: 0.9.0.

Thank you very much.
Torsten
Michael Fields June 15, 2010 at 2:08 pm
Torsten, what is the wp_tag_cloud() function doing that it shouldn’t? I no longer have version 0.9 but can assure you that the only thing that change between version 0.9 and 0.9.1 were permissions for the edit links.
Torsten June 16, 2010 at 11:09 am
Hallo Michael,
sorry my english is not the best.
So if an article is private, your 0.91 plugin doesn´t display it. But the custom taxonomies for example the wp_tag_cloud does it. I did not noticed that before, yesterday a make a test under “Autoren” called “test”, the article is private and caused 404. I hope by changing the term_args in the register_taxonomy of the function.php to fix it, but didn´t work.
Michael Fields June 17, 2010 at 5:40 pm
Sorry, but I was not able to reproduce this in WordPress 3.0-RC3.
Nicolas June 18, 2010 at 3:22 pm
Hello again Michael !

I was wondering if there was a way to tell the plugin to NOT display taxonomies if there was no post matching.

I would need to record a lot of taxonomies, and write the post later… Would you have an idea ?

Thank so much, have a great week end ;)
Michael Fields June 18, 2010 at 5:14 pm
Nicolas,
Are you using the current version 0.9.1? This is the version that I have installed here. I just created the term “Don’t Click me :)” for the “Topics” taxonomy and I do not see it displaying in the list. The shortcode that I am using is as plain as can be: [taxonomy-list tax="topics"].
Anh Han December 21, 2010 at 10:11 am
Hi Michael!

Great plugin! Was wondering how I go about listing the corresponding post titles complete with a link for each taxonomy.

Is this possible out of the box?
Michael Fields December 21, 2010 at 11:02 am
Thanks! Sorry, but that functionality is not supported by this plugin. I’m sure that it would be rather easy to create, but would more-than-likely create a bunch of extra queries.
Jerry December 23, 2010 at 2:24 am
Hi Michael

Thanks for the plugin, I plan on donating for your efforts.

I do have one question though.

I am having an error with taxonomies widget or taxonomies shortcode.

When I create and authors taxonomy and use taxonomies widget to diplay all the authors, the links with two words or more work but the links with just one word do not link, they are broken… you can check it out by visiting my site, http://www.myinspirationalsayings.com, if you click on sigle word strings the links to not work.

If you could point me in the right directions that would be great.

Thanks
Michael Fields December 23, 2010 at 2:31 am
Hi Jerry, I visited the page and it appears that you have this plugin installed, but I do not see it’s output on the link you provided.
Jerry December 23, 2010 at 4:13 am
If you go to the main page (the link I provided)
and you look and the widget titled “Authors” and click on an author that only has one “name” as in
“Aristotle” It does not link to the posts with the Aristotle taxonomy value. This may not be a problem with your plugin, rather a problem with the GD Custom Post and Taxonomy Plugin that im using. What do you think?

http://www.myinspirationalsayings.com/author/aristotle
Michael Fields December 23, 2010 at 5:28 am
Yes, I visited the link you provided and you are not using this plugin on the page! If I had to guess, I would say that you are using the GD Custom Post and Taxonomies Tool plugin to generate your lists. Most likely the issue you are experiencing stems from the use of the word “Author” as a taxonomy. This query var is reserved in WordPress. I would renaming the query_var and rewrite slug values of the taxonomy to something other than “Author”,
Jerry December 28, 2010 at 1:24 am
Michael

Thanks for the help.

Correct, No I am not using your short code on that page. But I am using your taxonomy side bar widget.
I fixed the error, for some reason the post slug could not be one word for the links in the taxonomies side bar widget to work correctly.
Jason Paul April 10, 2011 at 5:24 am
So I needed the list to show terms instead of taxonomy. So on a whim I tried this:

[taxonomy-list term="custom-post-types" show_counts="0" cols="2" ]

and it actually worked! I’m thrilled because I’ve been looking for a way to organize the content of a monthly magazine. Essentially creating a taxonomy for “Edition” and dynamically creating table of contents pages using taxonomy terms like “april-2011″. That might make no sense to anyone, but I think if you’re trying to do a site that is a periodical this is a huge deal.

I’m pretty sure this is the answer. I didn’t see the term= written in your documentation but I imagine you built this in on purpose. Thank you!
Jason Paul April 10, 2011 at 5:32 am
ah…just realized I jumped the gun in my excitement. as I’m doing a periodical magazine, I need the list to show the titles of the post with the taxonomy or term instead of the list of taxonomy/term names. it doesn’t seem like it’s possible with this plugin…but it was so close. Please let me know if you have any ideas on how to show a list of all the post titles in the list of specified tax instead of the actually tax names.

Michael Fields April 10, 2011 at 5:59 am

Yep, This plugin only works for terms of taxonomies. Posts are pretty easy to print in a list. Here’s a bit of code that should work for you. You’ll want to change “topic” to reflect your taxonomy slug and “topic-1″ to reflect the specific term:

$articles = get_posts( array(
	'topic'       => 'topic-1',
	'numberposts' => -1,
	) );

if ( ! empty( $articles ) ) {
	print "\n" . '<ul>';
	foreach( (array) $articles as $post ) {
		setup_postdata( $post );
		the_title( '<li><a href="' . esc_url( get_permalink() ) . '">', '</a></li>' );
	}
	print "\n" . '</ul>';
	wp_reset_postdata();
}

Jason Paul April 10, 2011 at 4:05 pm
Thanks. I’ll try to take this and figure out how to turn it into a shortcode to spin off a different plugin!
Jason Paul April 10, 2011 at 10:54 pm
So I noticed it works in standard post tag taxonomy Example I tried ‘tag’ => ‘wordpress’ and that generated the tag archive list. In the site I’m currently testing with all the taxonomies are for Custom Post Types and nothing shows up for those. Any ideas on how to include Custom Post Type taxonomies/terms to show up in that bit of code?
Michael Fields April 10, 2011 at 11:07 pm
That’s actually the expected behavior. You’ll want to read up on the get_posts() function. You’ll need to pass a ‘post_type’ argument that has a value of the name that you used to register you custom post_type.
Peter April 15, 2011 at 4:25 am
Hi Michael,
I really like your work on taxonomy related code & plugins – it has been most useful.
I wanted to know if you could give me any advice on how to make the tag term lists display indented lists for taxonomies with hierarchies?
I’m looking at the taxonomy-list-shortcode.php file around where you set the args for $term_args & $defaults but I can’t work out if it’s possible.
Any advice would be appreciated.
Peter
Peter April 15, 2011 at 5:38 am
Hi, sorry to comment again so soon. I guess I’m referring to adding hierarchy into the lists.
roser June 13, 2011 at 4:09 pm
congratulations for the plugin. I would like to exclude some taxonomies. Is it possible?
Thank you very much
Michael Fields June 13, 2011 at 7:25 pm
Roser, unfortunately it is not possible with the current version … I may add it into the next release though!
zerobde July 17, 2011 at 10:55 pm
How do you activate the taxonomy list shortcode gallery template? I like this plugin and appreciate the time and effort put into it. Keep up the great work :)
Michael Fields July 19, 2011 at 6:18 am
zerobde, Thanks! Glad you like the plugin … it’s one of my favorites :) The gallery template is not yet available unfortunately. I was waiting until a bug was fixed in 3.2 to get the next version out the door, but I am completely swamped at the moment. I’ll let you know when this feature is available.
Michael Carter November 18, 2011 at 1:24 pm
Michael — neat plugin. My question is general but applies here specifically as I’m using TL Shortcode. Is there any way to display the list horizontally? I’ve Googled this for a while, and it doesn’t seem to be an issue. It does seem like a practical problem because the vertical space used is wasted compared to a horizontal display.

Thanks, Mike