WooCommerce Category to Page Breadcrumb Mapper

A lightweight WordPress plugin that lets you map WooCommerce product categories to WordPress pages, replacing the default WooCommerce category trail in breadcrumbs with a custom page-based hierarchy on single product pages.

---

Overview

By default, WooCommerce breadcrumbs on product pages follow the product category hierarchy:

Home > Category > Product Name

This plugin allows you to override that behaviour on a per-category basis, replacing the category segment with any WordPress page (including its full ancestor chain):

Home > Parent Page > Mapped Page > Product Name

This is particularly useful when:

• Your site navigation is built around WordPress pages rather than WooCommerce categories
• You want products to appear contextually "under" a specific page in the breadcrumb trail
• Your categories don't map cleanly to the visual structure of your site

---

Requirements

Requirement	Details
WordPress	5.0+
WooCommerce	Any version with product_cat taxonomy
Breadcrumb Plugin	Must use the catch_breadcrumb_trail filter (e.g. Catch themes or compatible breadcrumb plugins)
PHP	7.4+

Important: This plugin hooks into the catch_breadcrumb_trail filter. It is only compatible with breadcrumb implementations that apply this filter. It will not affect breadcrumbs from Yoast SEO, RankMath, or other plugins that use their own filters.

---

Installation

1. Download or clone this repository.
2. Copy cat-page-breadcrumb-map.php into your WordPress plugins directory:

   wp-content/plugins/cat-page-breadcrumb-map/cat-page-breadcrumb-map.php

3. Log in to your WordPress admin dashboard.
4. Navigate to Plugins > Installed Plugins.
5. Find WooCommerce Category to Page Breadcrumb Mapper and click Activate.

---

Configuration

Mapping a Category to a Page

1. In the WordPress admin, go to Products > Categories.
2. Click on an existing category to edit it, or create a new one.
3. Locate the Breadcrumb Parent Page field.
4. Use the dropdown to select any published WordPress page.
5. Save the category.

The selected page will now act as the breadcrumb parent for all products assigned to that category.

The Breadcrumb Parent Page Field

• Available on both the Add Category and Edit Category screens.
• Displays all published WordPress pages in a dropdown.
• Selecting — None — leaves the breadcrumb unchanged (default WooCommerce behaviour).
• The mapping is stored as term meta (breadcrumb_page_id) on the category.

---

How It Works

1. Admin UI — Category Fields

The plugin registers two action hooks to inject the Breadcrumb Parent Page dropdown into the WooCommerce category taxonomy screens:

• product_cat_add_form_fields — adds the field to the "Add Category" form
• product_cat_edit_form_fields — adds the field to the "Edit Category" form

2. Saving the Mapping

On category save (both create and update), the plugin hooks into:

• created_product_cat
• edited_product_cat

It reads $_POST['breadcrumb_page_id'], sanitises it with absint(), and stores it as term meta against the category.

3. Breadcrumb Override

The core logic runs via the catch_breadcrumb_trail filter (priority 20). On single product pages (is_singular('product')), the plugin:

1. Retrieves all categories assigned to the current product.
2. Iterates through them to find the first category that has a breadcrumb_page_id mapped.
3. Looks up the full ancestor chain of the mapped page using get_post_ancestors().
4. Constructs a new breadcrumb trail in this order:
   • Home — links to home_url('/')
   • Ancestor pages — any parent pages above the mapped page, in order from root down
   • Mapped page — the page selected in the category settings, with its permalink
   • Product name — the current product title, with no link (terminal crumb)
5. Returns the new trail, replacing the default WooCommerce category breadcrumb.

If no mapped category is found, the original trail is returned unchanged.

---

Breadcrumb Trail Examples

Without the plugin (default WooCommerce)

Home > Clothing > T-Shirts > My T-Shirt

With the plugin — flat page mapped

Home > Shop > My T-Shirt

With the plugin — nested page hierarchy

Home > Collections > Seasonal > Summer > My T-Shirt

---

Code Reference

Function	Hook	Description
wcctp_add_page_field()	product_cat_add_form_fields	Renders the page dropdown on the Add Category screen
wcctp_edit_page_field($term)	product_cat_edit_form_fields	Renders the page dropdown on the Edit Category screen, pre-selecting the saved value
wcctp_save_page_field($term_id)	created_product_cat, edited_product_cat	Saves the selected page ID as term meta
wcctp_override_product_breadcrumb($trail)	catch_breadcrumb_trail	Rebuilds the breadcrumb trail on single product pages

Term Meta Key

breadcrumb_page_id

Stored on each product_cat term. Value is the integer post ID of the mapped WordPress page, or 0 / empty if none is set.

---

Limitations

• Only the first category with a mapped page is used when a product belongs to multiple categories.
• Only compatible with breadcrumb plugins/themes that apply the catch_breadcrumb_trail filter.
• Does not affect breadcrumbs on category archive pages — only on single product pages.
• No support for WooCommerce subcategory nesting in the replacement trail; the mapped page's WordPress ancestor hierarchy is used instead.

---

Author

Darren Kandekore

---

License

This plugin was developed for a specific client requirement. All rights reserved unless otherwise stated.