The WooCommerce 3.2 release brought with it an improved shortcode system. On a recent project, we had an opportunity to use the Product Categories shortcode to its fullest. This allowed us to really dig in and explore the options available with it. Here are a few of the insights we found while exploring the WooCommerce Product Categories shortcode:
Term Query Options within the WooCommerce Product Categories Shortcode
We found a pleasant surprise – the shortcode has more hiding under the hood than the original WooCommerce shortcodes documentation showed. The documentation stated only that the “[product categories]” shortcode exists, and didn’t so much as give an example before moving on to the next section. There wasn’t much more information hinting at the options it supports. Natively, the [product_categories] shortcode supports a small subset of the options available to a WP Term Query:
Option Accepts Default get_terms() argument Notes hide_empty mixed 1 hide_empty get_terms() expects either 1 or 0. The shortcode will map 1, '1', true, and 'true' to 1 and all other values to 0. order string 'ASC' order The only valid values are 'ASC' and 'DESC'. orderby string 'name' orderby Accepts any orderby value that can be passed to get_terms(). parent special empty string child_of This gets mapped to a Term Query's "child of" attribute. Accepts a comma-separated list of IDs. ids special empty string include This gets mapped to a Term Query's "include" attribute. Accepts a comma-separated list of IDs.
Additional WooCommerce Product Categories Shortcode Options
Additionally, WooCommerce has included a couple extra options not supported by term queries themselves. Nothing especially revelatory, but it does have the ability to limit the number of results and define a custom number of columns, which is certainly nice to have.
Option Accepts Default get_terms() argument Notes columns int 4 N/A Determines how many columns to format the results into. limit int or string '-1' N/A Determines how many results to display. number int or string '-1' N/A Alias of 'limit'. This appears to be deprecated; use 'limit' instead to be safe as 'number' has a good chance of being removed in the future.
The currently available options are fairly limited, but they cover the typical use cases you might run into when setting up a store that prefers not to use the full Catalog functionality, yet would still like to have a ‘list of product categories that…’ page or pages. While a fully filterable version would be preferable, a version like that has the potential to leave the door open to nefarious sorts using it as an attack vector.
Filters Cannot Currently Be Used to Add New Options
Initially, we were excited to see that WooCommerce was using WordPress’s built-in shortcode_atts() function to filter out any errant shortcode attributes. This is an essential part of any good “sanity check” when writing a shortcode. Since WordPress 3.6, shortcode_atts has a filter hook, which calls a filter unique to that shortcode after it does its thing, the filter in question is shortcode_atts_{$shortcode_name_here}. Having that functionality for the WooCommerce product categories shortcode would, at least theoretically, open it up to the whole of WP Term Query for a developer willing to drop code in their theme’s functions.php or spin up a quick plugin to encapsulate it outside the theme in question.
Unfortunately, it’s not meant to be, at least for now. The product categories shortcode cannot currently be expanded with filters. In this specific case, the folks over at WooThemes went the extra mile to harden this particular shortcode. Even if you do hook into it, there is a second mapping process to make sure only what was initially allowed by shortcode_atts() makes it through to the get_terms() call. So, we’re unable to make use of its full potential at this time, but hopes are high that the full filter functionality will be introduced in a later version. Having the whole of WP Term Query at our disposal for Product Category shortcode pages would blow the doors wide open for customization on special pages.
Don’t Forget to Check orderby Attributes
If orderby doesn’t appear to work, log in to the admin for the site in question. Using the page inspector of your choice, check the field name for that field’s input. In our case, the issue was using ‘tag-name’ instead of ‘name’ and the shortcode refused to cooperate until we switched the orderby attribute accordingly.
This site uses ‘tag-name’, and would need its ‘orderby’ set accordingly.
There are a lot of options currently available with the WooCommerce product categories shortcode and certainly more on the way in later versions. It’ll be exciting to see what other options become available in the future as shortcodes continue to develop and improve.