Setting up E-commerce Resource Previews
Using preview types for custom fields, you can configure page and section model content to display previews of your e-commerce platform's resources while editing in the Visual Editor.
Prerequisites
To get the most out of this document, make sure you've enabled and set up your e-commerce plugin. For detailed instructions, see Setting Up Built-in Plugins.
Adding the preview type field to your data model
- Go to Models.
- Open your model and click the +New Field button.
- Give the new field a descriptive name, such as
productPreview. - In the Type drop-down, select one of your e-commerce plugin's preview types. This example uses the Shopify product preview type.
- Builder prompts you to choose a default value from your products. Though you can close the prompt without choosing a default value, we recommend selecting a default value as a best practice. This helps your team mates understand the purpose of the field.
The video below shows these steps while adding a Shopify product preview custom field.
Setting the preview URL
When you open content within the Visual Editor for a model that has a preview field, a searchable list of e-commerce resources appears. Selecting a resource fetches its data from your e-commerce platform and can be used to construct a template string for the editing URL.
For example, you can set your model's editing URL to a template string that embeds a product's handle, such as http://localhost:3000/products/${product.handle}. You can respond to the request with a dynamic route on your back end by parsing the handle, fetching data from your e-commerce platform, and exposing that data to your content through state or context.
With this technique, non-developer teammates can preview what products, collections, and other resources look like on your product detail pages—also known as PDPs—and other content.
How Builder populates the URL
Builder determines the value of productPreview.handle when the user opens the model's content in the Visual Editor and selects a resource from the searchable list.
The plugin fetches the associated data from the e-commerce platform and exposes its properties to the editing URL template string on an object with the same name as the field. In this case, productPreview.handle represents the handle of the selected product.
Leveraging dynamic preview URLs
After setting up your model's editing URL to use the preview field's handle or ID, as above, you can create a dynamic route on your back end that:
- Parses the URL path to extract the resource's handle or ID
- Fetches the resource's data from your e-commerce platform using the parsed identifier
- Exposes the fetched data to your content using state or context
You can then use data bindings on your blocks to display your resource's data with data bindings.
For more information on using this technique with URLs, see Dynamic Preview URLs.
Selecting a resource to preview
You can preview a resource by selecting it from the searchable list that appears when you open your model's content in the Visual Editor.
The searchable list doesn't appear again after making your selection when you reopen your content because your selection is saved across sessions.
You can change the preview selection in the future from the Options tab in the Visual Editor by selecting the preview field's edit button.
The annotated screenshot below illustrates how an example page might display a preview for a product in a Shopify store:
- The editing URL, previously set to
http://localhost:3000/products/${productPreview.handle}, evaluates tohttp://localhost:3000/product/short-sleeve-t-shirtafter the user selects the Short sleeve t-shirt for the preview field. - A binding for the title of the Product View block, which is a custom component in the example registered by the application, sets the Product View's title to
state.product.title.state.productis passed when rendering the content in the dynamic route on the back end. - The title renders within the Product View block's custom component.
Next steps
For more information on using e-commerce plugins, check out the following articles:
Need Expert help?
Reach out to us, and we will match you with a Builder expert.