Template Overrides

{/* AUTO-GENERATED from ../docs/template-overrides.md by scripts/sync-dev-docs.mjs — do not edit by hand. */}

Overview

Dino Discounts ships PHP templates for three storefront components: the product-page tier table, the product-page promo message, and the spend-more nudge. Cart and checkout discount lines, notices and the mini-cart discount block are not template-driven. Theme authors and agencies can replace any template by placing a copy in their theme directory. The plugin renders from the theme copy instead of its own.

When to override:

• You need HTML structure changes that CSS can’t solve (e.g. adding a wrapper, reordering elements).
• You need to inject additional data from your theme (e.g. ACF fields, custom post meta).
• Your design system requires semantic markup the default template doesn’t produce.

When not to override:

• You only need visual changes — use CSS targeting .dd-* classes instead (see the CSS / Styling Reference for the per-surface class inventory and dequeue-able handles).
• You want to change copy — the nudge and product-page message text is authored per discount (Messaging section); for code-level tweaks use the dino_discounts_nudge_html or dino_discounts_storefront_message filter. Fixed strings such as the tier-table column headers are translatable, so gettext works for those.
• You want to suppress a component entirely — for nudges, set the surface’s slot to Not shown or turn off Enable spend-more nudges in Message Settings; for a product-page promo, untick Show on product page in the discount’s Messaging section. In code, return an empty string from dino_discounts_nudge_html / dino_discounts_storefront_message. The plugin registers its storefront callbacks through a wrapper, so remove_action() cannot detach them.

---

Override Mechanism

Copy the template from the plugin into your theme, preserving its relative path under a dino-discounts/ directory:

yourtheme/
└── dino-discounts/
    ├── storefront/
    │   ├── tier-table.php
    │   ├── discount-message.php
    │   └── spend-more-nudge.php
    └── mini-cart-discounts.php

Search order (first match wins):

1. {child_theme}/dino-discounts/{template_name}
2. {parent_theme}/dino-discounts/{template_name}
3. {plugin}/templates/{template_name}

Variables are extracted into the template’s local scope via extract() — the same pattern WooCommerce uses. Every variable listed in each template’s docblock is available as a plain PHP variable inside the template file.

---

Per-Template Variable Reference

storefront/tier-table.php

Purpose: Tier pricing table rendered on single product pages for tiered and bulk discounts, showing quantity/spend thresholds and the corresponding discount for each tier. Where it sits on the page is the store-wide Message Settings → Product-page promo → Position setting (Above Add to Cart or Below price).

Override path: yourtheme/dino-discounts/storefront/tier-table.php

Since: 4.15.0

Stability: ⚠️ Risky — see Stability Guide

Variable	Type	Description
$tiers	array	Sorted array of tier objects. Each entry has threshold (int/float), reward_type (string), and reward_value (float).
$type	string	Discount type: 'tiered' or 'bulk' (the table only renders for these two). Controls which column headers are rendered.
$trigger_metric	string	What the threshold measures: 'quantity' or 'cart_subtotal'. Bulk discounts are always 'quantity'.
$product_price	float	Current product price, used to compute the discounted unit price in percent/fixed rows.
$currency	string	Currency symbol for the shopper’s current currency (falls back to the store currency). Passed for convenience; the default template uses wc_price() directly rather than this variable.
$rule	array	Full discount rule array from the engine. Useful for advanced customisation; schema may change between minor versions.
$product	\WC_Product	WooCommerce product object for the page being rendered.

Reward type values ($tier['reward_type']): 'percent_off', 'fixed_amount_off', 'free_shipping', 'free_item'.

---

storefront/discount-message.php

Purpose: Promotional message rendered on single product pages (e.g. “Buy 3, save 20%”), used when a discount advertises with a custom message rather than a tier table. The message string is fully resolved (and has passed the dino_discounts_storefront_message filter) before the template receives it. Placement follows the same Product-page promo → Position setting as the tier table.

Override path: yourtheme/dino-discounts/storefront/discount-message.php

Since: 4.15.0

Stability: ✅ Safe — see Stability Guide

Variable	Type	Description
$message	string	Resolved message HTML. Placeholders have already been replaced and the value is wp_kses_post-safe.
$rule	array	Full discount rule array. Use for conditional rendering; schema may change between minor versions.
$product	\WC_Product	WooCommerce product object.

