Skip to content

Liveview Bridge

The Liveview Bridge is the structured postMessage layer that connects the Hyvä CMS editor to the storefront preview iframe. The editor and the preview run in different documents (often on different domains), so they cannot call each other directly. The bridge gives both sides a small, typed API for sending messages back and forth: pushing rendered content into the preview, opening a field's editor panel from a preview click, scrolling to a component, and forwarding events such as keystrokes.

This is a developer topic. Most projects never need to touch the bridge directly, but understanding it helps when building custom field handlers, preview interactions, or content-type integrations.

The Two Sides

The bridge defines a global window.liveviewBridge object on each side of the iframe boundary.

  • Editor side: src/liveview-editor/view/adminhtml/templates/page/js/utils/liveview-bridge.phtml. Provides toPreview().
  • Preview side: src/liveview-editor/view/frontend/templates/bridge.phtml. Provides toEditor(). The preview-side bridge is only emitted in a valid preview context, so it is never present on the public storefront.

Both sides share the same liveviewBridge.MSG constant map, so message types stay in sync.

Sending Messages

Every message is an object of the shape { type, ...payload }.

From the preview, send to the editor with toEditor(type, payload):

// Open the editor panel for a specific component field
window.liveviewBridge.toEditor(
    window.liveviewBridge.MSG.ACTIVATE_FORM,
    { component: uid, field: 'title' }
)

From the editor, send to the preview with toPreview(type, payload, iframe). Pass a specific iframe to target one preview, or omit it to broadcast to every preview panel (useful in split view):

// Push re-rendered content into one preview iframe
window.liveviewBridge.toPreview(
    window.liveviewBridge.MSG.UPDATE_CONTENT,
    responseData,
    iframe
)

The editor receives inbound messages through an @message.window handler in liveview-composer.phtml, which routes each message type to the matching editor action.

Message Types

liveviewBridge.MSG exposes these message types. The string values are stable identifiers prefixed with liveview-.

Constant Value Direction Purpose
FOCUS_COMPONENT liveview-focus-component Editor to preview Scroll the preview to a component and pulse-highlight it
UPDATE_CONTENT liveview-update-content Editor to preview Push re-rendered HTML and styles into the preview
ADMIN_PREVIEW liveview-admin-preview Editor to preview Signal that the preview is running inside the editor
ACTIVATE_FORM liveview-activate-form Preview to editor Open the editor panel for a clicked component or field
TOGGLE_COMPONENT_LIST liveview-toggle-component-list Preview to editor Open the add-component picker (used by the empty state)
MISSING_CONTENT_NODE liveview-missing-preview-content-node Preview to editor Report that the preview content node could not be found
STOREFRONT_INFO liveview-storefront-info Preview to editor Send storefront context back to the editor
CONTEXT_FIELD_TYPES liveview-context-field-types Editor to preview Send the per-component handler-field map for context editing
CONTEXT_OPEN_HANDLER liveview-context-open-handler Preview to editor Open a field handler from the preview context menu
CONTEXT_HIGHLIGHT_SIDEBAR liveview-context-highlight-sidebar Preview to editor Highlight a component in the component tree
CONTEXT_DELETE liveview-context-delete Preview to editor Delete a component from the preview context menu
KEYDOWN liveview-keydown Preview to editor Forward a keystroke so shortcuts work from the preview
IFRAME_POINTER_DOWN liveview-iframe-pointer-down Preview to editor Report a click inside the preview

Constant names changed

Earlier internal names FIELD_TYPES and OPEN_FIELD_HANDLER are now CONTEXT_FIELD_TYPES and CONTEXT_OPEN_HANDLER. If you maintain code or notes referencing the old names, update them to the current constants.

Common Patterns

Closing Editor Dropdowns on Preview Clicks

When a user clicks inside the preview, the preview-side bridge automatically sends an IFRAME_POINTER_DOWN message. The editor converts it into a liveview:iframe-pointer-down window event, and header dropdowns listen for that event to close themselves:

<div @liveview:iframe-pointer-down.window="showDropdown = false">
    ...
</div>

This is how open menus dismiss correctly even though the click happened in a different document.

Keeping Shortcuts Working From the Preview

The preview-side bridge forwards every keystroke to the editor as a KEYDOWN message. The editor replays it through its keybinding handler, so keyboard shortcuts keep working even when the user's focus is inside the preview iframe.