Use this guide to assess customizations for the Purple block theme, identify the relevant theme files, and choose an approach that survives updates. It also explains how to review Storefront child-theme customizations before rebuilding them for Purple.
Note:
This is a Developer level doc. If you are unfamiliar working with code and resolving potential conflicts, we recommend you work with a Woo Agency Partner for larger projects, or find a WooCommerce developer on Codeable for smaller customizations. We are unable to provide support for customizations under our Support Policy.
Before you start
↑ Back to top- Work on a staging site and keep the Purple, WordPress, WooCommerce, and extension versions under version control.
- Review the exact Purple release or commit before relying on a file path or behavior described here.
- Purple currently requires WordPress 7.1 or later, WooCommerce 11.1 or later, and PHP 7.4 or later. Check the latest released version in the WordPress.org theme directory, then verify the requirements in the theme package you plan to use. The trunk repository can change before an installed release does.
Choose a customization path
↑ Back to top| Goal | Recommended approach |
|---|---|
| Change a store’s content or appearance | Use the Site Editor and Purple’s styles, templates, template parts, and patterns. |
| Reuse a section across a store | Create or edit a block pattern. |
| Add store functionality | Use a plugin or WooCommerce-supported extension point. |
| Make a durable theme-level change | Use a child block theme or custom theme only when the change cannot be maintained in the Site Editor. Test it against theme and WordPress updates. |
Do not edit files in the installed Purple theme directly. Direct edits can be lost when the theme is updated.
For each Storefront action, filter, or child-theme customization, record the visible result and any behavior it changes. First try reproducing the layout in the Site Editor. Use a pattern for repeated layout, a plugin or supported WooCommerce extension point for functionality, or document a deliberate design change. Storefront-specific hooks are not a migration API for Purple; verify that any hook you retain runs in the new block-based flow.
Review customizations to Storefront’s template-homepage.php against Purple’s templates/front-page.html. Purple’s front-page template loads its storefront pattern rather than the assigned page’s content, so editing that page alone may not change the homepage.
For Storefront’s template-fullwidth.php, choose a suitable Purple page template and use wide or full-width block alignment where available. Purple includes Page no title, Page with cover, and Blank template options, but these are not file-for-file replacements for a customized Storefront layout.
Understand the theme structure
↑ Back to top| Location | Purpose |
|---|---|
theme.json | Defines global settings, styles, layout options, typography, colors, and editor-supported design controls. |
/templates | Defines the layouts used by pages, archives, products, the cart, checkout, and other site views. |
/parts | Defines reusable template parts such as headers and footers. |
/patterns | Provides reusable groups of blocks for pages and templates. |
functions.php | Contains theme bootstrap code and supported theme behavior. Use plugins for functionality that should not depend on the active theme. |
Templates, parts, and patterns
↑ Back to topThese files have different responsibilities:
- A template describes the layout for a type of page, such as a product archive or a single product.
- A template part describes a reusable section that appears in multiple templates, such as a header or footer.
- A pattern is a reusable group of blocks that can be inserted into a page or template and then edited.
A change to a shared template or template part can affect many customer-facing pages. Review more than one page of the relevant type after making a change.
Templates saved in the Site Editor are stored in the database and take precedence over matching child-theme and parent-theme files. If a file change does not appear, check for a saved template customization before replacing files or resetting the template. Back up that customization first. See the WordPress template documentation for the lookup order and guidance on distributing template changes.
Patterns and core blocks
↑ Back to topPurple includes theme-specific patterns and uses WordPress and WooCommerce core blocks. Pattern availability and categories can change as core pattern registration evolves, so rely on the current release in the Site Editor rather than fixed pattern counts or assumptions about which patterns are available.
Starter patterns may contain example copy, images, links, categories, and promotional details. Configure them for the store before treating them as production content.
WooCommerce templates and blocks
↑ Back to topPurple uses block templates for the catalog, single product, cart, checkout, and order confirmation. The cart and checkout templates wrap the assigned pages’ content; they do not replace that content with a new Cart or Checkout block. Check the assigned pages and their content as well as the surrounding template.
My Account is a separate customer journey to test, not a dedicated My Account template supplied by this Purple release. Review account-page content and any extension-added endpoints. When changing a WooCommerce template, test the states your store supports, including:
- Products with and without variations, images, reviews, or stock.
- Empty and filled carts, coupons, shipping calculations, and payment methods.
- Logged-out and logged-in customer accounts.
- Extension-added fields, blocks, sections, pages, and customer workflows.
For WooCommerce-specific block theming guidance, see Theming WooCommerce blocks.
Keep customizations update-safe
↑ Back to top- Keep custom templates, patterns, styles, and theme code in version control.
- Use a child block theme or a plugin when a change must survive updates.
- Test changes on a staging site with the WordPress, WooCommerce, Purple, and extension versions that your store uses.
- Review the complete shopping path after updating templates or WooCommerce blocks.
If a change breaks a layout or affects unexpected pages, review the shared template or template part you changed. Restore its previous version on staging and repeat the affected customer journey before transferring the change to the live store.
Release and compatibility testing
↑ Back to top- Test the exact WordPress, WooCommerce, Purple, and extension versions you plan to support.
- Check the catalog, product, cart, checkout, order confirmation, and account flows, including fields or blocks added by extensions.
- Record the Purple release or source revision, the versions tested, known limitations, and the results before recommending the change.
