[6.x] Include Tag

[JohnathonKoster]

Fixes #8175
Fixes #10703
Fixes #11486
Fixes #12709

Overview

This PR adds a new include tag: a strictly-scoped alternative to partial for rendering another view, available in both Antlers and Blade.

The partial tag automatically shares every variable from the template using it with the partial being rendered. That convenience is the root cause of a long line of historical scoping issues and little paper-cuts. Variables set inside a partial leaking back out (but only sometimes), parameters and front matter showing up in other partials rendered later on the page, and behavior changing depending on which syntax was used.

Fixing these issues with the existing partial tag would absolutely break a ton of sites, so include is here!

<s-include:cards/author name="Jimothy" :bio="author_bio" />

<s:include:cards/author name="Jimothy" :bio="$authorBio" />

How it differs from partial

	partial	include
Variables from the surrounding template	All of them	Only what you pass in
Variables set inside the view	Can leak back into the page	Stay inside the include
The Cascade (page, globals, etc.)	Automatically available	Requires cascade="true"
Front matter	Visible to other views rendered later	Stays with the include
Slots	Rendered up front, passed as strings	Rendered on demand, and the view can pass data to them

Passing data

You must pass data to the include tag explicitly. Parameters become variables inside the view, and you can spread an entire array using :params. Inside the view, use params to check what was passed in:

<s-include:cards/author :params="author" role="Editor" />

