Made in Builder

Made in Builder

Webinar 👉 Visually Build at Scale with Builder.io & Netlify on 12/1

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

Product

Features

Integrations

Talk to an Expert

Pricing

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

Getting the Preview URL Working

Most of the time, when you've successfully integrated your app with Builder, you can automatically edit and preview your site using a preview URL. However, since each use case is unique, it can help to have context about how the Preview URL works and what to do if your content isn't loading.

This document guides you through the following:

Prerequisites

To get the most out of this document, you should have already completed the following:

How Builder's preview URL works

When you've integrated your app with Builder, Builder loads your site in an iframe in the Visual Editor.

When your page loads in the Builder web app, Builder components on your page notify Builder with a message indicating that your component is present.

For example, if you are opening a page to edit your Page model, Builder waits for a message from a component with the model of Page. When Builder receives this message, Builder sends a message specifying the content to render for the preview.

The following image delineates the Builder UI:

  • The outer Builder web app, in blue, encompasses the Visual Editor tabs and in this case the model of Page
  • The iframe, in green, within the Visual Editor renders the content that you're editing
  • The Builder component, in purple, which in this case is a hypothetical integrated page referenced in your code base

For more information, refer to Preview URL best practices.

As you make edits, Builder passes messages to this component with the changes to the component.

The following diagram shows the data flow between the Builder component and the Builder web app. When the page component is loaded in the iframe, Builder receives a message that it is there. As soon as any changes occur, the Builder web app sends a message to the Builder component with the updates.

Turning off preview for a specific URL

To turn off the default behavior of previewing and editing on the specific URL for a page, do the following.

  1. Go to Account Settings > Advanced Settings > Advanced.
  2. Toggle Reload preview on URL path change to the off position.

You can turn off this setting to load the preview and editor on your hardcoded URL; for example, /builder-editing, regardless of the current editor path.

The following video demonstrates how to turn off the Reload preview on URL path change setting.

Getting your iframe to load

If you've integrated successfully, your content should load automatically in the Visual Editor iframe, but because each app is unique, if you're content hasn't loaded, there are a few things you can do.

The following should help get your content in the Visual Editor:

Making sure your headers are allowing Builder

If you are using headers that block iframes from loading, such as x-frame-options or content-security-policy, be sure to allow https://builder.io or install the Builder Chrome extension so the Visual Editor can load your site.

To confirm if you need to allow https://builder.io, open your browser's developer tools and check for output that suggests content from Builder is being blocked. A possible message logged to the console might be:

The following is a screenshot of this message in the console:

Turning on Proxy previews

As an alternative, you can turn on Proxy previews to handle the iframe contents automatically by doing the following:

  1. Go to Account Settings > Advanced settings > Advanced tab.
  2. Set Proxy previews to the on position.

Using the Builder Chrome extension

Another option for loading the contents of an iframe is to use the Builder Chrome extension, which, while editing, removes the headers that are blocking your site from loading.

The following video gives a short demo of using the Chrome Extension to edit your content. In addition to launching the Visual Editor with your content in an iframe, the Chrome extension also shortcuts the process of finding content. For more information refer to Editing Your Site Using the Builder Chrome Extension.

Allowing insecure content

If you are working on developing your site locally; for example, on http://localhost or http://127.0.0.1, you might need to tell your browser it's ok to load your local site–which is using http, an insecure protocol–within Builder's secure https app. The following video demos how to toggle this setting in Chrome:

For written instructions and more detail, refer to this StackOverflow answer for Chrome and Mixed Content Blocking for Firefox.

In some cases, you may need to manually configure your server technology's Content Security Policy to permit loading the project in an iframe. The below header instructs a localhost:3000 server to allow loading in an iframe and in Builder.io:

Checking for Builder in your code

If your page isn't showing up in the Visual Editor, confirm that Builder and your app are connected. Open that same page on your site and ensure the page loads as expected and the Builder component has rendered. For example, if using a framework like React, you should see <BuilderComponent /> or <BuilderPage /> rendered on the current page with React devtools.

With most other integrations, you should see a <builder-component> tag in the page's HTML. The following images point out how Builder content shows up in the inspector. This first example highlights <builder-component>:

This second example shows the Components tab with BuilderContent among the components.

If you do not see the relevant code, check your integration for conditions that are not met. For example, if your code has logic that says if Builder has no such content for a URL to render something else, be sure to update your code to still show the Builder code component or snippet anyway for your hardcoded editing route, such as your-site.com/builder-editing.

Check on any conditional logic in your code that might prevent the relevant Builder component from loading under certain conditions; for example, a page URL that has no live content yet but you still need your component to load for editing in the iframe in the Visual Editor for receiving messages from the web application to display and preview content in real time.

To ensure that your logic is returning your Builder content as intended, you can use Builder.isEditing and Builder.isPreviewing . The following example only returns a 404 if you're not editing, not previewing, and there's no Builder content. Otherwise, if there's a page, it should render. We recommend this approach as it accounts for most conditions.

✅ Good: best practice

Check for Builder.isEditing to always render BuilderComponent when editing

The following is an example of a pattern to avoid. This example returns a 404 if there is no Builder content, however, it doesn't take into account editing or previewing, so it is more likely that BuilderComponent might not render.

❌ Avoid: not a best practice

BuilderComponent might not render when editing due to conditional logic in this code

Using a preview URL with static sites

When working on static sites, such as with Gatsby, Nuxt, or Next.js in static mode, there is some additional configuration you might need to do to get your preview URL to render previews.

By default, when creating a page and editing it in Builder, the editor and preview loads the URL for that page. For example, if you create a new page at /example but your static site has no such page, you could get a 404. There are two options for this scenario:

Adding Builder component to your 404 page

If you're getting a 404, add the Builder component to your 404 page to support previewing and editing.

On your 404 page in your code base, add <BuilderComponent> as in the following code snippet. In this example, if the page isn't found, BuilderComponent still returns a Builder page, so Builder gets the message it expects and returns a page.


Need Expert help?

Reach out to us, and we will match you with a Builder expert.

Connect with us

Was this article helpful?