Template Hierarchy

Understanding BuddyX Pro’s template structure and WordPress template hierarchy for effective customization.

WordPress Template Hierarchy

BuddyX Pro follows the WordPress standard template hierarchy with custom enhancements for BuddyPress, WooCommerce, LearnDash, and FluentCart.

Template files the theme actually ships

These are the top-level template files present in buddyx-pro/ (5.1.4). The theme does not ship front-page.php, home.php, single-post.php, singular.php, or search.php - those views fall through to index.php (or archive.php) per the WordPress hierarchy.

404.php                         offline.php
500.php                         page.php
archive.php                     searchform.php
archive-fluent-products.php     sidebar.php
archive-sfwd-courses.php        sidebar-buddypress.php
bbpress.php                     single.php
buddypress.php                  single-fluent-products.php
comment.php                     single-sfwd-courses.php
comments.php                    single-sfwd-groups.php
footer.php                      taxonomy-product-brands.php
header.php                      taxonomy-product-categories.php
index.php

Basic Hierarchy Flow

WordPress checks templates in this order:
1. Child theme templates
2. Parent theme templates
3. WordPress default templates

Core Templates

Homepage Templates

Priority Order:

1. front-page.php          # Static front page or blog
2. home.php                # Blog homepage
3. page.php                # If front page is a page
4. index.php               # Ultimate fallback

Example: Custom homepage

front-page.php

<?php get_header(); ?>

<div class="homepage-wrapper">
    <?php
    while ( have_posts() ) {
        the_post();
        get_template_part( 'template-parts/content', 'front-page' );
    }
    ?>
</div>

<?php get_footer(); ?>

Single Post Templates

Priority Order:

1. single-{post-type}-{slug}.php    # Single post by slug
2. single-{post-type}.php           # Single post by type
3. single.php                       # Single post
4. singular.php                     # Any single content
5. index.php                        # Fallback

Examples shipped by the theme:

• single-sfwd-courses.php - LearnDash course
• single-sfwd-groups.php - LearnDash group
• single-fluent-products.php - FluentCart product
• single.php - Any single post (blog posts included; there is no single-post.php)

Page Templates

Priority Order:

1. custom-template.php              # Template Name: Custom
2. page-{slug}.php                  # Page by slug
3. page-{id}.php                    # Page by ID
4. page.php                         # Default page
5. singular.php                     # Any singular
6. index.php                        # Fallback

Custom Page Template:

<?php
/**
 * Template Name: Full Width Page
 * Template Post Type: page
 *
 * @package buddyxpro
 */

get_header();
?>

<div class="full-width-content">
    <?php
    while ( have_posts() ) {
        the_post();
        the_content();
    }
    ?>
</div>

<?php get_footer(); ?>

Archive Templates

Priority Order:

1. archive-{post-type}.php          # Custom post type archive
2. archive.php                      # Generic archive
3. index.php                        # Fallback

Examples:

• archive-fluent-products.php - FluentCart shop
• archive-sfwd-courses.php - LearnDash courses
• archive.php - Blog archives

Taxonomy Templates

Priority Order:

1. taxonomy-{taxonomy}-{term}.php   # Specific term
2. taxonomy-{taxonomy}.php          # Taxonomy archive
3. taxonomy.php                     # Any taxonomy
4. archive.php                      # Archive fallback
5. index.php                        # Final fallback

Examples shipped by the theme:

• taxonomy-product-categories.php - FluentCart product categories
• taxonomy-product-brands.php - FluentCart product brands

Plugin-Specific Templates

BuddyPress Templates

Template: buddypress.php

Used for all BuddyPress pages (members, groups, activity).

<?php
/**
 * BuddyPress Page Template
 *
 * @package buddyxpro
 */

get_header();

$buddypress_sidebar = get_theme_mod( 'buddypress_sidebar_option', 'right' );
?>

<?php do_action( 'buddyx_sub_header' ); ?>

<?php do_action( 'buddyx_before_content' ); ?>

<div id="primary" class="content-area">
    <main id="main" class="site-main">
        <?php
        // BuddyPress content
        if ( function_exists( 'bp_nouveau_wrapper_open' ) ) {
            bp_nouveau_wrapper_open();
        }
        ?>
    </main>
</div>

<?php
if ( 'left' === $buddypress_sidebar || 'right' === $buddypress_sidebar ) {
    get_sidebar();
}
?>

