Non-WooCommerce themes, by default, also include:

• Zoom feature enabled – ability to zoom in/out on a product image
• Lightbox feature enabled – product gallery images pop up to examine closer
• Comments enabled, not Reviews – visitors/buyers can leave comments, same as a post, and not product ratings or reviews

If you want more control over the layout of WooCommerce elements or full reviews support your theme will need to integrate with WooCommerce. There are a few different ways you can do this, and they are outlined below.

Theme Integration

There are three possible ways to integrate WooCommerce with a theme. If you are using WooCommerce 3.2 or below you will need to use one of these methods to ensure WooCommerce shop and product pages are rendered correctly in your theme. If you are using a version of WooCommerce 3.3 or above you only need to do a theme integration if the automatic one doesn’t meet your needs.

Using woocommerce_content()

This solution allows you to create a new template page within your theme that is used for all WooCommerce taxonomy and post type displays. While an easy catch-all solution, it does have a drawback in that this template is used for all WC taxonomies (product categories, etc.) and post types (product archives, single product pages). Developers are encouraged to use the hooks instead.

To set up this template page:

1. Duplicate page.php

Duplicate your theme’s page.php file, and name it woocommerce.php. This file should be found like this: wp-content/themes/YOURTHEME/woocommerce.php.

2. Edit your page (woocommerce.php)

Open up your newly created woocommerce.php in a text editor, or the editor of your choice.

3. Replace the loop

Next you need to find the loop (see The_Loop). The loop usually starts with a:

<?php if ( have_posts() ) :

and usually ends with:

<?php endif; ?>

This varies between themes. Once you have found it, delete it. In its place, put:

<?php woocommerce_content(); ?>

This will make it use WooCommerce’s loop instead. Save the file. You’re done.

Using hooks

The hook method is more involved, but it is also more flexible. This is similar to the method we use when creating themes. It’s also the method we use to integrate nicely with Twenty Ten to Twenty Sixteen themes.

Insert a few lines in your theme’s functions.php file.

First unhook the WooCommerce wrappers:

remove_action( 'woocommerce_before_main_content', 'woocommerce_output_content_wrapper', 10);
remove_action( 'woocommerce_after_main_content', 'woocommerce_output_content_wrapper_end', 10);

Then hook in your own functions to display the wrappers your theme requires:

add_action('woocommerce_before_main_content', 'my_theme_wrapper_start', 10);
add_action('woocommerce_after_main_content', 'my_theme_wrapper_end', 10);

function my_theme_wrapper_start() {
    echo '<section id="main">';
}

function my_theme_wrapper_end() {
    echo '</section>';
}

Make sure that the markup matches that of your theme. If you’re unsure of which classes or IDs to use, take a look at your theme’s page.php for guidance.

Whenever possible use the hooks to add or remove content. This method is more robust than overriding the templates. If you have overridden a template, you have to update the template any time the file changes. If you are using the hooks, you will only have to update if the hooks change, which happens much less frequently.

Using template overrides

For information about overriding the WooCommerce templates with your own custom templates read the Template Structure section below. This method requires more maintenance than the hook-based method, as templates will need to be kept up-to-date with the WooCommerce core templates.

Declaring WooCommerce Support

If you are using custom WooCommerce template overrides in your theme you need to declare WooCommerce support using the add_theme_support function. WooCommerce template overrides are only enabled on themes that declare WooCommerce support. If you do not declare WooCommerce support in your theme, WooCommerce will assume the theme is not designed for WooCommerce compatibility and will use shortcode-based unsupported theme rendering to display the shop.

Declaring WooCommerce support is straightforward and involves adding one function in your theme’s functions.php file.

Basic Usage

function mytheme_add_woocommerce_support() {
    add_theme_support( 'woocommerce' );
}

add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );

Make sure you are using the after_setup_theme hook and not the init hook. Read more about this at the documentation for add_theme_support.

Usage with Settings

function mytheme_add_woocommerce_support() {
    add_theme_support( 'woocommerce', array(
        'thumbnail_image_width' => 150,
        'single_image_width'    => 300,

        'product_grid'          => array(
            'default_rows'    => 3,
            'min_rows'        => 2,
            'max_rows'        => 8,
            'default_columns' => 4,
            'min_columns'     => 2,
            'max_columns'     => 5,
        ),
    ) );
}

