<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head><meta http-equiv="content-type" content="text/html; charset=utf-8" />
<title>[BuddyPress][14023] trunk/docs/user: Documentation: explain template hierarchy for BP Template Packs</title>
</head>
<body>
<style type="text/css"><!--
#msg dl.meta { border: 1px #006 solid; background: #369; padding: 6px; color: #fff; }
#msg dl.meta dt { float: left; width: 6em; font-weight: bold; }
#msg dt:after { content:':';}
#msg dl, #msg dt, #msg ul, #msg li, #header, #footer, #logmsg { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; }
#msg dl a { font-weight: bold}
#msg dl a:link { color:#fc3; }
#msg dl a:active { color:#ff0; }
#msg dl a:visited { color:#cc6; }
h3 { font-family: verdana,arial,helvetica,sans-serif; font-size: 10pt; font-weight: bold; }
#msg pre { white-space: pre-line; overflow: auto; background: #ffc; border: 1px #fa0 solid; padding: 6px; }
#logmsg { background: #ffc; border: 1px #fa0 solid; padding: 1em 1em 0 1em; }
#logmsg p, #logmsg pre, #logmsg blockquote { margin: 0 0 1em 0; }
#logmsg p, #logmsg li, #logmsg dt, #logmsg dd { line-height: 14pt; }
#logmsg h1, #logmsg h2, #logmsg h3, #logmsg h4, #logmsg h5, #logmsg h6 { margin: .5em 0; }
#logmsg h1:first-child, #logmsg h2:first-child, #logmsg h3:first-child, #logmsg h4:first-child, #logmsg h5:first-child, #logmsg h6:first-child { margin-top: 0; }
#logmsg ul, #logmsg ol { padding: 0; list-style-position: inside; margin: 0 0 0 1em; }
#logmsg ul { text-indent: -1em; padding-left: 1em; }#logmsg ol { text-indent: -1.5em; padding-left: 1.5em; }
#logmsg > ul, #logmsg > ol { margin: 0 0 1em 0; }
#logmsg pre { background: #eee; padding: 1em; }
#logmsg blockquote { border: 1px solid #fa0; border-left-width: 10px; padding: 1em 1em 0 1em; background: white;}
#logmsg dl { margin: 0; }
#logmsg dt { font-weight: bold; }
#logmsg dd { margin: 0; padding: 0 0 0.5em 0; }
#logmsg dd:before { content:'\00bb';}
#logmsg table { border-spacing: 0px; border-collapse: collapse; border-top: 4px solid #fa0; border-bottom: 1px solid #fa0; background: #fff; }
#logmsg table th { text-align: left; font-weight: normal; padding: 0.2em 0.5em; border-top: 1px dotted #fa0; }
#logmsg table td { text-align: right; border-top: 1px dotted #fa0; padding: 0.2em 0.5em; }
#logmsg table thead th { text-align: center; border-bottom: 1px solid #fa0; }
#logmsg table th.Corner { text-align: left; }
#logmsg hr { border: none 0; border-top: 2px dashed #fa0; height: 1px; }
#header, #footer { color: #fff; background: #636; border: 1px #300 solid; padding: 6px; }
#patch { width: 100%; }
#patch h4 {font-family: verdana,arial,helvetica,sans-serif;font-size:10pt;padding:8px;background:#369;color:#fff;margin:0;}
#patch .propset h4, #patch .binary h4 {margin:0;}
#patch pre {padding:0;line-height:1.2em;margin:0;}
#patch .diff {width:100%;background:#eee;padding: 0 0 10px 0;overflow:auto;}
#patch .propset .diff, #patch .binary .diff {padding:10px 0;}
#patch span {display:block;padding:0 10px;}
#patch .modfile, #patch .addfile, #patch .delfile, #patch .propset, #patch .binary, #patch .copfile {border:1px solid #ccc;margin:10px 0;}
#patch ins {background:#dfd;text-decoration:none;display:block;padding:0 10px;}
#patch del {background:#fdd;text-decoration:none;display:block;padding:0 10px;}
#patch .lines, .info {color:#888;background:#fff;}
--></style>
<div id="msg">
<dl class="meta" style="font-size: 105%">
<dt style="float: left; width: 6em; font-weight: bold">Revision</dt> <dd><a style="font-weight: bold" href="http://buddypress.trac.wordpress.org/changeset/14023">14023</a><script type="application/ld+json">{"@context":"http://schema.org","@type":"EmailMessage","description":"Review this Commit","action":{"@type":"ViewAction","url":"http://buddypress.trac.wordpress.org/changeset/14023","name":"Review Commit"}}</script></dd>
<dt style="float: left; width: 6em; font-weight: bold">Author</dt> <dd>imath</dd>
<dt style="float: left; width: 6em; font-weight: bold">Date</dt> <dd>2024-09-10 17:35:16 +0000 (Tue, 10 Sep 2024)</dd>
</dl>
<pre style='padding-left: 1em; margin: 2em 0; border-left: 2px solid #ccc; line-height: 1.25; font-size: 105%; font-family: sans-serif'>Documentation: explain template hierarchy for BP Template Packs
Props vapvarun
Closes https://github.com/buddypress/buddypress/pull/299</pre>
<h3>Modified Paths</h3>
<ul>
<li><a href="#trunkdocsuseradvancedREADMEmd">trunk/docs/user/advanced/README.md</a></li>
<li><a href="#trunkdocsusermanifestjson">trunk/docs/user/manifest.json</a></li>
</ul>
<h3>Added Paths</h3>
<ul>
<li><a href="#trunkdocsuseradvancedtemplatehierarchymd">trunk/docs/user/advanced/template-hierarchy.md</a></li>
</ul>
</div>
<div id="patch">
<h3>Diff</h3>
<a id="trunkdocsuseradvancedREADMEmd"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/docs/user/advanced/README.md</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/docs/user/advanced/README.md 2024-09-10 17:10:17 UTC (rev 14022)
+++ trunk/docs/user/advanced/README.md 2024-09-10 17:35:16 UTC (rev 14023)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -1,6 +1,6 @@
</span><span class="cx" style="display: block; padding: 0 10px"> # Advanced BuddyPress customizations
</span><span class="cx" style="display: block; padding: 0 10px">
</span><del style="background-color: #fdd; text-decoration:none; display:block; padding: 0 10px">-- Customizing templates
</del><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+- [Customizing templates](template-hierarchy.md)
</ins><span class="cx" style="display: block; padding: 0 10px"> - [Customizing functionalities](functionalities.md)
</span><span class="cx" style="display: block; padding: 0 10px"> - [Customizing texts](texts.md)
</span><span class="cx" style="display: block; padding: 0 10px"> - [Customizing BP Base URL](custom-base-url.md)
</span></span></pre></div>
<a id="trunkdocsuseradvancedtemplatehierarchymd"></a>
<div class="addfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Added: trunk/docs/user/advanced/template-hierarchy.md</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/docs/user/advanced/template-hierarchy.md (rev 0)
+++ trunk/docs/user/advanced/template-hierarchy.md 2024-09-10 17:35:16 UTC (rev 14023)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -0,0 +1,302 @@
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+# Customizing templates
+
+BuddyPress follows a template hierarchy system that allows you to customize the appearance of your community site. This document will guide you through the basics of BuddyPress template hierarchy, how to customize templates, and the structure of BuddyPress template files.
+
+The way you can override default BuddyPress templates with your custom templates has evolved since the first versions of the plugin when a specific and standalone BuddyPress theme was required to display your community content (until version 1.7).
+
+The current (and most common) way to achieve template overrides is based on the BP Theme Compatibility API and the BP Template Packs which made BuddyPress content integration available in all WordPress themes (even Block only ones!).
+
+## BP Template Packs template hierarchy
+
+BuddyPress comes with 2 template packs. By default, the BP Nouveau template pack is active but you can switch back to the BP Legacy one from the "Options" tab of your dashboard's `Settings > BuddyPress` area.
+
+1. `buddypress\bp-templates\bp-legacy`: This folder contains the BP Legacy templates: the ones that were created out of the BP Default standalone theme (deprecated).
+2. `buddypress\bp-templates\bp-nouveau`: this folder contains the BP Nouveau templates which brought an improved design and dynamic UIs for your community area.
+
+### Template Loading Order
+
+When BuddyPress loads a template, it follows this order:
+
+1. **Child Theme**: BuddyPress looks for templates in the child theme directory first. This allows you to customize templates without modifying the parent theme.
+2. **Parent Theme**: If the template is not found in the child theme, BuddyPress will look in the parent theme directory.
+3. **BP active template pack**: If neither the child nor the parent theme contains the template, BuddyPress will use its own templates (`bp-legacy` or `bp-nouveau`).
+
+### The BuddyPress base template file
+
+The BP Theme Compatibility API is first looking for the best based template file within the active theme, it then picks it to use its `the_content()` template tag as a placeholder to insert what are actually **template parts** from the active BP Template Pack directory.
+
+1. `active-wordpress-theme/plugin-buddypress.php`,
+2. `active-wordpress-theme/buddypress.php`,
+3. `active-wordpress-theme/community.php`,
+4. `active-wordpress-theme/generic.php`,
+5. `active-wordpress-theme/page.php` <- most commonly picked,
+6. `active-wordpress-theme/single.php`,
+7. `active-wordpress-theme/singular.php`,
+8. `active-wordpress-theme/index.php`.
+
+The `page.php` template is the one that is generally picked: that's because themes including the 4 first ones are not very common. But if you add a new template to the active theme's directory having one of the 4 first file names then it will be the one BuddyPress will pick. That's how you can customize the base template file BuddyPress should use.
+
+> [!TIP]
+> An easy way to customize the base template file is to copy the `page.php` template of your active WordPress theme, rename it `buddypress.php`, remove the unused comment template tags and fine tune your HTML markup from there!
+
+### Customizing BuddyPress Template parts
+
+To customize a BuddyPress template part:
+
+1. **Copy the Template part**: Locate the template file in the BuddyPress plugin directory (either `bp-legacy` or `bp-nouveau`) and copy it to your theme's directory. For example, copy `activity/index.php` from `bp-legacy` to your theme's `buddypress` or `community` folder (`wp-content/themes/your-theme/buddypress/activity/index.php`).
+
+2. **Modify the Template part**: Edit the copied template file in your theme directory as needed. Your changes will override the default BuddyPress template.
+
+### Common Template Files
+
+Here are some common BuddyPress template files you might want to customize:
+
+- **Members**: `buddypress/members/index.php`
+- **Activity**: `buddypress/activity/index.php`
+- **Groups**: `buddypress/groups/index.php`
+- **User Profile**: `buddypress/members/single/profile.php`
+
+### Template File Structure
+
+BuddyPress template files are organized into several directories, each corresponding to different components of the plugin:
+
+- **activity/**: Templates for activity streams
+- **blogs/**: Templates for site tracking
+- **groups/**: Templates for user groups
+- **members/**: Templates for member profiles and directories
+
+### Directory Structure for Overriding BuddyPress Legacy Templates
+
+Here is the complete directory structure for all the BuddyPress legacy template files. You can copy the necessary files based on your customization needs and override them inside the child theme at the following path.
+
+```Plain text
+your-child-theme/
+└── buddypress/
+ ├── activity/
+ │ ├── activity-loop.php
+ │ ├── comment.php
+ │ ├── entry.php
+ │ ├── index.php
+ │ ├── post-form.php
+ │ └── single/
+ │ └── home.php
+ │ └── type-parts/
+ │ ├── content-created-group.php
+ │ ├── content-friendship-created.php
+ │ ├── content-joined-group.php
+ │ ├── content-new-avatar.php
+ │ ├── content-new-member.php
+ │ ├── content-updated-profile.php
+ │ └── content.php
+ ├── assets/
+ │ ├── _attachments/
+ │ │ ├── avatars/
+ │ │ │ ├── camera.php
+ │ │ │ ├── crop.php
+ │ │ │ ├── index.php
+ │ │ │ └── recycle.php
+ │ │ ├── cover-images/
+ │ │ │ └── index.php
+ │ │ └── uploader.php
+ │ ├── emails/
+ │ │ └── single-bp-email.php
+ │ ├── embeds/
+ │ │ ├── activity.php
+ │ │ ├── footer.php
+ │ │ ├── header-activity.php
+ │ │ └── header.php
+ │ ├── utils/
+ │ │ └── restricted-access-message.php
+ │ └── widgets/
+ │ ├── dynamic-groups.php
+ │ ├── dynamic-members.php
+ │ └── friends.php
+ ├── blogs/
+ │ ├── blogs-loop.php
+ │ ├── confirm.php
+ │ ├── create.php
+ │ └── index.php
+ ├── common/
+ │ └── search/
+ │ └── dir-search-form.php
+ ├── groups/
+ │ ├── create.php
+ │ ├── groups-loop.php
+ │ └── index.php
+ │ └── single/
+ │ ├── activity.php
+ │ ├── admin.php
+ │ ├── admin/
+ │ │ ├── delete-group.php
+ │ │ ├── edit-details.php
+ │ │ ├── group-avatar.php
+ │ │ ├── group-cover-image.php
+ │ │ ├── group-settings.php
+ │ │ ├── manage-members.php
+ │ │ └── membership-requests.php
+ │ ├── cover-image-header.php
+ │ ├── group-header.php
+ │ ├── home.php
+ │ ├── invites-loop.php
+ │ ├── members.php
+ │ ├── plugins.php
+ │ ├── request-membership.php
+ │ ├── requests-loop.php
+ │ └── send-invites.php
+ ├── members/
+ │ ├── activate.php
+ │ ├── index.php
+ │ ├── members-loop.php
+ │ ├── register.php
+ │ └── single/
+ │ ├── activity.php
+ │ ├── blogs.php
+ │ ├── cover-image-header.php
+ │ ├── friends.php
+ │ ├── friends/
+ │ │ └── requests.php
+ │ ├── groups.php
+ │ ├── groups/
+ │ │ └── invites.php
+ │ ├── home.php
+ │ ├── invitations.php
+ │ ├── invitations/
+ │ │ ├── invitations-loop.php
+ │ │ ├── list-invites.php
+ │ │ └── send-invites.php
+ │ ├── member-header.php
+ │ ├── messages.php
+ │ ├── messages/
+ │ │ ├── compose.php
+ │ │ ├── message.php
+ │ │ ├── messages-loop.php
+ │ │ ├── notices-loop.php
+ │ │ └── single.php
+ │ ├── notifications.php
+ │ ├── notifications/
+ │ │ ├── feedback-no-notifications.php
+ │ │ ├── notifications-loop.php
+ │ │ ├── read.php
+ │ │ └── unread.php
+ │ ├── plugins.php
+ │ ├── profile.php
+ │ ├── profile/
+ │ │ ├── change-avatar.php
+ │ │ ├── change-cover-image.php
+ │ │ ├── edit.php
+ │ │ ├── profile-loop.php
+ │ │ └── profile-wp.php
+ │ └── settings.php
+ │ ├── settings/
+ │ │ ├── capabilities.php
+ │ │ ├── data.php
+ │ │ ├── delete-account.php
+ │ │ ├── general.php
+ │ │ ├── notifications.php
+ │ │ └── profile.php
+```
+
+### Directory Structure for Overriding BuddyPress Nouveau Templates
+
+Here is the complete directory structure for all the BuddyPress Nouveau template files. Based on your customization needs, you can copy the necessary files.
+
+```Plain Text
+your-child-theme/
+├── buddypress/
+│ ├── activity/
+│ │ ├── activity-loop.php
+│ │ └── comment-form.php
+│ ├── assets/
+│ │ ├── emails/
+│ │ │ └── single-bp-email.php
+│ │ ├── embeds/
+│ │ │ ├── activity.php
+│ │ │ └── header.php
+│ │ └── widgets/
+│ │ ├── dynamic-groups.php
+│ │ └── dynamic-members.php
+│ ├── blogs/
+│ │ ├── blogs-loop.php
+│ │ └── create.php
+│ ├── common/
+│ │ ├── filters/
+│ │ │ ├── directory-filters.php
+│ │ │ └── groups-screens-filters.php
+│ │ ├── js-templates/
+│ │ │ ├── activity/
+│ │ │ │ └── form.php
+│ │ │ ├── messages/
+│ │ │ └── search-form.php
+│ │ ├── nav/
+│ │ │ └── directory-nav.php
+│ │ ├── notices/
+│ │ │ └── template-notices.php
+│ │ └── search/
+│ │ └── search-form.php
+│ ├── groups/
+│ │ ├── create.php
+│ │ ├── groups-loop.php
+│ │ └── single/
+│ │ ├── activity.php
+│ │ ├── admin/
+│ │ ├── delete-group.php
+│ │ ├── edit-details.php
+│ │ ├── group-avatar.php
+│ │ ├── group-cover-image.php
+│ │ ├── group-settings.php
+│ │ ├── manage-members.php
+│ │ └── membership-requests.php
+│ │ ├── cover-image-header.php
+│ │ ├── default-front.php
+│ │ ├── group-header.php
+│ │ └── home.php
+│ ├── members/
+│ │ ├── activate.php
+│ │ ├── members-loop.php
+│ │ └── single/
+│ │ ├── activity.php
+│ │ ├── blogs.php
+│ │ ├── cover-image-header.php
+│ │ ├── default-front.php
+│ │ ├── friends/
+│ │ ├── requests-loop.php
+│ │ └── requests.php
+│ │ ├── groups/
+│ │ └── invites.php
+│ │ ├── home.php
+│ │ ├── invitations/
+│ │ ├── invitations-loop.php
+│ │ ├── list-invites.php
+│ │ └── send-invites.php
+│ │ ├── member-header.php
+│ │ ├── messages.php
+│ │ ├── notifications/
+│ │ └── notifications-loop.php
+│ │ ├── parts/
+│ │ ├── item-nav.php
+│ │ ├── item-subnav.php
+│ │ └── profile-visibility.php
+│ │ ├── plugins.php
+│ │ ├── profile/
+│ │ ├── change-avatar.php
+│ │ ├── change-cover-image.php
+│ │ ├── edit.php
+│ │ ├── profile-loop.php
+│ │ └── profile-wp.php
+│ │ ├── settings/
+│ │ ├── capabilities.php
+│ │ ├── data.php
+│ │ ├── delete-account.php
+│ │ ├── general.php
+│ │ ├── group-invites.php
+│ │ ├── notifications.php
+│ │ └── profile.php
+```
+
+## Standalone BuddyPress theme template hierarchy
+
+TBD.
+
+## BuddyPress Block only theme template hierarchy
+
+TBD.
</ins></span></pre></div>
<a id="trunkdocsusermanifestjson"></a>
<div class="modfile"><h4 style="background-color: #eee; color: inherit; margin: 1em 0; padding: 1.3em; font-size: 115%">Modified: trunk/docs/user/manifest.json</h4>
<pre class="diff"><span>
<span class="info" style="display: block; padding: 0 10px; color: #888">--- trunk/docs/user/manifest.json 2024-09-10 17:10:17 UTC (rev 14022)
+++ trunk/docs/user/manifest.json 2024-09-10 17:35:16 UTC (rev 14023)
</span><span class="lines" style="display: block; padding: 0 10px; color: #888">@@ -174,6 +174,12 @@
</span><span class="cx" style="display: block; padding: 0 10px"> "parent": null
</span><span class="cx" style="display: block; padding: 0 10px"> },
</span><span class="cx" style="display: block; padding: 0 10px"> {
</span><ins style="background-color: #dfd; text-decoration:none; display:block; padding: 0 10px">+ "title": "Customizing templates",
+ "slug": "advanced-templacte-hierarchy",
+ "markdown_source": "../user/advanced/template-hierarchy.md",
+ "parent": null
+ },
+ {
</ins><span class="cx" style="display: block; padding: 0 10px"> "title": "BuddyPress Components",
</span><span class="cx" style="display: block; padding: 0 10px"> "slug": "components",
</span><span class="cx" style="display: block; padding: 0 10px"> "markdown_source": "../user/components/README.md",
</span></span></pre>
</div>
</div>
</body>
</html>