Visual Builder

Lesson 5 of 15 6 min read
  • JNext lesson
  • KPrevious lesson
  • FSearch lessons
  • EscClear search

The visual builder is a full-screen frontend editing interface for managing Page Block sections. It provides a live preview canvas, code editors, a section management sidebar, and viewport controls for responsive testing.

Accessing the Builder

There are two ways to open the visual builder.

From the admin bar. When viewing any singular post or page on the frontend (while logged in), the admin bar shows a “Page Blocks Builder” link. This link appears as a child of the “Edit” node if it exists, otherwise as a standalone item. Clicking it opens the builder for that post.

Direct URL. The builder is accessed via a special query string on the site’s home URL.

https://yoursite.com/?build=page-blocks&post_id=123&pb_nonce=abc123

The post_id parameter identifies the post, and pb_nonce is a security nonce that’s validated before granting access.

Access Requirements

To use the builder, you must be logged in with the edit_post capability for the target post, the post type must be enabled in the plugin settings, and the nonce must be valid. If any check fails, the builder returns a 403 Forbidden error.

When the builder loads, the WordPress admin bar is hidden to give you a clean, full-screen editing environment.

Layout Overview

The builder interface is divided into distinct areas.

Top Bar

The top bar spans the full width and contains.

  • Brand label (“Blocks”) on the left.
  • Toggle buttons for showing/hiding the Sections sidebar and Code panel.
  • Apply to Gutenberg button in the center, which saves all sections to the post.
  • Close button on the right, which navigates back to the Gutenberg editor.

Preview Canvas

The main area of the builder is a live preview rendered in a sandboxed iframe. The iframe loads your theme’s stylesheets so sections appear as they will on the live site.

Above the preview is a toolbar with viewport controls. You can switch between Desktop (full width), 992px, 768px, 480px, and 360px widths to test responsive behavior. The preview iframe resizes to the selected width.

Section Sidebar

The right sidebar lists all sections in order. Each section item shows.

  • Grip handle (⋮⋮) for drag-and-drop reordering.
  • Section name inferred from the HTML content. The builder looks for the first <section id="..."> or heading tag (h1–h6) in the HTML. If none is found, it falls back to “Section 1”, “Section 2”, etc.
  • Action buttons for collapse (hide from preview), duplicate, and delete.

The sidebar header shows the total section count and a “+” button to add new sections.

Below the section list is an “Active Section” panel that displays the current section’s inferred ID and CSS classes extracted from the HTML.

Code Panel

The bottom panel contains the code editors. It uses a two-column layout.

  • Left column is always the HTML editor.
  • Right column shows either CSS or JS. Use the swap button in the column header to toggle between them.

Above the code editors is a toolbar with section-level options.

  • wpauto checkbox to enable WordPress content formatting.
  • PHP checkbox to enable PHP code execution.
  • JS Location dropdown to choose between Footer and Inline placement.

Splitter

Between the preview canvas and the code panel is a draggable splitter. Drag it up or down to resize the preview and code areas. You can also drag from the top edge of the code panel itself. The minimum code panel height is 240px.

Status Bar

At the very bottom is a status bar showing a “Live preview” indicator and a count of visible sections out of total sections (e.g., “3/5 sections” when 2 sections are collapsed).

Section Management

Adding Sections

Click the “+” button in the sidebar header, or press Cmd+N / Ctrl+N. New sections are inserted after the currently selected section.

Selecting Sections

Click a section name in the sidebar to select it. The code editors update to show that section’s content, and the section is highlighted in the sidebar.

Duplicating Sections

Click the duplicate button (⧉) on a section, or press Cmd+D / Ctrl+D. The duplicate is inserted immediately after the original. If the original section’s HTML contains an id attribute, the duplicate appends “-copy” to avoid ID collisions.

Deleting Sections

Click the delete button (✕) on a section, or press Cmd+Backspace / Ctrl+Backspace. If you delete the last remaining section, an empty section is automatically created.

Reordering Sections

Drag a section by its grip handle to a new position in the sidebar. You can also use Alt+Arrow Up and Alt+Arrow Down to move the selected section.

Collapsing Sections

Click the collapse button (◉/◌) to toggle a section’s visibility in the preview. Collapsed sections are excluded from the preview iframe but are still saved and rendered on the frontend. This is useful for temporarily hiding a section while you work on others.

Live Preview

The preview updates automatically as you edit code, with a 110ms debounce to avoid excessive re-rendering. The preview is rebuilt by constructing a full HTML document that includes.

  1. Your theme’s stylesheets (collected from the page’s linked stylesheets).
  2. Theme inline styles (global styles, classic theme styles).
  3. Preview injection content (if configured via the filter).
  4. Your sections’ CSS in a <style> tag.
  5. Your sections’ HTML content.
  6. Theme scripts (from theme directories and jQuery if present).
  7. Your sections’ JavaScript.

When any section has format or phpExec enabled, the builder requests a server-rendered preview via AJAX. The server processes the PHP and wpautop formatting and returns the rendered output, which is then injected into the preview document.

Template-Aware Preview

The builder detects which page template is assigned to the post and applies a CSS class to the shell element (is-template-default, is-template-builder, or is-template-premium-builder). This can affect how the preview canvas is styled.

Saving

Clicking “Apply to Gutenberg” (or pressing Cmd+S / Ctrl+S) triggers the save process.

  1. The builder collects all sections into a JSON payload.
  2. It sends the payload to the md_page_blocks_builder_apply AJAX endpoint.
  3. The server validates the nonce and user capabilities.
  4. Existing Page Block instances in the post content are removed.
  5. New Page Block instances are created from the payload and inserted at the position where the first Page Block was found (or at the end if none existed).
  6. The post is updated via wp_update_post.
  7. The page template is auto-set to “Page Blocks Builder” if no template was previously assigned.
  8. The autosave draft is cleared.

The save button shows “Saving…” during the request, “Saved” on success, and an alert message on failure.

Closing the Builder

The “Close” button navigates to the Gutenberg editor for the current post. If the builder was opened in an embedded context (iframe), it sends a cancel message to the parent window instead.