---

storefront/spend-more-nudge.php

Purpose: “Spend more” nudge bar rendered in the cart, checkout, and mini-cart (classic and block), showing how much more the shopper needs to spend to unlock the next discount tier. At most one nudge renders per surface, in the slot chosen in Message Settings → Spend-more nudge.

Override path: yourtheme/dino-discounts/storefront/spend-more-nudge.php

Since: 4.15.0

Stability: ✅ Safe — see Stability Guide

Variable	Type	Description
$message	string	Resolved nudge message HTML. Placeholders have already been replaced and the value is wp_kses_post-safe.
$modifier_class	string	Space-separated CSS modifier classes added to the wrapper (e.g. 'dd-spend-more-nudge--cart-page dd-position-bottom').
$rule	array	Full discount rule array.
$delta	float	Monetary gap between the shopper’s current spend and the next threshold.
$context	string	Where the nudge is displayed: 'mini', 'cart', or 'checkout'.
$position	string	The slot it renders in: 'top' or 'bottom' on every surface, plus 'before_buttons' (mini-cart), 'before_checkout_button' (cart) and 'before_order_review' / 'before_payment' (checkout).

---

mini-cart-discounts.php (legacy)

See Legacy Note below.

---

Stability Guide

Safe overrides

discount-message.php and spend-more-nudge.php are stable override targets. Their variable contracts are intentionally narrow:

• $message is a pre-rendered, already-escaped string. You can wrap it, hide it, or replace it with your own markup without touching engine internals.
• $rule is passed for context but your template does not need to consume it. If you do read from $rule, be aware the schema can change on minor version bumps (see version-skew section below).
• Other variables ($delta, $context, $position) are plain scalars unlikely to change semantics.
• In spend-more-nudge.php, keep the outer <div class="dd-spend-more-nudge <?php echo esc_attr( $modifier_class ); ?>">. WooCommerce cart fragments find the nudge by those classes to refresh it after a cart update.

Risky overrides

tier-table.php is tightly coupled to the engine rule schema. It reads $tiers, $type, and $trigger_metric — all of which are derived directly from internal engine data. When the engine gains a new reward type or trigger metric, the default template is updated in the same release. If you have overridden this template, your copy will not receive that update and may silently mis-render new tiers or omit new reward types.

Mitigation if you must override tier-table:

• Copy the default template in full and make the minimum change needed.
• Subscribe to the changelog. Any release that touches includes/Engine/, includes/Storefront/StorefrontDisplay.php or templates/storefront/tier-table.php requires you to merge upstream changes into your copy.
• Add a comment at the top of your copy recording the plugin version it was based on (e.g. // Based on Dino Discounts 4.15.0).

Version-skew detection

There is currently no automatic template-version check. To detect drift manually:

1. After each plugin update, run:

   diff wp-content/plugins/dino-discounts/templates/storefront/tier-table.php \
        wp-content/themes/yourtheme/dino-discounts/storefront/tier-table.php

2. Review the diff against the plugin changelog before going live.

---

Filter: dino_discounts_locate_template

Intercept template resolution and point any template at a custom path — useful for plugins, page builders, or multi-theme setups that can’t use the standard theme directory.

/**
 * Signature:
 *   apply_filters( 'dino_discounts_locate_template', string $template, string $template_name )
 *
 * @param string $template      Absolute path to the resolved template (child/parent theme or plugin fallback).
 * @param string $template_name Relative template name that was requested (e.g. 'storefront/tier-table.php').
 * @return string Absolute path to use instead.
 */
add_filter( 'dino_discounts_locate_template', function ( string $template, string $template_name ): string {
    // Redirect the tier table to a custom location for a specific child theme.
    if ( 'storefront/tier-table.php' === $template_name && is_child_theme() ) {
        $custom = get_stylesheet_directory() . '/my-custom-templates/tier-table.php';
        if ( file_exists( $custom ) ) {
            return $custom;
        }
    }
    return $template;
}, 10, 2 );

The filter fires on every template load, so keep the callback fast (a single file_exists() check is fine; a database query is not).

---

Actions: dino_discounts_before_template and dino_discounts_after_template

Run code just before or after any template loads, without replacing it. Useful for logging, timing, or setting up state your template override reads.

Both actions pass 3 arguments: $template_name, $template_path, and $args. Always register with accepted_args = 3 (the fourth parameter to add_action) so WordPress passes all three to your callback (see includes/Storefront/template-functions.php).

/**
 * Signature (both actions share the same parameters):
 *   do_action( 'dino_discounts_before_template', string $template_name, string $template_path, array $args )
 *   do_action( 'dino_discounts_after_template',  string $template_name, string $template_path, array $args )
 *
 * @param string $template_name Relative template name (e.g. 'storefront/spend-more-nudge.php').
 * @param string $template_path Absolute path to the resolved template file.
 * @param array  $args          All variables passed into the template (same keys as the variable tables above).
 */

// Example: log which templates fire on a page (development only).
// $args contains all variables passed into the template.
add_action(
    'dino_discounts_before_template',
    function ( string $template_name, string $template_path, array $args ): void {
        if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log
            error_log( 'dino_discounts template: ' . $template_name . ' from ' . $template_path );
        }
    },
    10,
    3
);

