Streamlining Layouts in ProcessWire with Template Inheritance

The Problem: Repeating Layout Code

In many ProcessWire sites you’ll find the same header, navigation, footer, and CSS classes duplicated across dozens of templates. When a change is needed—say you want to swap a logo—the effort grows linearly with the number of templates. Template inheritance lets you write the shared markup once and reuse it, so updates propagate automatically.

Template Inheritance Basics

ProcessWire’s inheritance works by placing an extends statement at the top of a template file. The child template inherits all fields, modules, and PHP code from the parent. Placeholders defined in the parent allow the child to inject content without duplicating markup.

Building a Base Template

// File: templates/base.php
// This file lives in the templates folder and is used as a parent.

// Define a placeholder for the main content area.
{content}

// Common header and footer.
<header>My Site Header</header>
<footer>© 2026 My Site</footer>

Notice the {content} placeholder. It’s a custom tag that the child template will replace with its own markup.

Extending with Child Templates

// File: templates/blog.php
extends('base') // Inherit all from base.php

// Override the placeholder with blog‑specific markup.
{content}
  <article>
    <h1>{$page.title}</h1>
    <p>{$page.body}</p>
  </article>
{/content}

When a page uses the blog template, ProcessWire renders base.php first, then injects the block inside {content} from blog.php. The result is a single header/footer with page‑specific article markup.

Testing the Inheritance

1. Create the two files in your ProcessWire installation’s templates folder.
2. In the admin UI, create a new page, assign it the blog template, and add a title and body field.
3. Publish the page and view it in a browser.
4. View the page source: you should see the header, footer, and the article markup from blog.php.
5. Modify templates/base.php—for example, change <header>My Site Header</header> to <header>New Header</header>. Re‑publish the page and confirm the change appears without editing blog.php.

To verify performance, enable the debug module, then load the page and examine the “Render time” in the debug bar. Adding a few inheritance layers typically adds milliseconds, but deep chains (more than three levels) can become noticeable on larger sites.

Trade‑offs & Best Practices

• Readability: Deep inheritance can obscure where a piece of markup originates. Keep chains to two or three levels and use comments to document the hierarchy.
• Debugging: A change in a parent placeholder name breaks all children. Use consistent, descriptive placeholder names and avoid renaming without updating all children.
• Coupling: If a page needs a unique layout, inheritance may be overkill. Consider partials or modules for truly page‑specific sections.
• Field Groups: Inheritance does not auto‑propagate field definitions. Add fields to the parent template’s fieldgroup so children inherit them automatically.
• Performance: Keep template logic light. Heavy processing should live in modules or page handlers, not in the template itself.

Next Steps

Once you’re comfortable with a two‑level hierarchy, experiment with a third level: for example, a templates/blog/post.php that extends templates/blog.php and adds a comments section. Remember to profile rendering time after each addition.

Finally, document your template structure in a shared wiki or README so new developers understand the inheritance chain and avoid accidental coupling.