GT Page Blocks Builder Preview System
GT Page Blocks Builder previews use an iframe to show your sections with the available theme styles. Ordinary inline sections in Code mode render in the browser; Visual mode, native blocks, formatting or PHP settings trigger a server-rendered preview.
A preview helps you edit, but it does not reproduce every page-level condition. The distinction becomes visible with linked library blocks, third-party styles and interactive content.
How the Preview Works
The preview constructs a full HTML document and sets it as the iframe’s srcdoc. The document includes, in order.
- Theme stylesheet
<link>tags. - Theme inline styles (global styles, classic theme styles).
- Preview injection head HTML (if configured).
- Injected CSS from the preview injection filter.
- Section CSS combined into a
<style>tag. - Body start HTML from the preview injection filter.
- Section HTML content.
- Body end HTML from the preview injection filter.
JavaScript isn’t written into that document. Once the iframe has loaded, the builder injects scripts as elements in this order: head JavaScript from the preview settings, inline section JavaScript, footer section JavaScript, footer JavaScript from the preview settings, then a small reveal helper. Because the page has already loaded by then, a DOMContentLoaded listener in section code can miss its event in the preview even though it runs on the live page. Run setup code right away, or check document.readyState first.
Theme Asset Collection
The visual builder automatically discovers and loads your theme’s CSS files into the preview.
Stylesheets
The builder collects theme stylesheets from three sources.
Explicit theme styles. The child theme’s style.css and parent theme’s style.css are always included. Additionally, any CSS files found in the theme’s css/ and assets/css/ directories (recursively) are included.
Page stylesheets. Any <link rel="stylesheet"> tags on the builder page whose URLs match the theme directory are collected.
Inline styles. Any <style> tags with IDs containing “global-styles”, “classic-theme-styles”, or starting with “theme” are collected.
Scripts
Theme JavaScript isn’t loaded in the preview, and neither is jQuery. Effects that depend on theme scripts, such as scroll-reveal animations, won’t run there. So that content doesn’t stay hidden, a reveal helper adds common classes such as visible, is-visible, in-view, aos-animate and active to elements like [data-aos] or classes containing reveal, fade or slide. The gt_pb_preview_reveal_enabled, gt_pb_preview_reveal_classes and gt_pb_preview_reveal_selector filters adjust it.
Client-Side vs. Server-Side Preview
The preview uses two rendering modes depending on section settings.
Client-Side Preview
In Code mode, when no section has format or phpExec enabled and none holds native or core blocks, the preview is built entirely in the browser. The raw HTML, CSS, and JavaScript from your sections are assembled into the preview document without any server request. This is instant.
Server-Side Preview
In Visual mode, or when any section has format or phpExec enabled or holds native or core blocks, the builder posts the sections to the front-end preview route /?gt_pb_preview=1 with the md_page_blocks_builder_preview action. It runs the same login, nonce, capability and post-type checks as the builder. When the Functionalities plugin is active, every preview is server-rendered. The server processes the content (executing PHP, applying wpautop()) and returns the rendered output as JSON.
POST /?gt_pb_preview=1
action=md_page_blocks_builder_preview
post_id=123
pb_nonce=abc123
sections=[{"content":"...","css":"...","js":"...","format":true,"phpExec":false}]The response contains.
{
"success": true,
"data": {
"html": "rendered HTML output",
"css": "minified CSS",
"jsInline": "inline JavaScript",
"jsFooter": "footer JavaScript"
}
}The builder then inserts this rendered output into the preview document in place of the raw section content.
Preview Debouncing
In the visual builder, HTML and JS edits rebuild the preview right away. CSS edits wait 1,000 ms after you stop typing, and any server-rendered preview waits at least 250 ms, so rapid typing doesn’t send a request for every keystroke.
In the Gutenberg block editor, the preview updates reactively when block attributes change, using React’s effect system.
Preview Request Tracking
Both the visual builder and the Gutenberg block use request ID tracking to prevent stale responses. Each preview request increments a counter. When the response arrives, it checks whether the counter has advanced (meaning a newer request was made). If it has, the stale response is discarded.
Viewport Controls
The visual builder’s preview canvas includes viewport control buttons.
- Desktop renders the preview at full width (no constraint).
- 992 constrains the preview iframe to 992px wide.
- 768 constrains to 768px.
- 480 constrains to 480px.
- 360 constrains to 360px.
The iframe resizes to the selected width with max-width: calc(100% - 24px) to maintain a small margin. The active viewport button is highlighted.
Hidden Sections
In the visual builder, the eye icon hides a section from the preview. Hidden sections are excluded from the preview document but are still saved and still render on the live page. The hidden state isn’t saved, so every section shows again the next time the builder loads. This lets you temporarily hide sections to focus on specific parts of the page during development.
Preview in Gutenberg
The Gutenberg block editor also supports preview mode for individual Page Blocks. Click Preview in the block toolbar to switch to preview mode. The block shows an iframe with the rendered output, including theme stylesheets. Click Edit code to return to editor mode.
When format or phpExec is enabled on the block, the Gutenberg preview uses server-rendered content through the md_page_blocks_builder_preview action on admin-ajax.php.
Check Layout and Behavior Separately
A narrow screenshot checks layout. Clicking an interface control checks behavior. Both matter for an interactive section.
The dark-mode controls inside these demos are authored JavaScript and CSS. They should not be confused with a built-in visual-builder control.
Linked Library Preview Limitation
In Code mode, a browser-built preview can leave out linked library sections, because it only switches to a server preview for formatting, PHP or native blocks, not for library links. Visual mode always renders the preview on the server, so it shows linked sections.
The inline course exports avoid that dependency. A server preview can resolve the linked source, but enabling Auto-format merely to force that path can change paragraph markup. Switching to Visual mode is the cleaner check.
Quick answers to common questions:
Is the preview the real frontend rendering?
Not in every case. Ordinary inline sections in Code mode use a browser-built preview, while Visual mode, formatting or PHP request server rendering. Page-level styles, query context, missing theme scripts and linked blocks in a Code-mode browser preview can make a preview differ from the frontend.
Why does my preview differ from the published page?
Check whether the section is linked, which template is assigned, and whether the preview has the required CSS. Check cached output only after confirming that WordPress holds the expected saved content.
For a step-by-step walkthrough, see How to Add a Calculator or Pricing Toggle to a Page.