Skip to content
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:

  • mod.page_craft.php::resolveTemplateEmbeds() (front-end render path)
  • Services/TemplatePreview.php::render() (shared with the editor preview path)
  • Template lookup: flat file in system/user/templates/<site_short_name>/ first; DB fallback via the templates table.
  • 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 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.

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