Template Hierarchy

Pro feature

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

Copy template from parent to child
Keep same directory structure
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>';
    }
}