WordPress theme development – how we utilise CSS utility classes

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.

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.

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.

Summary

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.