Template Override Precedence System

When themes copy WooCommerce templates to yourtheme/woocommerce/ for customization, and Donation Platform for WooCommerce needs to override the same templates for donation features, a conflict arises. Donation Platform for WooCommerce Version <= 1.4.0 “theme always wins” bailout that sometimes blocked some donation features.

Three-Tier Precedence System

Tier 1: Explicit Donation Platform for WooCommerce Theme Overrides (Highest Priority)

Create Donation Platform for WooCommerce-specific template overrides that always take precedence:

Location: yourtheme/wc-donation-platform/{namespace}/{template-path}

yourtheme/
└── wc-donation-platform/
    ├── woocommerce/
    │   ├── checkout/form-login.php
    │   └── emails/customer-completed-order.php
    │   └── single-product/add-to-cart/product.php
    └── woocommerce-subscriptions/
        └── myaccount/my-subscriptions.php

Use this tier when you need donation-specific customizations separate from regular WooCommerce templates. Explicit overrides win regardless of the precedence mode.

Tier 2: Theme WooCommerce Overrides (Configurable)

When the theme has a WooCommerce override but no explicit Donation Platform for WooCommerce override, the wcdp_template_override_precedence filter decides:

ModeBehavior
'plugin' (default)The Donation Platform for WooCommerce template wins
'theme'The theme template wins, except for single-product/* templates
'theme_force'The theme template always wins
add_filter('wcdp_template_override_precedence', function($mode, $template_name) {
    // Restore the legacy behavior: theme wins, except on single product pages.
    return 'theme';
}, 10, 2);

Filter Parameters:

ParameterTypeDescription
$modestringCurrent mode, default 'plugin'
$template_namestringTemplate path (e.g., 'checkout/payment.php')
$templatestringFull path to theme template
$plugin_templatestringFull path to Donation Platform for WooCommerce template
$namespacestring'woocommerce' or 'woocommerce-subscriptions'

Tier 3: No Theme Override (Default)

When the theme has no WooCommerce override, the Donation Platform for WooCommerce template is used automatically.

Backward Compatibility

The default 'plugin' mode is a behavior change: Donation Platform for WooCommerce templates now win over theme WooCommerce overrides in donation contexts (checkout, emails, single product donation form). Previously the theme won everywhere except single-product/*.

To keep the old behavior site-wide, set the filter to 'theme':

add_filter('wcdp_template_override_precedence', function($mode) {
    return 'theme';
});

To make the theme win everywhere, including single-product/*:

add_filter('wcdp_template_override_precedence', function($mode) {
    return 'theme_force';
});

Configuration Examples

Selective Template Control

Theme wins for checkout templates, Donation Platform for WooCommerce elsewhere:

add_filter('wcdp_template_override_precedence', function($mode, $template_name) {
    if (strpos($template_name, 'checkout/') === 0) {
        return 'theme';
    }
    return $mode;
}, 10, 2);

Per-Site Configuration (Multisite)

add_filter('wcdp_template_override_precedence', function($mode, $template_name) {
    return (get_current_blog_id() === 5) ? 'theme_force' : $mode;
}, 10, 2);

Debugging

Check Which Template is Used

add_filter('wcdp_get_template', function($template, $template_name) {
    error_log("Donation Platform for WooCommerce using: {$template} for {$template_name}");
    return $template;
}, 10, 2);

Related Articles