We recently came across the need to add a CSS class to the subcategory images output by WooCommerce. As there currently isn’t a suitable filter, in this technical how-to post, we’ll share our solution.
Along the way, we’ll touch on how WordPress and WooCommerce are built upon by developers without causing headaches when it comes to future updates and we’ll share a generic helper function which simplifies adding CSS classes to HTML elements.
We’ve built tooling and optimised around CodyFrame, an excellent frontend framework which includes many helpful CSS utility classes.
What are utility classes?
Rather than write specific CSS styling for every element, frontend frameworks come bundled with utility classes. Single-purpose classes such as font size, colour etc. Using these classes can speed up development and improve website performance by reducing the overall amount of CSS that is written for a project.
While the easiest solution to our original problem would be to write a CSS selector to target the image tag, I’m going to share one of our helper functions which makes it easier to work with and benefit from the power of CSS utility classes.
Actions and filters
One of the key strengths of WordPress and its ecosystem is its extensibility. The system of actions and filters that allow developers to hook in custom functionality and modify existing functionality without directly making changes to the underlying code (modifications which would be overwritten by a future update).
WooCommerce tend to be fairly good when it comes to providing filters, allowing developers to tweak certain attributes. However, in our case, the subcategory image’s attributes are not made available via a filter. Instead, we have to dig a little further and locate the action which outputs the image entirely. We can remove the action and register our own to output the image as we need.
Adding CSS classes
The woocommerce_subcategory_thumbnail function also handles cases where a category doesn’t have an image defined. Instead a placeholder fallback image is output. Rather than duplicate all the functionality this method provides, we can call the original function and add a class to the HTML image tag it prints out. We do this using a PHP output buffer.
What is PHP output buffering?
As the woocommerce_subcategory_thumbnail function echo’s its result, we need to capture its output so we can work on it further. We do this by opening a buffer, calling the function, then copy the contents of the buffer to a variable using ob_get_clean.
Now we have the image tag’s markup assigned to a variable, you could use str_replace to add the CSS class. Alternatively, I’ll share a helper function from our internal WordPress starter theme. We have a number of helper functions for interacting with DOM elements.
Helper function to add CSS classes to HTML elements
The function uses PHP’s DOMDocument for HTML parsing and manipulation. It has a few additional features:
It accepts a list of HTML elements. For example, you might want to add a class to multiple heading levels, you could pass in h1, h2, h3 etc.
It supports an optional exception value. As mentioned, we use the CodyFrame frontend framework which includes standardised CSS class naming for properties including font size. For this, the naming convention uses a text- prefix. Using our helper function we can add a text-lg class to every paragraph, unless the paragraph has an existing, explicitly defined text- class. This allows our theme to define a default size, but still allow the user to override should they wish.
The helper function is fairly generic and the concept can be applied throughout the development of a WordPress site. For example, we filter post content to add CSS classes to unordered lists, we buffer the output of Yoast’s breadcrumb functionality to add a text-decoration-none class to its links.
We hope you found this insight into our development process useful. If you’d like to discuss any WordPress or development projects with us, just fill out the form below to get in touch.
Get in touch
Get in touch if you have any trouble. Our team of WooCommerce experts are at hand for new builds and supporting existing stores.