<?php do_action( 'buddyx_after_content' ); ?>

<?php get_footer(); ?>

bbPress Templates

Template: bbpress.php

Used for forums, topics, and replies.

<?php
/**
 * bbPress Page Template
 *
 * @package buddyxpro
 */

get_header();

$bbpress_sidebar = get_theme_mod( 'bbpress_sidebar_option', 'right' );
?>

<?php do_action( 'buddyx_sub_header' ); ?>

<?php do_action( 'buddyx_before_content' ); ?>

<div id="primary" class="content-area">
    <main id="main" class="site-main">
        <?php
        while ( have_posts() ) {
            the_post();
            the_content();
        }
        ?>
    </main>
</div>

<?php
if ( 'left' === $bbpress_sidebar || 'right' === $bbpress_sidebar ) {
    get_sidebar();
}
?>

<?php do_action( 'buddyx_after_content' ); ?>

<?php get_footer(); ?>

WooCommerce Templates

Override Path: buddyx-pro/woocommerce/

The theme ships a small set of WooCommerce template overrides (only the files it needs to restyle - everything else falls back to WooCommerce core):

buddyx-pro/woocommerce/
├── archive-product.php            # Shop / product archive
├── single-product.php             # Product page
├── cart/
│   └── cart.php                   # Cart table
├── single-product/
│   └── rating.php                 # Product rating markup
└── global/
    └── quantity-input.php         # Quantity input

LearnDash Templates

The theme ships two LearnDash single templates plus a course archive. Lesson, topic, and quiz views are handled by LearnDash’s own templates (the theme does not override them):

archive-sfwd-courses.php   # Course archive
single-sfwd-courses.php    # Course single
single-sfwd-groups.php     # Group single

Example: single-sfwd-groups.php

<?php
get_header();
?>

<?php do_action( 'buddyx_sub_header' ); ?>

<?php do_action( 'buddyx_before_content' ); ?>

<div id="primary" class="content-area">
    <main id="main" class="site-main">
        <?php
        while ( have_posts() ) {
            the_post();
            // LearnDash group content
            learndash_group_content();
        }
        ?>
    </main>
</div>

<?php do_action( 'buddyx_after_content' ); ?>

<?php get_footer(); ?>

FluentCart Templates

Templates:

• archive-fluent-products.php - Shop page
• taxonomy-product-categories.php - Category archive
• taxonomy-product-brands.php - Brand archive

Example: archive-fluent-products.php

<?php
get_header();
?>

<?php do_action( 'buddyx_sub_header' ); ?>

<?php do_action( 'buddyx_before_content' ); ?>

<div id="primary" class="content-area">
    <main id="main" class="site-main">
        <?php
        // FluentCart renders its own content
        do_action( 'fluent_cart/template/main_content' );
        ?>
    </main>
</div>

<?php do_action( 'buddyx_after_content' ); ?>

<?php get_footer(); ?>

Template Parts

Template parts are reusable components loaded with get_template_part().

Directory Structure

This mirrors the real template-parts/ tree in 5.1.4 (abridged):

template-parts/
├── buddyx-page-header.php          # Page header wrapper
├── content-bbpress.php             # bbPress content
├── content-buddypress.php          # BuddyPress content
├── content-user-preview.php        # Member preview card
├── form.php                        # Generic form wrapper
├── form-login.php                  # Login form
├── form-register.php               # Registration form
├── form-vcard.php                  # vCard form
├── content/                        # Entry building blocks
│   ├── entry.php                   # Entry dispatcher
│   ├── entry-post.php              # Post entry
│   ├── entry-page.php              # Page entry
│   ├── entry-full-width.php        # Full-width entry
│   ├── entry-attachment.php        # Attachment entry
│   ├── entry-share.php             # Share row
│   ├── entry_header.php            # Entry header
│   ├── entry_title.php             # Entry title
│   ├── entry_content.php           # Entry content
│   ├── entry_summary.php           # Entry summary / excerpt
│   ├── entry_meta.php              # Entry meta
│   ├── entry_media.php             # Entry media
│   ├── entry_thumbnail.php         # Entry thumbnail
│   ├── entry_footer.php            # Entry footer
│   ├── entry_actions.php           # Entry actions
│   ├── entry_categories.php        # Category list
│   ├── entry_tags.php              # Tag list
│   ├── entry_taxonomies.php        # Custom taxonomies
│   ├── page_header.php             # Page-header body
│   ├── pagination.php              # Pagination
│   ├── related-posts.php           # Related posts
│   ├── error.php / error-404.php   # Error states
│   ├── error-500.php / error-offline.php
│   └── entry_header-sfwd-courses.php   # LearnDash course header
├── header/
│   ├── branding.php                # Logo / site title
│   ├── navigation.php              # Primary + mobile nav
│   ├── custom_header.php           # Custom header image
│   ├── buddypress-profile.php      # BP profile menu
│   └── buddyx-panel.php            # Side panel
├── layout/                         # Blog layout variants
│   ├── entry-default-layout.php
│   ├── entry-grid-layout.php
│   ├── entry-list-layout.php
│   ├── entry-masonry-layout.php
│   ├── entry-magazine-layout.php
│   ├── entry-editorial-layout.php
│   └── entry-minimal-layout.php
├── post-format/                    # Post-format media
│   ├── entry-audio.php  entry-gallery.php  entry-image.php
│   └── entry-link.php   entry-quote.php    entry-video.php
└── footer/
    └── info.php                    # Footer info / copyright

There is no template-parts/content.php, content-none.php, content-page.php, header/mobile.php, or footer/footer-widgets.php. Page content is rendered by template-parts/content/entry-page.php (dispatched through entry.php); the mobile menu lives in header/navigation.php; footer widgets render from footer.php directly.

Using Template Parts

// Load an entry part (dispatcher).
get_template_part( 'template-parts/content/entry', get_post_type() );

// Load a specific header part.
get_template_part( 'template-parts/header/branding' );

// Pass variables
set_query_var( 'custom_var', 'value' );
get_template_part( 'template-parts/content/entry' );
// Access in the part: get_query_var( 'custom_var' )

Creating Custom Template Part

template-parts/content-custom.php

<?php
/**
 * Template part for displaying custom post content
 *
 * @package buddyxpro
 */
?>

<article id="post-<?php the_ID(); ?>" <?php post_class( 'custom-post' ); ?>>
    <header class="entry-header">
        <?php the_title( '<h1 class="entry-title">', '</h1>' ); ?>
    </header>

    <div class="entry-content">
        <?php the_content(); ?>
    </div>

    <footer class="entry-footer">
        <?php
        // Custom meta
        echo '<span class="custom-meta">';
        echo esc_html( get_post_meta( get_the_ID(), 'custom_field', true ) );
        echo '</span>';
        ?>
    </footer>
</article>

Partial Templates

Header

File: header.php

Structure:

<!DOCTYPE html>
<html <?php language_attributes(); ?>>
<head>
    <meta charset="<?php bloginfo( 'charset' ); ?>">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <?php wp_head(); ?>
</head>

<body <?php body_class(); ?>>
<?php wp_body_open(); ?>
<?php do_action( 'buddyx_body_top' ); ?>

<div id="page" class="site">
    <?php do_action( 'buddyx_page_top' ); ?>

    <?php do_action( 'buddyx_header_before' ); ?>
    <header id="masthead" class="site-header">
        <?php do_action( 'buddyx_header_wrapper_before' ); ?>
        <!-- Branding + navigation template parts, header actions -->
        <?php do_action( 'buddyx_header_wrapper_after' ); ?>
    </header>
    <?php do_action( 'buddyx_header_after' ); ?>

There is no buddyx_header hook. The real header hooks are buddyx_header_before, buddyx_header_wrapper_before, buddyx_header_wrapper_after, buddyx_header_after, and buddyx_header_actions (inside the menu-icons area). See Hooks & Filters.

Footer

File: footer.php

Structure:

    <?php do_action( 'buddyx_footer_before' ); ?>

    <footer id="colophon" class="site-footer">
        <!-- Footer content -->
    </footer>

    <?php do_action( 'buddyx_footer_after' ); ?>
</div><!-- #page -->

<?php do_action( 'buddyx_page_bottom' ); ?>
<?php wp_footer(); ?>
<?php do_action( 'buddyx_body_bottom' ); ?>

</body>
</html>

Sidebar

File: sidebar.php

Structure:

<?php
if ( ! is_active_sidebar( 'sidebar-1' ) ) {
    return;
}
?>

<?php do_action( 'buddyx_sidebar_before' ); ?>

