Theme Template Override Not Loading #

PetMatchPro lets Junior and Preferred users override any search, detail, or poster template by copying it into their active theme. If your copied template isn’t loading, this guide walks through the resolution chain and the most common reasons it fails.

How Template Resolution Works #

When PetMatchPro renders a template, it follows this logic:

1. License check. If your tier is too low for the selected template, an upgrade message is shown and resolution stops.
2. Directory choice. If your active theme has a PetMatchPro template directory at themes/your-theme/petmatchpro/templates/{partner}/ AND your tier is Junior or Preferred, the plugin loads templates from the theme directory. Otherwise, it loads from the bundled plugin directory.
3. File lookup. The selected template filename (with .php auto-appended if missing) is loaded from whichever directory was chosen in step 2.
4. Error. If the file isn’t found in the chosen directory, the plugin falls back to the default template for the method type or displays “template not found”.

Free (Basic) tier always loads from the plugin directory — theme overrides are a Junior+ feature.

The (theme) suffix you see on dropdown options is purely a display label so you can tell theme overrides apart from bundled plugin templates. The plugin strips the suffix before looking up the file, so the file on disk should always be the bare filename (e.g., adopt-search-default-custom.php, not adopt-search-default-custom (theme).php).

Step 1: Confirm the Correct Folder Structure #

The theme override path must match exactly:

wp-content/themes/your-active-theme/petmatchpro/templates/{partner}/your-template.php

Where {partner} is one of:

• pp — PetPoint
• af — AnimalsFirst
• rg — RescueGroups

Common mistakes:

• Folder is pet-match-pro (with hyphens) instead of petmatchpro (no hyphens)
• Folder is template (singular) instead of templates
• Folder is in the parent theme but the active theme is a child theme — the override must live in the active theme
• Filename mismatch: case-sensitive on Linux servers (e.g., Adopt-Default.php won’t match adopt-default.php)
• Missing .php extension

Step 2: Confirm License Tier #

1. Go to PetMatchPro > License Information.
2. Verify your tier is Junior or Preferred.
3. Free (Basic) users will never resolve theme paths, no matter where the file is placed.

Step 3: Confirm Template Selection #

The admin template dropdown lists both plugin templates and theme templates. Theme templates appear with a (theme) suffix.

1. Go to PetMatchPro > General Options.
2. Find the Search Template or Detail Template field for the relevant method type.
3. Select the option that ends in (theme). For example: adopt-search-default (theme).
4. Click Apply Changes.

If no (theme) options appear in the dropdown, your theme override file is not being detected at the expected path. Re-check Step 1.

Step 4: Shortcode Template Parameter #

If you’re overriding via the shortcode template parameter rather than admin settings:

[pmp-search template="adopt-search-default-custom.php (theme)"]

• The plugin tolerates either form — with or without the .php extension, with or without the (theme) suffix — so all of these resolve to the same template:
  • template="adopt-search-default-custom"
  • template="adopt-search-default-custom.php"
  • template="adopt-search-default-custom (theme)"
  • template="adopt-search-default-custom.php (theme)"
• Best practice: include the (theme) suffix in shortcodes that point at a theme override. It’s a self-documenting hint to the next person editing the page that this template lives in the theme directory, not the plugin directory. Especially valuable when your theme override has the same filename as a bundled plugin template — the suffix makes the override intent unambiguous.
• The shortcode template parameter is Junior+ only. Free users selecting a paid template see an upgrade message instead of the template loading.

Step 5: Clear Caches #

OPcache and page caches can serve stale template paths after you copy a new file into the theme. After uploading the override:

1. Hard refresh the page (Ctrl+Shift+R / Cmd+Shift+R)
2. Clear your WordPress caching plugin (if any)
3. Clear LiteSpeed cache (if your host uses it)
4. Ask your host to clear OPcache or restart PHP-FPM
5. Purge your CDN if applicable

How the Override Resolves #

Once you create a theme override directory at themes/your-theme/petmatchpro/templates/{partner}/, PetMatchPro routes all template lookups for that partner to the theme directory (Premium+ tier required). Any template you reference by name must exist in the theme directory at that point — if a template only lives in the bundled plugin folder and you’ve also created a theme override directory, the plugin won’t find it.

Practical implications:

• If you only want to override one or two templates, copy them to the theme directory and select them in admin or shortcodes; templates you don’t override won’t be available in this method’s dropdown unless they’re also copied.
• For full flexibility (mix of overrides and stock plugin templates), copy all the templates you use into the theme directory.
• If you decide you no longer need any theme overrides, delete or rename the theme override directory entirely — PetMatchPro will then fall back to the plugin’s bundled templates.

If your override file isn’t loading, double-check the directory path (Step 1) and filename spelling (case-sensitive on Linux servers). The most common failure mode is a typo in the directory name (petmatchpro with no hyphen, templates plural) or the wrong active theme.

Recommended Workflow #

1. Copy the original plugin template from wp-content/plugins/pet-match-pro/public/templates/{partner}/ to your theme at wp-content/themes/your-theme/petmatchpro/templates/{partner}/.
2. You can keep the original filename (the theme copy will silently override the plugin version) or rename with a -custom suffix (e.g., adopt-search-default-custom.php) to make the override visually distinct in the admin dropdown and your file manager. PetMatchPro picks up any .php file in this directory.
3. Make your customizations in the theme copy.
4. Select your override template in General Options (it will appear in the dropdown with a (theme) suffix), or reference it directly in a shortcode.
5. If you’re using a child theme, copy into the child theme — not the parent.

When same-name vs. renamed:

• Use the same filename as the plugin template if you want a transparent, drop-in override that takes precedence whenever that template is referenced (admin dropdown picks the theme version automatically once it exists).
• Use a renamed filename (e.g., -custom suffix) if you want both the original plugin template and your customized version available side-by-side, so you can switch between them while iterating or compare behavior.

Next Steps #

• Theme Template Overrides — Full setup guide
• Template Not Found Errors — When PetMatchPro can’t load any template
• Search Templates Gallery — All templates available for override
• Detail Templates Gallery — Detail templates available for override