4 Insights from Exploring the WooCommerce Product Categories Shortcode

November 8, 2018 By Andrew Mull

• Facebook
• Instagram
• LinkedIn
• Twitter

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.