Do not use these actions to wrap markup. dino_discounts_get_template() captures the template’s output via ob_start() / ob_get_clean() and returns it as a string, and both actions fire outside that buffer. Anything you echo from them is printed straight away, before the plugin outputs the template HTML, and never reaches the nudge HTML sent in cart fragments or the Store API. To change the markup, override the template or filter the result instead:

// Example: add an icon inside the spend-more nudge.
// Keep changes inside the nudge's own <div>: cart-fragment refreshes replace
// that element, so a wrapper added outside it would pile up on each refresh.
add_filter( 'dino_discounts_nudge_html', function ( string $html ): string {
    return preg_replace( '/(<div[^>]*>)/', '$1<span class="mytheme-nudge-icon" aria-hidden="true"></span>', $html, 1 );
} );

---

Legacy Note: mini-cart-discounts.php

templates/mini-cart-discounts.php is a legacy artifact. The current mini-cart rendering path is JavaScript-driven (assets/js/cart-ui-sync.js, reading from window.dinoDiscountsMiniCart). The PHP template is no longer called during a normal page load.

Overriding this file has no effect on what shoppers see in the mini-cart. To change the mini-cart discount display you have two supported, override-free paths:

• Visual changes — target the .dd-* classes with CSS. The per-surface class inventory, DOM skeleton, custom properties, and the dequeue-able dino-discounts-discount-display handle are documented in the CSS / Styling Reference.

• Markup changes — register a JS render filter on the live sync layer (assets/js/cart-ui-sync.js). This is the markup-level extension point for the JS-rendered surface — the counterpart to a PHP template override:

  // fn( html, { discounts, currency } ) → html
  // `html` is the discount block's inner markup (.dd-discount-line rows);
  // return the markup to render. Filters run in registration order;
  // registering re-renders the open drawer immediately.
  var unsubscribe = window.__dinoCartUISync.addRenderFilter( function ( html, context ) {
      return '<span class="my-theme-badge">Deal!</span>' + html;
  } );
  // Call `unsubscribe()` to remove the filter.

  A filter that throws or returns a non-string is ignored, so one misbehaving consumer cannot break the render for others.

The file is retained for third-party code that loads it directly.

---

Testing Checklist

After placing an override, verify it is active and behaves correctly:

• Override is loaded: Add a visible marker (e.g. <!-- override active -->) to the template, load the relevant page, and confirm the marker appears in page source. Remove before shipping.
• No PHP errors or warnings: Check wp-content/debug.log (with WP_DEBUG_LOG enabled) after loading the affected page.
• All variables are defined: In WP_DEBUG mode, WordPress will warn on undefined variables. Walk through every variable listed in the table for your template.
• Correct context rendering: For spend-more-nudge.php, test in mini-cart, cart page, and checkout, and in each slot you use. For tier-table.php, test with both bulk and tiered discounts, and with spend- and quantity-based tiered discounts, if your store uses more than one.
• Escaping is intact: Every user-visible string must pass through esc_html(), esc_attr(), or wp_kses_post() as appropriate. Do not echo raw $rule or $product data directly.
• Child/parent theme priority: If using a child theme, confirm the child copy wins over the parent by temporarily removing it and verifying the parent copy loads.
• Plugin update regression: After each Dino Discounts update, diff your copy against the plugin’s version of the template and merge any upstream changes before re-testing.