Docs /PageCraft

Dynamic Content

Audience: Editor and Site Builder.

Dynamic Content is the bundled section that embeds an EE template inside a PageCraft canvas. Use it when part of the page should render at request time — a blog listing, a product grid, a featured-entries strip — instead of being baked into the saved entry HTML.

Workflow

  1. Open the section picker → PageCraft category → Dynamic Content. Drop it into the canvas.
  2. Click the dashed placeholder ("Click to select an EE template").
  3. The slideout opens with a dropdown listing every template in your EE site (flat-file or DB-backed; both work). Templates are grouped and sorted; templates whose names start with _ are dimmed but still selectable.
  4. Pick a template (e.g. blog/listing_grid). The canvas immediately fetches the rendered HTML and shows a live preview in place of the placeholder.
  5. Save the entry. The selected template path persists.

What's stored

The placeholder div carries a single attribute:

<div data-cb-type="template-embed" data-pc-template-path="blog/listing_grid">…</div>

Two notes on the attribute:

  • data-pc- namespace is intentional. ContentBox aggressively strips empty data-cb-* attributes during snippet insertion, which would lose the template path if we used data-cb-template-path. The PC namespace is round-trip safe.
  • The sentinel __unset__ is used as the value before a template has been chosen. ContentBox would otherwise drop the attribute entirely (empty string is treated as "no value present"), and there'd be no key to write into when the user finally picks a template.

Front-end render

When the entry renders, {exp:page_craft:html} walks the saved markup, finds every data-cb-type="template-embed" element, reads its data-pc-template-path, and replaces the placeholder's inner HTML with the rendered template. The substitution happens server-side at request time — the consumer never sees the placeholder.

The render path:

  1. mod.page_craft.php::resolveTemplateEmbeds() (front-end render path)
  2. Services/TemplatePreview.php::render() (shared with the editor preview path)
  3. Template lookup: flat file in system/user/templates/<site_short_name>/ first; DB fallback via the templates table.
  4. Parser annotation cleanup: {!-- ra:HEX --} and {!-- bloqs:start:N:N --} markers are stripped before the result is returned. EE's normal post-process handles these on a real page render, but the embed path runs in isolation so it does the cleanup itself.

Editor preview

Inside the canvas, the same render runs through Actions/TemplateRenderPreview.php (the template_render_preview ACT) which returns a small JSON envelope { html, error }. That keeps the editor preview byte-identical to what your visitors see — if a template parse error happens, you see it in the editor before publishing.

Caveats

  • Templates that depend on {logged_in} / {logged_out} always render as if the visitor is logged out in the preview path. The preview process zeroes out the session member ID before parsing so private content doesn't leak into draft previews.
  • Embedded templates shouldn't include their own {layout=...} tag — the embed strips it because the wrapping page is responsible for layout, not the embedded fragment.
  • Heavy templates render every time the entry is saved (preview) and every time the entry is rendered (front-end). Add EE's normal {exp:channel:entries cache="yes"} or template caching at the wrapping template level if you need to throttle the cost.
  • An embed renders when the page renders, so any page cache freezes it with the page. That includes EE template caching and static or full-page caches (Speedy, CE Cache, a CDN). A change to the embedded template, or to the entries it lists, appears only after that page's cache entry is cleared or expires.

Restricting which templates can be embedded

By default any site template can be embedded. To limit it, list template groups (or exact group/template paths) in system/user/config/config.php:

$config['pagecraft_template_embed_roots'] = ['embeds', 'partials/footer'];
// or as a string: 'embeds, partials/footer'

This is enforced where an embed renders, front end and editor preview alike, not only in the picker. That matters because anyone who can edit a field's HTML can type any path into data-pc-template-path. The picker then lists only the allowed templates too. Remove the line to allow everything again.

An embed that would render itself, directly or through a template that renders the same field, is skipped and leaves an HTML comment explaining why. Embeds nested more than three deep are skipped the same way.

Reference

  • Plugin source: themes/user/pagecraft/assets/plugins/template-embed/index.js
  • Front-end render: mod.page_craft.php::resolveTemplateEmbeds()
  • Editor preview: Actions/TemplateRenderPreview.php
  • Shared render service: Services/TemplatePreview.php