---
tags:
  - wordpress
  - fse
  - database
  - architecture
  - templates
title: Under the Hood: wp_template vs. wp_template_part
---

# Under the Hood: `wp_template` vs. `wp_template_part`

When you edit a template in the Site Editor, WordPress doesn't edit your HTML files. Instead, it saves a copy of the block markup into the database. To manage this, WordPress introduced two new internal Post Types.

Understanding these post types is crucial for debugging why a template isn't updating or why "Clear Customizations" is appearing.

## 1. The Two Post Types

Both live in the `wp_posts` table, just like standard Pages or Posts.

### `wp_template`
*   **Corresponds to:** Files in the `templates/` directory (e.g., `index.html`, `single.html`, `404.html`).
*   **Purpose:** Represents a full-page layout.
*   **Slug Structure:** usually `theme-slug//template-name` (e.g., `twentytwentyfour//single`).

### `wp_template_part`
*   **Corresponds to:** Files in the `parts/` directory (e.g., `header.html`, `footer.html`).
*   **Purpose:** Represents a reusable section included inside a template.
*   **Slug Structure:** `theme-slug//part-name` (e.g., `twentytwentyfour//header`).

## 2. The Resolution Hierarchy (Shadowing)

WordPress uses a specific logic to decide what to show the user. It checks the database first, then the filesystem.

1.  **Database Check:** Does a `wp_template` post exist with the slug `my-theme//single` and `post_status = 'publish'`?
    *   **Yes:** Render the content from `post_content` in the database. (Ignore the file).
    *   **No:** Look for `templates/single.html` in the active theme folder.

**Key Takeaway:** The moment you click "Save" in the Site Editor, you create a database entry that "shadows" (hides) your physical HTML file.

## 3. Inspecting the Database

If you are comfortable with SQL or tools like PHPMyAdmin, you can see exactly what customizations are active.

**Query to see all customized templates:**
```sql
SELECT ID, post_name, post_status 
FROM wp_posts 
WHERE post_type = 'wp_template';
```

**Query to see all customized parts:**
```sql
SELECT ID, post_name, post_status 
FROM wp_posts 
WHERE post_type = 'wp_template_part';
```

## 4. "Clearing" Customizations

When you click "Clear Customizations" in the Site Editor, WordPress effectively runs:

```sql
DELETE FROM wp_posts WHERE ID = [The ID of the shadow template];
```

Once the row is deleted, the hierarchy logic (Step 2 above) fails the Database Check and falls back to reading your `.html` file again.

## 5. Why the Slug Includes the Theme Name?

You might notice slugs like `twentytwentyfour//index`.

WordPress namespaces templates to the active theme. This allows you to switch themes without losing your customizations.

*   If you customize the Header in **Theme A**, it saves as `theme-a//header`.
*   If you switch to **Theme B**, WordPress looks for `theme-b//header`.
*   It does *not* load the customizations from Theme A, preventing layout breakage.