Skip to content

Page partials

Jump to bottom Edit New page
Greg Bowler edited this page May 18, 2026 · 4 revisions

Partials are reusable HTML fragments that can be inserted into page views. They are a layout tool rather than a data-binding tool.

Unlike headers and footers, partials are not automatically applied to every page in a directory. And unlike custom HTML components, they are not intended to behave like named UI elements with their own focused element boundary. They are mainly for composing page structure from reusable pieces.

Why use partials?

Partials help when repeated sections of markup would otherwise be copied between several pages. They also help keep large page views manageable, especially when several pages share a common skeleton but differ in content.

The practical benefit is that the outer page shape can live in one place while each page supplies only the content that makes it unique. That reduces duplication, makes layout changes less error-prone, and keeps individual page files shorter and easier to review.

This becomes especially useful once a section of the site needs its own layout rules. For example, a public marketing page, an authenticated account area, and an admin area may all share some common structure while still needing different wrappers. Partials let those relationships stay visible in HTML instead of being hidden inside PHP logic.

Partial file structure

Partial files live in the configured partial directory, which by default is page/_partial.

A page view can reference or extend partial content from there, allowing one file to provide the main layout while another fills in the page-specific parts. WebEngine expands those partials before the normal page binding and logic work is complete.

This means the final document shape is assembled first, and then the page logic can bind data into that assembled document.

A simple partial extension

Page HTML can extend a partial using special INI comment syntax:

<!--
extends=base-page
-->

<h2>Welcome</h2>
<p>This page body will be injected into the template.</p>

Base template:

_partial/base-page.html

<!doctype html>
<html>
<head>
	<title>My site</title>
</head>
<body>
	<header>
		<h1>My site</h1>
	</header>

	<main data-partial></main>
</body>
</html>

If we do this, the page's body content is moved into the template's data-partial element.

Recursive partials

Partials can extend other partials.

That means we can have:

  • a page extending a section layout
  • that section layout extending a global site layout

DomTemplate expands that chain from the inside out until the final page is assembled.

Template variables with [vars]

The opening comment can also contain a [vars] section.

<!--
extends=base-page

[vars]
title=Orders
heading=Order history
-->

With these vars in place within the page's leading INI comment, any reference to them in data-bind elements will be bound before any page logic executes. This allows a page view to override some default HTML content in the partial it extends, such as the <title> content, for example.

When to use partials

Partials are a good fit for:

  • shared page sections when pages are more complex than simple _header and _footer expansion can manage
  • layout fragments reused across one area of the application
  • page skeletons that several views build upon

Use _header and _footer when the framing can be global or directory-wide, where the page chrome is consistent across all pages. Use custom components when the repeated fragment behaves more like a reusable UI element. Use ordinary binding when the structure is fixed and only the values change.

Partials help shape the document before data is bound into it. That is why this page is about layout composition, not data binding.

The content within page views can be made dynamic by binding data to the DOM.

Website | Packagist | Github

Overview

Build your first app

Pages, routes, and views

Adding server-side behaviour

Working with data and services

Production applications

Running, testing, and deploying

Reference

Further reading

Clone this wiki locally