Each e-commerce plugin provides custom types that you can use to add functionality to the Visual Editor. The table below lists each for quick reference and links to more detail.
| Type | Naming Ends In | Description |
|---|---|---|
no suffix | Stores an object representing an asynchronous request for resource data from your e-commerce platform. Ex: | |
| Adds a preview type field to your model. Ex: | |
| Stores a reference to a resource in your e-commerce platform. For handle types like Ex: | |
| Stores references to one or more resources in your e-commerce platform. For list types like Ex: |
A request object type field stores an object representing an asynchronous request for resource data from your e-commerce platform, similar to a JavaScript promise.
The object has three top-level properties:
options: an object with a single property, the name of which corresponds to the resource type and the value of which corresponds to the resource's ID. For example,options.productholds your product's ID.data(optional): an object with a single property, the name of which corresponds to the resource type and the value of which corresponds to the resource's data. For example,data.productholds data fetched from your e-commerce platform about the product.datais only available when you make a content request is made with thenoTraverserequest option or query parameter set tofalsewhile using the JS SDK or Content API and GraphQL API, respectively.request: an object with metadata about the asynchronous resource data request.
You can use request object types wherever you need to refer to a single resource by its ID; for example, while setting up e-commerce resource-based content targeting or creating custom component inputs.
You can select a resource for the field using a searchable list, which at a minimum exposes the resource's ID through the request object's options property. Using that ID, you can fetch resource data from your e-commerce platform and expose it to your components through state and data bindings.
With the noTraverse request option set to false, you can also use request object types to fetch resource data without a separate request, saving you a roundtrip. Builder fetches the data from your e-commerce platform using the resource's ID for you, adding the response to the data property on the request object.
Request object type names, such as ShopifyProduct, have no suffix.
A preview type is a request object type that adds a preview type field to your model and triggers a searchable list to appear when opening that model's content in the Visual Editor if the field is empty.
When you select a resource from the list, the plugin automatically fetches it from your e-commerce platform and exposes its data in the model's editing URL through string templating.
You can use preview types to enable teammates to preview content for specific resources while editing, for instance in a product detail page.
Preview type names end with the word Preview, such as ShopifyProductPreview.
For more information on using preview types, see Setting Up E-commerce Resource Previews.
A handle type stores a reference to a resource in your e-commerce platform such as a product or a product collection. The reference is a string that corresponds to the resource's handle.
The handle is a human-readable, machine-parseable unique identifier assigned by a user or auto-generated by the e-commerce platform. For example, a product called "Short sleeve t-shirt" may have the handle short-sleeve-t-shirt.
You can use handle types for custom component input fields, which allows you to select a resource for the field from a searchable list. Builder passes the handle for the selected resource to your component as a prop with the same name as your field. The prop's value is a string or, if the field is empty, undefined.
Handle type names end with the word Handle, such as ShopifyProductHandle.
A list type stores references to one or more resources in your e-commerce platform. Each reference is a string that corresponds to the resource's ID in your platform.
While handle types also store references to resources, the references stored by list types are primary IDs. For example, a product called "Short sleeve t-shirt" may have the handle short-sleeve-t-shirt and a randomized ID such as 9f870b34-7397-4dc0-b2e7-9d93cdcba0fe. You can call different e-commerce APIs to fetch resource data depending on whether your reference is a handle or a primary ID.
Similar to handle types, use list types to provide a searchable list interface for custom component input fields. Builder passes the IDs for the selected resources to your component as a prop with the same name as your field. The prop's value is an array of zero or more strings.
List type names end with the word List, such as ShopifyProductList.
For more information on using e-commerce plugins, check out the following articles:
