Steve-Dee-Designs
/
woocommerce
mirror of https://github.com/woocommerce/woocommerce.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

fix spelling, grammar, etc.

This commit is contained in:
Leif Singer 2023-11-29 13:43:21 +01:00
parent 6e039e8578
commit 75e3cc3185
1 changed files with 31 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
docs/theme-development/classic-theme-developer-handbook.md
View File

@ -2,7 +2,7 @@
---
**Note:** this doc is heared toward the development of classic themes. Visit [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/) to learn about block theme development, and explore the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a new theme.
**Note:** this document is geared toward the development of classic themes. For the recommended modern approach, visit [Develop Your First Low-Code Block Theme](https://learn.wordpress.org/course/develop-your-first-low-code-block-theme/) to learn about block theme development, and explore the [Create Block Theme plugin](https://wordpress.org/plugins/create-block-theme/) tool when you're ready to create a new theme.
---
@ -12,29 +12,29 @@ 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
- Comments enabled, not Reviews – visitors/buyers can leave comments as opposed to 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.
There are three possible ways to integrate WooCommerce with a theme. If you are using WooCommerce 3.2 or below (**strongly discouraged**) 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()
### 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.
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 WooCommerce taxonomies** (product categories, etc.) and **post types** (product archives, single product pages). Developers are encouraged to use the hooks instead (see below).
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](http://codex.wordpress.org/The_Loop)). The loop usually starts with a:
1. **Duplicate page.php:** Duplicate your theme’s `page.php` file, and name it `woocommerce.php`. This path to the file should follow this pattern: `wp-content/themes/YOURTHEME/woocommerce.php`.
2. **Edit your page (woocommerce.php)**: Open up your newly created `woocommerce.php` in a text editor.
3. **Replace the loop:** Next you need to find the loop (see [The_Loop](https://codex.wordpress.org/The_Loop)). The loop usually starts with code like this:
```php
<?php if ( have_posts() ) :
```
and usually ends with:
It usually ends with this:
```php
<?php endif; ?>
@ -48,13 +48,13 @@ This varies between themes. Once you have found it, **delete it**. In its place,
This will make it use **WooCommerce’s loop instead**. Save the file. You’re done.
**Note:** When creating woocommerce.php in your theme’s folder, you will not be able to override the woocommerce/archive-product.php custom template as woocommerce.php has priority over archive-product.php. This is intended to prevent display issues.
**Note:** When creating `woocommerce.php` in your theme’s folder, you will not be able to override the `woocommerce/archive-product.php` custom template as `woocommerce.php` has priority over `archive-product.php`. This is intended to prevent display issues.
### 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.
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 WordPress default themes.
Insert a few lines in your **theme’s functions.php** file.
Insert a few lines in your theme’s `functions.php` file.
First unhook the WooCommerce wrappers:
@ -78,19 +78,19 @@ function my_theme_wrapper_end() {
}
```
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.
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.
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.
Declaring WooCommerce support is straightforward and involves adding one function in your theme’s `functions.php` file.
### Basic Usage
@ -102,7 +102,7 @@ function mytheme_add_woocommerce_support() {
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.
Make sure you are using the `after_setup_theme` hook and not the `init` hook. Read more about this in [the documentation for `add_theme_support`](https://developer.wordpress.org/reference/functions/add_theme_support/).
### Usage with Settings
@ -134,7 +134,7 @@ The `product_grid` settings let theme developers set default, minimum, and maxim
### Product gallery features (zoom, swipe, lightbox)
The product gallery introduced in 3.0.0 ([read here for more information](https://developer.woo.com/2016/10/19/new-product-gallery-merged-in-to-core-for-2-7/)) uses Flexslider, Photoswipe, and the jQuery Zoom plugin to offer swiping, lightboxes and other neat features.
The product gallery introduced in 3.0.0 ([read here for more information](https://developer.woo.com/2016/10/19/new-product-gallery-merged-in-to-core-for-2-7/)) 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.
@ -148,9 +148,9 @@ 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.
You do not have to support all three 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`:
If gallery features are enabled (e.g., you have a theme that enabled them, or you are running a theme that is not compatible with WooCommerce), you can disable them with `remove_theme_support`:
```php
remove_theme_support( 'wc-product-gallery-zoom' );
@ -162,23 +162,23 @@ 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.
WooCommerce template files contain the **markup** and **template structure** for **the frontend and the 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.
When you open these files, you will notice they all contain **hooks** that allow you to add or move content without needing to edit the 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.
Edit files in an **upgrade-safe way** using *overrides*. Copy them 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`
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 delete any of WooCommerce hooks when overriding a template. This would prevent plugins hooking in to add content.
**Warning:** Do not delete any WooCommerce hooks when overriding a template. This would prevent plugins hooking in to add content.
**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.
**Warning:** Do not edit these files within the core plugin itselfe as they are overwritten during the upgrade process and any customizations will be lost.
## CSS Structure
@ -187,12 +187,13 @@ Inside the `assets/css/` directory, you will find the stylesheets responsible fo
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](http://sass-lang.com/) 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.
- `woocommerce.scss` is not directly used by the plugin, but by the team developing WooCommerce. We use [SASS](http://sass-lang.com/) in this file to generate the CSS in the first file.
The CSS is written to make the default layout compatible with as many themes as possible by using percentage-based 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.
To avoid upgrade issues, we advise not editing these files but rather using 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:
@ -209,14 +210,12 @@ WooCommerce also outputs the theme name (plus other useful information, such as
### 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:
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` by adding the following code to your theme’s `functions.php` file:
```php
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.
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 and styles.
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](https://developer.files.wordpress.com/2017/12/woocommerce-theme-testing-checklist.pdf).