How do layouts and partials compose one page in a server-side template engine, and what does each mechanism cost?

A page of any size is not one template. Engines give two composition mechanisms that pull in opposite directions, and most confusion about server-side templating comes from mixing them without noticing which one is in play. ## Layouts: composing from the outside in A layout is the page frame — document shell, header, navigation, footer — with **named holes** in it: blocks, sections, slots, whatever the engine calls them. A page template says which layout it belongs to and provides content for some of those holes; holes it leaves alone keep the layout's default. Two execution styles exist: - **The child drives.** Rendering starts from the page template, which declares its parent; the engine renders the parent and substitutes the child's blocks as it reaches them. - **The frame drives.** Rendering starts from the layout, which pulls the page's rendered body in at a designated point. The observable difference shows up in ordering questions: whether the page body is rendered before or after the surrounding frame decides whether the body can still contribute something the frame uses — a title, a set of page-specific styles, a breadcrumb. Engines that render the body first can let it push values upward; engines that render the frame first need those values supplied in the model instead. ## Partials: composing from the inside out A partial is a template rendered at a point inside another template. The question that decides everything about it is **what variable scope it sees**. | Partial style | What it can read | Strength | Cost | |---|---|---|---| | Ambient context | the caller's entire scope plus framework-supplied values | nothing to wire up; fastest to write | silently depends on names the caller happens to provide | | Explicit parameters | only what the call passes in | reusable, testable, its contract is readable | more typing, and every call site must be updated when it changes | | Self-loading fragment | fetches or computes its own data at render time | callers stay ignorant of what it needs | hides work inside rendering, and repeats per row when looped | Ambient is the default in most engines because it is convenient, and it is a perfectly good choice for a fragment that exists only to split one long page into readable files. It becomes a problem the moment the fragment is reused: the second caller does not supply `currentFilter`, the fragment renders empty or raises, and the failure appears in a template rather than in code. A shared fragment should take parameters, because that is what turns it from a copy-paste unit into a component with a contract. The self-loading fragment deserves its own warning. A partial that goes and fetches what it needs looks elegant and, rendered inside a loop, performs one lookup per row — the rendering-layer form of the repeated-query problem. Worse, the work happens after the handler has returned, which is usually after any transaction or timeout budget the handler was operating under, and often after the response has begun. ## What composition costs 1. **Provenance.** With a three-deep layout chain and nested fragments, answering "where is this value set?" means walking the chain. Shallow hierarchies — a base layout, at most one specialised layout, then pages — keep that answerable. 2. **Lookup and cache pressure.** Every included fragment is its own resolution and its own compiled-template cache entry. That is cheap, but a loop that includes a fragment per row multiplies the per-render bookkeeping, and a fragment name computed at runtime can defeat caching entirely. 3. **Inherited settings.** Escaping mode, locale and strictness generally come from engine configuration and flow into fragments regardless of who called them. A fragment cannot assume the caller's settings, and a call-site decision about unescaped output does not travel into the fragment it calls. 4. **Duplication that composition does not fix.** Splitting a page into fragments removes repeated markup but not repeated model preparation; if every page that includes a fragment must compute the same three values first, that belongs in shared code, not in every handler. ## Practical rules that hold generically - Give any fragment used by more than one page an explicit parameter list, and treat that list as its public interface. - Keep layouts shallow and give blocks names that say what they are for rather than where they sit. - Let the handler assemble the data; let templates arrange it. A fragment that queries is a fragment that will surprise someone under load. - Name fragments from a fixed set, never from request input, so resolution and caching stay bounded and predictable. - Where a fragment is also the unit you re-render for an incremental page update, define it once and render it from both the full-page path and the fragment path, so the two cannot drift.