{{# Inside the view: {{ name }}, {{ avatar }}, {{ role }}, {{ params:role }} ... #}}

Use handle_prefix to make prefixed keys like hero_title available as both hero_title and title:

<s-include:hero :params="entry" handle_prefix="hero_" />

Slots

Content between the tag pair becomes the default slot, and you can define named slots with slot:name pairs.

<s-include:modal title="Delete this entry?">
    <s-slot:footer><button>Cancel</button></s-slot:footer>
    <p>This action cannot be undone.</p>
</s-include:modal>

{{# views/modal.antlers.html #}}
<h2>{{ title }}</h2>
<main>{{ slot }}</main>
<footer>{{ slot:footer }}</footer>

Slots only render when the view actually uses them, and the view can pass data back to your slot content. A view can render a slot once per item in a loop, for example:

{{# views/table.antlers.html #}}
<table>{{ rows }}<tr>{{ slot:row :cell="value" }}</tr>{{ /rows }}</table>

{{# Your template: #}}
<s-include:table :rows="rows">
    <s-slot:row><td>{{ cell }}</td></s-slot:row>
</s-include:table>

You can also forward a slot you received on to another include:

{{# views/panel.antlers.html #}}
<section class="panel">{{ slot }}</section>

{{# views/card.antlers.html forwards its slot along: #}}
<s-include:panel :slot="slot" />

{{# Your template: #}}
<s-include:card>Card content</s-include:card>

The Cascade

Included views don't see the Cascade by default. Pass cascade="true" when you want it:

<s-include:site_header cascade="true" />

Conditionals and existence

Use when and unless to control whether anything renders. exists and if_exists work the same way they do on partial:

<s-include:promo :when="show_promo" />
<s-include:if_exists src="cards/{type}" />

The issues

• Inconsistent behaviour for variables set in a partial #8175: variables set inside a partial sometimes leak into the surrounding template, depending on what else the partial contains. With include they never do.
• Cascade method getViewData should only return the data from the current view and not all of it. #10703: parameters passed to one partial show up in the view: data of the next one rendered on the page. Each include only sees its own.
• Leakage or not leakage? Of view variables in antlers partials with frontmatter #11486: front matter from nested partials hangs around between inclusions and leaks into the layout. An include cleans up after itself.
• Shorthand version not working as intended #12709: wrapping a partial in {{ if }} and using the ?= shorthand isolate variables differently. Both behave the same with include.

Notes for reviewers

• When a partial uses handle_prefix, the prefix rewrites variable lookups in everything rendered inside it. The include tag suspends this while it renders, so an enclosing partial's prefix never reaches the included view. Components rendered inside such a partial still inherit the prefix. That is probably unintentional, but changing it could break existing sites, so it's left alone for now.

[jackmcdade]

Looking forward to using this! After a review and playing around, got a couple things I want to make sure are intentional:

Blade → Antlers cascade — If I do <s:include:some_antlers_view /> from Blade, it still sees Cascade values even without cascade="true". Antlers → Antlers correctly gets nothing. Feels like isolation only kicks in on the Antlers tag path — is that working as intended?

scope punching out — Using scope inside an include writes straight to Cascade, and you can even smuggle a deferred slot out and render it later. Is that a blessed escape hatch we should call out, or something we want to plug?

if_exists body in Blade — exists uses the tag body as conditional output, but if_exists turns it into a slot. That feel right to you?

[JohnathonKoster]

Blade → Antlers cascade — If I do <s:include:some_antlers_view /> from Blade, it still sees Cascade values even without cascade="true". Antlers → Antlers correctly gets nothing. Feels like isolation only kicks in on the Antlers tag path — is that working as intended?

Refactored a few things so the include tag will isolate the Cascade in Blade. This logic was moved into the include tag itself and out of the processor to not accidentally mess with existing behaviors.

scope punching out — Using scope inside an include writes straight to Cascade, and you can even smuggle a deferred slot out and render it later. Is that a blessed escape hatch we should call out, or something we want to plug?

Added a test to codify it. It's a neat use of existing behaviors and I don't see the harm in it; it'd be a lot more work to shut this down and its kind of cool!

if_exists body in Blade — exists uses the tag body as conditional output, but if_exists turns it into a slot. That feel right to you?

The existing behavior is correct IMO. The exists variant shouldn't be used as a tag (or tag pair) as its purpose is to determine if a view exists:

@if (Statamic::tag('include:exists')->src('cards/author')->fetch())

@endif

@if (Statamic::tag('partial:exists')->src('cards/author')->fetch())

@endif

{{ if {include:exists src="cards/author"} }} ... {{ /if }}
{{ if {partial:exists src="cards/author"} }} ... {{ /if }}

ref: https://statamic.dev/tags/partial-exists

[jackmcdade]

Awesome, thanks man!

[jasonvarga]

Really nice piece of work — the scoping model is the right call, the try/finally discipline around cascade and prefix state is careful, and the test suite (9 files, ~1,680 lines, one test per closed issue plus a dedicated SandboxTest for scope-escape attempts) is unusually thorough. The randomized nowdoc terminator is a good catch on its own: slot content containing a literal COMPILED; line would previously have broken out of the hoisted heredoc.

A couple of things need fixing before this ships, since once the behaviour is out it becomes BC. Details are on the relevant lines; the rest are notes below.

Notes (not line-specific)

Missing Antlers coverage for include:exists / include:if_exists. The PR description documents <s-include:if_exists src="cards/{type}" />, and RendersViews::exists() / ifExists() are new code paths for IncludeTag. Blade covers them (IncludeCompilerTest::it_forwards_exists_method_calls and it_forwards_if_exists_method_calls), but there's nothing equivalent under tests/Antlers/Runtime/Includes/. Same gap in the other direction for the src form — Antlers has test_it_renders_a_view_using_the_src_form, Blade doesn't test <s:include src="..." />.

New trait members are private in an otherwise protected trait. CompilesPartials was entirely protected; the six new members (compileSlotOutput, compileIncludeSlot, rawSlotName, isValidSlotName, compileInclude, compileViewTag) are private. compilePartial() stays protected and delegates, so the existing extension point survives — consistency nit only.

GlobalRuntimeState::captureRuntimeState() going from 3 to 4 elements is handled safely. restoreState() uses $capturedState[3] ?? true, and list-destructuring in third-party code ignores the extra element. Just flagging that I checked.