add_action( 'after_setup_theme', 'mytheme_add_woocommerce_support' );

These are optional theme settings that you can set when declaring WooCommerce support.

thumbnail_image_width and single_image_width will set the image sizes for the shop. If these are not declared when adding theme support, the user can set image sizes in the Customizer under the WooCommerce > Product Images section.

The product_grid settings let theme developers set default, minimum, and maximum column and row settings for the Shop. Users can set the rows and columns in the Customizer under the WooCommerce > Product Catalog section.

Product gallery features (zoom, swipe, lightbox)

The product gallery introduced in 3.0.0 (read here for more information) uses Flexslider, Photoswipe, and the jQuery Zoom plugin to offer swiping, lightboxes and other neat features.

In versions 3.0, 3.1, and 3.2, the new gallery is off by default and needs to be enabled using a snippet (below) or by using a compatible theme. This is because it’s common for themes to disable the WooCommerce gallery and replace it with their own scripts.

In versions 3.3+, the gallery is off by default for WooCommerce compatible themes unless they declare support for it (below). 3rd party themes with no WooCommerce support will have the gallery enabled by default.

To enable the gallery in your theme, you can declare support like this:

add_theme_support( 'wc-product-gallery-zoom' );
add_theme_support( 'wc-product-gallery-lightbox' );
add_theme_support( 'wc-product-gallery-slider' );

You do not have to support all 3 parts of the gallery; you can pick and choose features. If a feature is not enabled, the scripts will not be loaded and the gallery code will not execute on product pages.

If gallery features are enabled (e.g. you have a theme which enabled them, or you are running a non-WC compatible theme), you can disable them with remove_theme_support:

remove_theme_support( 'wc-product-gallery-zoom' );
remove_theme_support( 'wc-product-gallery-lightbox' );
remove_theme_support( 'wc-product-gallery-slider' );

You can disable any parts; you do not need to disable all features.

Template Structure

WooCommerce template files contain the markup and template structure for frontend and HTML emails of your store. If some structural change in HTML is necessary, you should override a template.

When you open these files, you will notice they all contain hooks that allow you to add/move content without needing to edit template files themselves. This method protects against upgrade issues, as the template files can be left completely untouched.

