WordPress’ built-in template hierarchy makes it easy to reuse template files on typical sites: use category.php for category archives and archive.php for all archive types (category, tag, search, etc.).
However, when a site has a more complex content structure you often need a custom template hierarchy to avoid duplicating code. For projects with multiple custom post types and several taxonomies each, creating a clear mapping from taxonomies and archives to a single template file saves time and keeps templates DRY.
For example, on a site I’m building the “recipe” post type uses two taxonomies: “name-range” (to group recipes by alphabetical ranges like A–D or E–G) and “base” (a shared taxonomy that indicates the alcoholic base for cocktails). I want one template file to serve several related contexts:
- Recipe post type archive
- Name-range taxonomy archive
- Base taxonomy archive, but only when the queried post type is recipe
To accomplish this, use the template_include filter. This filter runs after WordPress determines the default template to use but before it loads that template, so it’s the right place to substitute a custom template based on more specific logic.
The simple approach below checks whether the current request is the recipe post type archive, the name-range taxonomy archive, or the base taxonomy archive where the queried post type is recipe. If so, it forces WordPress to load archive-recipe.php instead of the template it would normally select.
| function be_template_chooser( $template ) { |
| if ( is_post_type_archive( ‘recipe’ ) || is_tax( ‘name-range’ ) || ( is_tax( ‘base’ ) && ‘recipe’ == get_post_type() ) ) |
| $template = get_query_template( ‘archive-recipe’ ); |
| return $template; |
| } |
| add_filter( ‘template_include’, ‘be_template_chooser’ ); |
That code effectively says: if the current request is the recipe archive, the name-range taxonomy, or the base taxonomy for recipes, use archive-recipe.php.
To make the logic reusable and to help with styling, it’s helpful to centralize the section detection into a helper function that returns the current section name (for example, “recipe”, “lifestyle”, “brand”, or “experience”) or false when no match exists. With that, you can both choose the appropriate archive template and add a matching body class like section-recipe.
| function be_return_archive_section() { |
| if ( is_post_type_archive( ‘lifestyle’ ) || is_tax( ‘lifestyle-section’ ) || is_tax( ‘lifestyle-type’ ) || is_tax( ‘lifestyle-series’ ) ) |
| return ‘lifestyle’; |
| if ( is_post_type_archive( ‘recipe’ ) || is_tax( ‘name-range’ ) || ( is_tax( ‘base’ ) && ‘recipe’ == get_post_type() ) ) |
| return ‘recipe’; |
| if ( is_post_type_archive( ‘brand’ ) || ( is_tax( ‘base’ ) && ‘brand’ == get_post_type() ) ) |
| return ‘brand’; |
| if ( is_post_type_archive( ‘experience’ ) ) |
| return ‘experience’; |
| return false; |
| } |
| function be_template_chooser( $template ) { |
| if ( be_return_archive_section() ) |
| $template = get_query_template( ‘archive-‘ . be_return_archive_section() ); |
| return $template; |
| } |
| add_filter( ‘template_include’, ‘be_template_chooser’ ); |
| add_filter( ‘body_class’, ‘be_section_body_classes’ ); |
| function be_section_body_classes( $classes ) { |
| if ( be_return_archive_section() ) |
| $classes[] = ‘section-‘ . be_return_archive_section(); |
| return $classes; |
| } |
Summary of the workflow:
- be_return_archive_section() inspects the current query and returns a section slug (like “recipe”) if it matches any configured post type archive or related taxonomy, otherwise it returns false.
- be_template_chooser() uses that section slug to load archive-{section}.php when appropriate, ensuring taxonomy archives that should share a CPT template use the same file.
- be_section_body_classes() adds a body class such as section-recipe so you can style section-specific pages consistently.
When you add a new taxonomy or want a taxonomy to share a CPT archive template, update be_return_archive_section() to include the new mapping. Once mapped, the proper archive template will be used automatically and the matching body class will be applied.