<aside id="secondary" class="widget-area">
    <?php dynamic_sidebar( 'sidebar-1' ); ?>
</aside>

<?php do_action( 'buddyx_sidebar_after' ); ?>

AMP Templates

Location: amp/

BuddyX Pro includes AMP-specific templates:

amp/
├── single.php                 # AMP single post
├── archive.php                # AMP archive
└── search.php                 # AMP search results

AMP Template Detection:

functions.php

add_filter( 'template_include', 'buddyx_theme_amp_templatre_include', '9999992233720368547758099' );
function buddyx_theme_amp_templatre_include( $template_file ) {
    if ( function_exists( 'amp_is_request' ) && amp_is_request() ) {
        if ( is_single() ) {
            $template_file = get_template_directory() . '/amp/single.php';
        }
        if ( is_archive() ) {
            $template_file = get_template_directory() . '/amp/archive.php';
        }
    }
    return $template_file;
}

Custom Template Files

Search Results

The theme does not ship a search.php. Search results are rendered by index.php (the WordPress fallback), which loops through template-parts/content/entry for each result. searchform.php provides the search form markup, and amp/search.php handles AMP search. To customise search output, either add a search.php in your child theme or filter the entry parts.

404 Template

File: 404.php

<?php
get_header();
?>

<div class="error-404 not-found">
    <header class="page-header">
        <h1 class="page-title"><?php esc_html_e( 'Oops! Page not found', 'buddyxpro' ); ?></h1>
    </header>

    <div class="page-content">
        <p><?php esc_html_e( 'The page you are looking for might have been removed.', 'buddyxpro' ); ?></p>
        <?php get_search_form(); ?>
    </div>
</div>

<?php get_footer(); ?>

Override Templates in Child Theme

Method 1: Direct Copy

1. Copy template from parent to child
2. Keep same directory structure
3. Modify as needed

# Example: Override header
cp buddyx-pro/header.php buddyx-pro-child/header.php

Method 2: Custom Template Location

// Child theme functions.php
add_filter( 'template_include', 'child_custom_template', 99 );
function child_custom_template( $template ) {
    if ( is_page( 'custom' ) ) {
        $custom_template = get_stylesheet_directory() . '/templates/custom-page.php';
        if ( file_exists( $custom_template ) ) {
            return $custom_template;
        }
    }
    return $template;
}

Method 3: Plugin Integration Override

// Override FluentCart category template
add_filter( 'template_include', 'child_fluentcart_templates', 100 );
function child_fluentcart_templates( $template ) {
    if ( is_tax( 'product-categories' ) ) {
        $custom = get_stylesheet_directory() . '/fluentcart/taxonomy-categories.php';
        if ( file_exists( $custom ) ) {
            return $custom;
        }
    }
    return $template;
}

Template Debugging

Show Current Template

// Add to child theme functions.php
add_action( 'wp_footer', 'show_template_info' );
function show_template_info() {
    if ( current_user_can( 'administrator' ) && WP_DEBUG ) {
        global $template;
        echo '<div style="position:fixed;bottom:0;left:0;background:#000;color:#fff;padding:10px;z-index:9999;">';
        echo '<strong>Template:</strong> ' . basename( $template );
        echo '</div>';
    }
}

Template Hierarchy Debug

// Show template loading order
add_filter( 'template_include', 'debug_template_hierarchy', 9999 );
function debug_template_hierarchy( $template ) {
    if ( WP_DEBUG ) {
        error_log( 'Template loaded: ' . $template );
    }
    return $template;
}

Best Practices

Do

• Follow WordPress template hierarchy
• Use child theme for overrides
• Keep consistent file structure
• Document custom templates
• Use template parts for reusable components
• Test template changes thoroughly
• Escape all output
• Use proper WordPress functions

Don’t

• Modify parent theme templates directly
• Hardcode URLs or paths
• Skip header/footer includes
• Duplicate template code
• Forget wp_head() and wp_footer()
• Mix business logic with presentation
• Use PHP short tags

Template Checklist

Before creating a custom template:

• Check if template part can be reused
• Follow WordPress naming conventions
• Include proper DocBlock
• Call get_header() and get_footer()
• Add theme action hooks
• Escape all output
• Test responsive design
• Validate HTML
• Test with WP_DEBUG enabled
• Document custom functionality

Related Documentation

• Theme Architecture
• Hooks & Filters Reference
• Creating a Child Theme
• Customization Guide