Template files can be found within the **/woocommerce/templates/** directory.

How to Edit Files

Edit files in an upgrade-safe way using overrides. Copy it into a directory within your theme named /woocommerce keeping the same file structure but removing the /templates/subdirectory.

Example: To override the admin order notification, copy: wp-content/plugins/woocommerce/templates/emails/admin-new-order.php to wp-content/themes/yourtheme/woocommerce/emails/admin-new-order.php

The copied file will now override the WooCommerce default template file.

CSS Structure

Inside the assets/css/ directory, you will find the stylesheets responsible for the default WooCommerce layout styles.

Files to look for are woocommerce.scss and woocommerce.css.

• woocommerce.css is the minified stylesheet – it’s the CSS without any of the spaces, indents, etc. This makes the file very fast to load. This file is referenced by the plugin and declares all WooCommerce styles.
• woocommerce.scss is not directly used by the plugin, but by the team developing WooCommerce. We use SASS in this file to script the CSS in the first file easier and faster.

The CSS is written to make the default layout compatible with as many themes as possible by using % widths for all layout styles. It is, however, likely that you’ll want to make your own adjustments.

Modifications

To avoid upgrade issues, we advise not editing these files but rather use them as a point of reference.

If you just want to make changes, we recommend adding some overriding styles to your theme stylesheet. For example, add the following to your theme stylesheet to make WooCommerce buttons black instead of the default color:

a.button, 
button.button, 
input.button, 
#review_form #submit {
    background:black; 
}

WooCommerce also outputs the theme name (plus other useful information, such as which type of page is being viewed) as a class on the body tag, which can be useful for overriding styles.

Disabling WooCommerce styles

If you plan to make major changes, or create a theme from scratch, then you may prefer your theme not reference the WooCommerce stylesheet at all. You can tell WooCommerce to not use the default woocommerce.css.

Add the following code to your theme’s functions.php file:

add_filter( 'woocommerce_enqueue_styles', '__return_false' );

With this definition in place, your theme will no longer use the WooCommerce stylesheet and give you a blank canvas upon which you can build your own desired layout/style.

Styling a WooCommerce theme from scratch for the first time is no easy task. There are many different pages and elements that need to be styled, and if you’re new to WooCommerce, you are probably not familiar with many of them. A non-exhaustive list of WooCommerce elements to style can be found here.

Examples

Storefront is the official WooCommerce theme built to the same exact standards as WooCommerce itself. The code is available on GitHub.

If you would like to see examples of other themes that have added WooCommerce support and with their own styles, we suggest looking at the following themes, which can be downloaded from their showcase pages on WordPress.com:

• Karuna
• Shoreditch
• Independent Publisher 2
• Pique
• Libre 2
• Button 2
• Radcliffe 2
• Lodestar

The post WooCommerce Theme Developer Handbook first appeared on CODIBU.

• woocommerce_thumbnail – used in the product ‘grids’ in places such as the shop page.
• woocommerce_single – used on single product pages.
• woocommerce_gallery_thumbnail – used below the main image on the single product page to switch the gallery.

woocommerce_single shows the full product image, as uploaded, so is always uncropped by default. It defaults to 600px width.

woocommerce_gallery_thumbnail is always square cropped and defaults to 100×100 pixels. This is used for navigating images in the gallery.

woocommerce_thumbnail defaults to 600px width, square cropped so the product grids look neat. The aspect ratio for cropping can be customized by the store owner.

It is important to note that despite the actual image widths that are set, themes can ultimately change the size images are displayed using CSS, and image widths may be limited by the product grid/column widths.

Themes can define image sizes

Starting with WooCommerce 3.3.0, themes can declare what sizes should be used when declaring WooCommerce support. If a theme defines the image sizes (widths), the store owner will not be able to change them, but the size defined should be optimal for the theme.

add_theme_support( 'woocommerce', array(
'thumbnail_image_width' => 200,
'gallery_thumbnail_image_width' => 100,
'single_image_width' => 500,
) );

When calling WordPress functions which expect an image size e.g. wp_get_attachment_image_src, you should use the image size names — these are:

• woocommerce_thumbnail
• woocommerce_single
• woocommerce_gallery_thumbnail

Store owners will still be able to control aspect ratio and cropping (see below).

Customize image sizes in the customizer

The customizer houses the options which control thumbnails in WooCommerce.

If the theme is declaring image sizes, the top section will be hidden and only the cropping option will be visible.

Changing the cropping option, or widths, will update the preview on the right side to show how things will look. Changes will not be visible to customers until the customizer is ‘published’ and the thumbnails have been regenerated to the new dimensions.

The thumbnail cropping section in the customizer allows store owners to select one of three cropping ratio settings for images in the catalog:

• 1:1 (Square scropping)
• Custom (Store owner can enter a custom aspect ratio)
• Uncropped (Preserve single image aspect ratio)

Actual image dimensions are then calculated based on the cropping option selected, and the image width.

Changing image sizes via hooks

Whilst themes can fix image sizes at certain widths, and store owners can control widths and aspect ratios, if you need more control over thumbnail sizes there are some hooks available to you.

The wc_get_image_size function is used by WooCommerce to get the image size dimensions. The return value of this is passed through a filter:

woocommerce_get_image_size_{SIZE_NAME_WITHOUT_WOOCOMMERCE_PREFIX}

If using this hook you’ll be passed an array of sizes, similar to this:

array(
'width' => 200,
'height' => 200,
'crop' => 1,
)

So for example, if I wanted to change gallery thumbnails to be 150x150px uncropped images, you could use the following code:

add_filter( 'woocommerce_get_image_size_gallery_thumbnail', function( $size ) {
return array(
'width' => 150,
'height' => 150,
'crop' => 0,
);
} );

We don’t recommend plugins and themes go this route because it removes control from the store owner and their settings won’t be respected, but the option is there for store owners.

Note: after making changes to image sizes you may need to regenerate your thumbnails so the new sizes are used for existing images.

Changing what image sizes are used in WooCommerce via hooks

As well as the above hook, some template functions in WooCommerce run the image size through a filter so you can use something other than the WooCommerce registered image sizes.

The following filters exist:

Note: full is a size registered by WordPress and set in Settings > Media.

As an example, let’s say I wanted to make the gallery thumbnail size used the thumbnail size registered by WordPress instead of woocommerce_gallery_thumbnail. The following snippet would do the job:

add_filter( 'woocommerce_gallery_thumbnail_size', function( $size ) {
return 'thumbnail';
} );

Note: The hooks listed above are used by WooCommerce core. If a theme has custom template files or uses it’s own functions to output images, these filters may not be in use.

The post Image Sizes for Theme Developers first appeared on CODIBU.

We sometimes update the default templates when a new version of WooCommerce is released. This applies to major releases (WooCommerce 2.6, 3.0, and 4.0) but also to minor releases (WooCommerce 3.8.0).

Starting in WooCommerce version 3.3, most themes will look great with WooCommerce.

Our developer focused blog will list any template file changes with each release.

If, however, you are using a theme with older templates or an older version of WooCommerce, you may need to update templates yourself or contact the theme author for an update.

• Most theme authors fix themes in a timely manner, so you only need to update your theme to get the updated templates.
• You need to update templates yourself if you modified templates or are using a child theme.

Otherwise, you need to select and use a different theme that already uses current WooCommerce templates.

How to update outdated templates

We need to determine what templates to update, make a backup of old templates and then restore any customizations.

1. Go to: WooCommerce > Status > System Status. Scroll to the end of the page where there is a list of templates overridden by your theme/child theme and a warning message that they need to be updated. For example, the templates form-pay.php and form-login.phph are outdated:

2. Save a backup of the outdated template.
3. Copy the default template from wp-content/plugins/woocommerce/templates/[path-to-the-template] and paste it in your theme folder found at: wp-content/themes/[path-to-theme]
4. Open the template you pasted into the theme folder with a text editor of choice, such as Atom, Visual Code, BBEdit, Notepad++, and replicate any changes that you had to the previous template in your new, updated template file.

We recognize that it can be time-consuming. This is why we try to avoid changing WooCommerce templates, but sometimes it is wise to break backward compatibility.

FAQ

Where can I find the latest version of WooCommerce?

If you’re looking for the default templates to use for updating, you want to use the latest version of WooCommerce. There are a few easy ways to get the templates:

• Access the files via FTP if your current WooCommerce installation is up to date.
• Find the templates per WooCommerce version in our Template Structure documentation.
• Download the latest version from the WordPress.org plugin page.
• Download all versions from the GitHub repository.

Why don’t you make a button to click and update everything?

It’s impossible to make a video or a one-click update. Why? Because there are thousands of themes, and every theme is coded differently. One size does not fit all.

The post Fixing Outdated WooCommerce Templates first appeared on CODIBU.

The post Display Category Image on Category Archive first appeared on CODIBU.

get_product_search_form()

For more info, see: Function get_product_search_form.

It then looks for the product search form in the file ‘product-searchform.php’ or uses its default markup. You can override the default WooCommerce template product-searchform.php by customizing the markup.

For reference, the default markup is:

The post Overriding the product search box (widget) first appeared on CODIBU.

The conditional tags of WooCommerce and WordPress can be used in your template files to change what content is displayed based on what conditions the page matches. For example, you may want to display a snippet of text above the shop page. With the is_shop() conditional tag, you can.

Because WooCommerce uses custom post types, you can also use many of WordPress’ conditional tags. See: http://codex.wordpress.org/Conditional_Tags for a list of the tags included with WordPress.

Available conditional tags

All conditional tags test whether a condition is met, and then return either TRUE or FALSE. Conditions under which tags output TRUE are listed below the conditional tags.

The list below holds the main conditional tags. To see all conditional tags, visit the WooCommerce API Docs.

WooCommerce page

is_woocommerce()

Returns true if on a page which uses WooCommerce templates (cart and checkout are standard pages with shortcodes and thus are not included).

Main shop page

is_shop()

Returns true when on the product archive page (shop).

Product category page

is_product_category()

Returns true when viewing a product category archive.

is_product_category( 'shirts' )

When the product category page for the ‘shirts’ category is being displayed.

is_product_category( array( 'shirts', 'games' ) )

When the product category page for the ‘shirts’ or ‘games’ category is being displayed.

Product tag page

is_product_tag()

Returns true when viewing a product tag archive

is_product_tag( 'shirts' )

When the product tag page for the ‘shirts’ tag is being displayed.

is_product_tag( array( 'shirts', 'games' ) )

When the product tag page for the ‘shirts’ or ‘games’ tags is being displayed.

Single product page

is_product()

Returns true on a single product page. Wrapper for is_singular.

Cart page

is_cart()

Returns true on the cart page.

Checkout page

is_checkout()

Returns true on the checkout page.

Customer account pages

is_account_page()

Returns true on the customer’s account pages.

Endpoint

is_wc_endpoint_url()

Returns true when viewing a WooCommerce endpoint

is_wc_endpoint_url( 'order-pay' )

When the endpoint page for order pay is being displayed.

is_wc_endpoint_url( 'order-received' )

When the endpoint page for order received is being displayed.

is_wc_endpoint_url( 'view-order' )

When the endpoint page for view order is being displayed.

is_wc_endpoint_url( 'edit-account' )

When the endpoint page for edit account is being displayed.

is_wc_endpoint_url( 'edit-address' )

When the endpoint page for edit address is being displayed.

is_wc_endpoint_url( 'lost-password' )

When the endpoint page for lost password is being displayed.

is_wc_endpoint_url( 'customer-logout' )

When the endpoint page for customer logout  is being displayed.

is_wc_endpoint_url( 'add-payment-method' )

When the endpoint page for add payment method is being displayed.

Ajax request

is_ajax()

Returns true when the page is loaded via ajax.

Working example

The example illustrates how you would display different content for different categories.

The post Conditional Tags first appeared on CODIBU.

Inside the assets/css/ directory, you will find the stylesheets responsible for the default WooCommerce layout styles.

Files to look for are woocommerce.scss and woocommerce.css.

• woocommerce.css is the minified stylesheet – it’s the CSS without any of the spaces, indents, etc. This makes the file very fast to load. This file is referenced by the plugin and declares all WooCommerce styles.
• woocommerce.scss is not directly used by the plugin, but by the team developing WooCommerce. We use SASS in this file to script the CSS in the first file easier and faster.

The CSS is written to make the default layout compatible with as many themes as possible by using % widths for all layout styles. It is, however, likely that you’ll want to make your own adjustments.

Modifications

To avoid upgrade issues, we advise not editing these files but rather use them as a point of reference.

If you just want to make changes, we recommend adding some overriding styles to your theme stylesheet. For example, add the following to your theme stylesheet to make WooCommerce buttons black instead of the default color:

a.button, 
button.button, 
input.button, 
#review_form #submit {
  background:black; 
}

WooCommerce also outputs the theme name (plus other useful information, such as which type of page is being viewed) as a class on the body tag, which can be useful for overriding styles.

Disabling WooCommerce styles

If you plan to make major changes, then you may prefer your theme not reference the WooCommerce stylesheet at all. You can tell WooCommerce to not use the default woocommerce.css. See the following tutorial for disabling WooCommerce style sheets.

Contributing

If you are contributing to WooCommerce core and need to edit the style, please edit the Sass files and then compile them by using Grunt. To know more about what Grunt tasks we use, check out the file Gruntfile.js inside the root of WooCommerce. You can read more about Grunt here.

The post CSS Structure first appeared on CODIBU.

When you open these files, you will notice they all contain hooks that allow you to add/move content without needing to edit template files themselves. This method protects against upgrade issues, as the template files can be left completely untouched.

Template files can be found within the /woocommerce/templates/ directory:

How to Edit Files

Edit files in an upgrade-safe way using overrides. Copy the template into a directory within your theme named /woocommerce keeping the same file structure but removing the /templates/ subdirectory.

Example: To override the admin order notification, copy: wp-content/plugins/woocommerce/templates/emails/admin-new-order.php to wp-content/themes/yourtheme/woocommerce/emails/admin-new-order.php

The copied file will now override the WooCommerce default template file.

Warning: Do not edit these files within the core plugin itself as they are overwritten during the upgrade process and any customizations will be lost. For more detailed information, see Fixing Outdated WooCommerce Templates.

For Custom Templates

If you are a theme developer or using a theme with custom templates, you must declare WooCommerce theme support using the add_theme_support function. See Declaring WooCommerce Support in Themes at GitHub.

If your theme has a woocommerce.php file, you will be unable to override the woocommerce/archive-product.php custom template in your theme, as woocommerce.php has priority over other template files. This is intended to prevent display issues.

The post Template structure & Overriding templates via a theme first appeared on CODIBU.