How to Override Template Files in BigCommerce for WordPress

Published in

BigCommerce Developer Blog

7 min readAug 27, 2019

The template files that ship with the BigCommerce for WordPress plugin are intended to cover most needs for most people. It could never cover all needs for all people however, so we followed the standard WordPress template override system to allow you to easily modify the templates to fit your needs. This makes BigCommerce for WordPress flexible enough to allow merchants to make the plugin elements match the rest of the site design and branding. I’ll show you how to override a template to make it do something new.

In this post we’ll reference some excellent resources, listed here:

The Project

My store is selling Minions, those little yellow chaps from the movie Despicable Me. I have some Custom Fields in BigCommerce that list Specifications. The template for Single Products can see those custom fields and automatically render them, but it does it nearly at the bottom of the page and in a format that I don’t desire.

Instead I’m going to reformat those fields into a nice HTML table and put it right below the image gallery where there’s currently an empty space.

So let’s get started.

Step 1: Preparing the Data

I made four custom fields. You can read how in our custom fields documentation. I found my product in WordPress and then clicked the Open in BigCommerce link.

Then in the menu at the top I chose Custom Fields and created my four.

Then I went back to WordPress and again in the admin listing I found my product and clicked the Re-Sync link.

This gets the new information for that product without having to resync the entire catalog. Now our data is ready.

Step 2: Copying The Template File

All of the template files are in the BigCommerce for WordPress plugin folder, but you don’t want to edit those. If you do then the next time there’s a plugin update all of your changes will be overwritten. So we need to move them into your theme.

Note: You don’t have to move ALL of the template files, only the ones you change.

The plugin folder is called bigcommerce, so you’ll find the template files in /bigcommerce/templates/ . The ones you probably want are in /bigcommerce/templates/public/components The components folder holds all of the small pieces of each page. You almost never want to work with the template files above components, they assemble all the small pieces. The ones we’re specifically going to be working with in this post are /bigcommerce/templates/public/components/products/product-single.php and /bigcommerce/templates/public/components/products/product-gallery.php

To copy these to your theme, make a folder in your theme called bigcommerce. Then we want to replicate paths starting with components. So we’ll copy our files into bigcommerce/components/products/ in our theme.

Here’s a screenshot of it in the twentyeleven theme.

Step 3: Editing The Template Files

Once the files are in the right place we can begin editing them.

Editing product-single.php

At the top of product-single.php you’ll see a list of variables that are available in this file. One of them is $specs. Near the bottom of the file you’ll find it echoed. That’s all there is to the original method of printing them out. The data controller that serves this template does the work of getting the fields and organizing them all into one string held by $specs.

We’re going to ignore that variable and pull the data out of the product data class ourselves. Find the line that looks like this:

<?php echo $specs; ?>

and either comment it out, or remove it altogether.

You’ll also note that one of the variables is called $product. This is an object that holds all of the product data. The data itself is marked Private, which means you can’t access it directly, but the Product class provides methods for accessing that data. You can see all of these methods in the Product documentation (pro tip: scroll to the bottom).

Editing product-gallery.php

The place I want my new code is right under the images. So I’m going to find the code that looks like this:

<?php echo $images; ?>

This actually calls the product-gallery.php template, so we’re going to go edit that one.

We want to put our new code just inside the last </div> in the template, so that it’s inside the gallery div.

The Code

As we can see in the docs for the Product class, there’s a method called get_custom_fields(). So let’s fire up PHP and make a line like this:

<?php
    $custom_fields = $product->get_custom_fields();

So now $custom should hold all of our custom fields in an array. If you want to see the contents of the array you can either inspect it in your editor, or print it like this:

echo ‘<pre>’;
print_r( $custom_fields );
echo ‘</pre>’;

My results look like this:

Array
(
    [0] => Array
        (
            [name] => Henchmen Type
            [value] => Minions Christmas
        )    [1] => Array
        (
            [name] => Construction Material
            [value] => Yellow Marshmallow
        )    [2] => Array
        (
            [name] => Average Age
            [value] => 2,473 years
        )    [3] => Array
        (
            [name] => Language
            [value] => Minion
        )
)

At this point all we have to do is loop through the array and build our HTML table. The entire code block looks like this:

<?php// go get our custom fields
$custom_fields = $product->get_custom_fields();// make sure we actually got some
if ( ! empty( $custom_fields ) ) {
?><table id=”bc-product-specs”><caption><?php _e( ‘Product Specifications’, ‘bigcommerce’ ); ?></caption><tbody>
<?php// loop over custom fields array making table rows
foreach ( $custom_fields as $set => $fields ) {    echo ‘<tr>’;
    echo ‘<td class=”name”>’ . esc_html( $fields[‘name’] ) . ‘</td>’;
    echo ‘<td class=”value”>’ . esc_html( $fields[‘value’] ) . ‘</td>’;
    echo ‘</tr>’;
}
?>
</tbody>
</table><?php
}
?>

Note: Before we start printing code to the screen we check to make sure we retrieved some content. Also, when we actually print variables, make sure to escape the output.

The Output

Now we have something that looks like this:

The table is correct from a content standpoint, but I’m using the theme TwentyEleven, and I don’t like how the HTML table looks, so I’m going to adjust that. You’ll note in the code above that the table itself has an id of bc-product-specs, and each left cell has a class of name and each right cell has a class of value.

So I’m adding some CSS that looks like this:

#bc-product-specs {
  margin-top: 30px;
  border-collapse: collapse;
}#bc-product-specs caption {
  margin: 0 0 4px 0;
  font-size: 22px;
}#bc-product-specs td {
  border: 1px solid #ddd;
  padding: 2px 4px;
}#bc-product-specs td.name {
  font-weight: bold;
}

We enter that by going into the WordPress Customizer, found in the top bar of the site when you’re logged in:

Then in the bottom of the Customizer options choose additional CSS:

And then put in the CSS:

Once you’re done entering your CSS, click publish and your changes will be saved.

Conclusion

It’s important to remember why we copied template files before editing. Every time the main plugin gets an update it gets all new copies of the templates, whether they change or not. If you make changes to those core templates then they get destroyed on every update. That’s why WordPress invented this system of copying plugin templates into your theme, so you can safely make changes without fear of losing them.

Then once you’ve made your own copies you can make them look any way you want, even changing the content on them.

Here are some of the important points we covered in this post:

Copy template files from the plugin to your theme
Edit the ones in your theme
$product holds an enormous amount of information
CSS can go in the customizer

Editing template files is an easy way to really change and extend the BigCommerce for WordPress plugin.