Includes

<pagelove:include> is a declarative HTML element that allows a Pagelove document to include a fragment of another document (or of the site as a whole) using standard CSS selectors.

Unlike traditional template partials, included fragments remain addressable, authorisable, and writable through Pagelove’s HTTP and selector‑based model.

Element form

<pagelove:include
  selector="..."
  resource="..." />

Attributes:

• selector (required)
• resource (optional constraint)

Attribute semantics

selector (required)

A CSS selector identifying the fragment to include.

The selector is evaluated against a set of candidate resources determined by the resource attribute (if present) or the entire site graph (if not).

resource (optional)

Constrains the search space for the selector.

When present, only resources whose path matches the value(s) of resource are searched. Glob-style (*, ** & ?)wildcards are supported

When omitted, the selector is evaluated across the entire site graph.

resource does not mean “include the whole resource”. A selector is always required.

This is invalid:

<pagelove:include resource="/partials.html" />

This is valid:

<pagelove:include resource="/partials.html" selector="header#nav" />

Resolution model

Given:

<pagelove:include selector="S" resource="R?" />

The server resolves the include as follows:

1. Determine the candidate resource set:
   • If resource is present: all resources matching resource.
   • Otherwise: the entire site graph.
2. Evaluate selector within each candidate resource.
3. Collect all matching elements across all candidates.
4. Apply cardinality rules (below).
5. If resolution succeeds, materialise the matched element in place of the <pagelove:include> node, preserving provenance metadata (origin resource and origin node identity).

Cardinality rules

<pagelove:include> is defined to resolve to exactly one element.

The following rules are enforced:

• 0 matches → request fails with:

404 Not Found

• >1 matches → request fails with:

500 Internal Server Error

Multiple matches are treated as a site integrity failure, not a client input error. An include is expected to identify a single canonical fragment. Ambiguity indicates incorrect site composition.

Examples

Global selector include

Searches the entire site graph.

<pagelove:include selector="#partials header#nav" />

Constrained include

Searches only within /partials.html.

<pagelove:include
  resource="/partials.html"
  selector="header#nav" />

Interaction with HTTP Document Mutation (PUT, POST & DELETE)

Included fragments retain their origin identity.

When a client performs a mutating HTTP request (such as PUT) targeting an element that originated from an included fragment:

• The modification is applied to the origin resource, not the including document.
• Authorization rules and shape constraints are evaluated in the context of the origin resource.
• Concurrency control (ETags) is performed against the origin resource.

If an include fails to resolve uniquely, no write is attempted.

Summary

<pagelove:include> provides deterministic, selector‑based document composition across the site graph.

It:

• Requires a selector
• Optionally constrains search using resource
• Enforces single‑match resolution
• Treats ambiguity as a server integrity failure
• Preserves fragment provenance for authorization, validation, and write‑through semantics

This makes fragment inclusion a first‑class, HTTP‑addressable primitive rather than a template‑time convenience.