This is a beginner developer’s introduction to the plugin WordPress WooCommerce. In this post we’ll look at the basics of how WooCommerce works and how we can customize it in our theme or plugin using hooks and templates.
First off, WooCommerce offers great flexibility for theme and plugin developers to adjust its functionality. For simple modifications you usually have at least two alternatives to go about it. The choice of how you modify depends on how you prefer to work, how flexible and legible your code should be, and how you prefer to keep doing future maintenance of your site when it comes to plugin (and WordPress) updates.
WooCommerce templates
WooCommerce offers a large array of template files in which you as a theme developer can override. The way you do this is by making a copy of the original WooCommerce template into your theme folder. And then you make your changes to the file in your theme.
Navigate to your WooCommerce plugin folder in /wp-content/plugins/woocommerce/. Here you will find the subfolder templates. The entire contents of files (there is a lot!) in /wp-content/plugins/woocommerce/templates/ including its subfolders are all template files you can override in your theme.
In order for WooCommerce to find your modified templates, you need a subfolder in your theme root directory named woocommerce. If your theme’s slug is ‘awhitepixel’ then your folder should be located at /wp-content/themes/awhitepixel/woocommerce/. Inside this folder you can place your modified copies of WooCommerce’s template files. Keep in mind that template files located in subfolders need to be placed in corresponding subfolders in your woocommerce folder. For example; overriding WooCommerce’s /templates/single-product/add-to-cart/simple.php requires you to place your copy of simple.php in /woocommerce/single-product/add-to-cart/ folder in your theme.
You might also have noticed that there is a lot of actions and filters in the templates. Most of them are filled with do_action()s. For optimal use of WooCommerce you should not remove any of the hooks in the templates. In most cases you might consider changing the functionality by using actions and filters instead of overriding templates. Let me explain why!
Important note about overriding templates and plugin updates
For a beginner overriding a template might seem like the easiest and the most intuitive fix. Why mess about with hooks if you can straight out change the template which outputs the thing you want to change? Answer: Because this strategy generates more work for keeping up maintenance of your webshop.
WooCommerce updates frequently, and sometimes they update a template file. In order to keep your webshop up to date, you would need to update the overriden template files in your theme as well. You’ll usually need to replace the whole template file with the newest updated file, and then re-add your changes. This quickly becomes a lot more difficult if you don’t remember all changes you made. Take it from me who has years of experience in fixing other developer’s WooCommerce template files during plugin updates. Trust me, it’s not a fun job to do!
Now that we know hooks are a better strategy, let’s look at how to go about that.
WooCommerce hooks
WooCommerce offers a huge amount of hooks, both actions and filters. Using hooks is actually really simple!
With hooks you can also alter so much more than just the output of the templates. You can customize product prices, checkout fields, or make your webshop do something when a product is added to the cart.
If you are developing a plugin, hooks are also the only way to go. You can only override templates in a theme, not a plugin. (Okay, there are ways to overcome this, but it’s very uncommon and not recommended).
If you have looked in some of the WooCommerce template files, you should have seen plenty of do_action(). These are hooks; checkpoints you can hook into and add your code or modify a variable. If you are unsure about how hooks work, I have a post that explains this in depth.
If you want to output something, for example a text or something similar, look for actions (do_action()). For example outputting something in cart template, you have the choice of hooking onto woocommerce_before_cart, woocommerce_before_cart_table, woocommerce_before_cart_contents, woocommerce_cart_contents, woocommerce_cart_actions, woocommerce_after_cart_contents, woocommerce_after_cart_table, woocommerce_cart_collaterals, or woocommerce_after_cart. Simply choose the one that is positioned where you want your output. This is an example of showing a text before the table and the form in cart page:
add_action('woocommerce_before_cart', function() {
_e('Here are the products you have added in the cart so far', 'textdomain');
});
Filters (look for apply_filters()) are for modifying an output or a variable. A common use of filters in WooCommerce is modifying the “Add to cart” text on the buy buttons. WooCommerce offers multiple filters for this, allowing you to control the text on different pages. For example you can customize the text in the shop loop or in single product view. Filters often provide multiple arguments for further control; for example the product object. Here is a simple example on how to change the “Add to cart” texts in single product view:
add_filter('woocommerce_product_single_add_to_cart_text', function($original_text, $product) {
return __('Buy this', 'textdomain');
}, 10, 2);
With some knowledge of how hooks work and simply looking inside the template files you can find quite a lot of easily changeable functionality. Obviously WooCommerce offers much more advanced modification, changing prices, payment methods, product modifications or imports, all possible with the use of hooks.
Conclusion
The purpose of this post is to give the beginner the basics of how to make modifications to WooCommerce, and the consequences of how you do the changes. I always recommend using hooks over overwriting template files, unless absolutely necessary.
The next step is diving into advanced modifications by getting to know the hooks, processes and objects in WooCommerce. As WooCommerce is the most popular eCommerce platform there is, there are plenty of resources and code examples available on the web. Take a look at the category Woocommerce here on this site for more as well.