In 2019, BigCommerce released the Widgets API enabling developers to build integrations via REST API to the Page Builder. Since its initial release, we’ve made many updates to both Page Builder and the Widgets API — with more planned development and enhancements coming in 2021.
If you are unfamiliar with these features, BigCommerce Page Builder gives merchants the ability to drag and drop widgets and page components to customize their storefront with ease. According to PracticalEcommerce these tools, “represent newer approaches to software development and deployment that [provide merchants] advantages in functionality at a low cost.”
For developers, the Widget API unlocks the ability to build everything from bespoke widgets, page components, and marketplace applications.
In this blog post, we’ll explore the key features of the Widgets API and share best practices for an optimal developer workflow. We’ll also answer and give clarity to many common dev questions about building custom widgets. Let’s get started and dive deep into widgets and explore the big possibilities they unlock.
What are Widgets?
Widgets are easily configurable web UI elements. They consist of HTML, CSS and Javascript that is JSON encoded. These UI elements can be applied to any BigCommerce approved theme and extend the functionality already available. A merchant can drag and drop these blocks into their theme’s widget regions and even customize the look and feel of a widget from the control panel.
Developers can create custom widgets for a specific client or they can create widget applications that are available in our BigCommerce Marketplace. These widgets can consume store data now more easily, by using GraphQL queries. Widgets can also be configured from an application to call services that are linked to other third-party APIs like Google Maps, Facebook, or Twilio.
Developing and using Widgets are a great way to unlock functionality for the BigCommerce storefront and create solutions that merchants can leverage right away with minimal assistance. This low to no code functionality for merchants enables developers to innovate and merchants to implement their solutions easier than ever before.
Widgets Features and Support
There are several features supported via the Widgets API:
- Widget Templates for the creation and configuration of widgets for both Page Builder and regional placement.
- Widget “CRUD” operations and maintenance.
- Using specified widget regions and create placements for widgets.
- Using global regions for widget placement in generalized regions.
- Versioning of widgets using update logic for templates and widgets.
- The latest development is around allowing templates to pull store data using our GraphQL API.
Types of Widgets
1. Custom-developed widgets.
The custom-developed widgets flow is the base of all widget development. Custom widgets can use storedata from GraphQL or be developed into widget applications.
The custom widget flow documented above shows how to create custom widgets. There are basically two flows with a shared update flow. The first flow ensures that a widget is optimized for Page Builder. These widgets, when placed by the merchant in Page Builder, the POST Widget and POST Placement API calls are made on the developer's behalf by Page Builder, so this process does not need to be done by an application. For most widget use cases, you will want to use this flow.
The second flow is a direct embed to a specific placement. These API placed widgets will always appear below all the Page Builder placed widgets in a specific region. These widgets are not optimized for: utilizing layouts, duplication in various regions, and need to be re-architected if one wants to place them in Page Builder. However, widgets that are placed in regions can have their settings updated in Page Builder.
Based on your requirements and the needs of the client you can determine if you want to have your widget template contain settings. This is a schema object that Page Builder can use to modify things like CSS styling. Page Builder widgets do not require a settings schema but you need to consider how your widget may react to different regions. If that is not necessary because you built the widget template with a specific design and placement in mind, you can just place the widget for the client where it is optimal to do so. This just requires what we talked about in flow two: a region, the widget, and placement.
Versioning and updating widgets are a new feature of the API. This is an optional flow, but a very nice to have feature for managing the widget development lifecycle when you are wanting to update merchants to new versions that could have breaking changes. This allows the merchant to decide if they want the latest version of your widget, absolving developers from the headaches of managing versions outside of the widgets API. Using the Widget Template UUID you can ensure that a template is updated with a flag for “create_new_version” set to true and then update the widget with a flag of “upgrade” set to true.
2. Widgets that leverage storefront data.
Widgets can now leverage storefront data by using the Storefront GraphQL API. These widgets are dynamic in nature but follow the same creation path as above. The BigCommerce Developer Documentation contains a tutorial on how to implement graphql queries into your widget template; Create Widgets powered by GraphQL.
The most important thing is to architect your data to use a single query in your widget template. If you know that you are going to need to use many data nodes, test your query to ensure that the return meets your needs. You can see the GraphQL data relationships using GraphQL Explorer.
Note : Be aware of ‘Complexity Limits’ when using the GraphQL API.
Here is an example GraphQL powered widget template to get you thinking about your next widget build. This widget is Page Builder enabled and would show a product’s name, image and price.
POST [https://api.bigcommerce.com/stores/`{{STORE_HASH}}`/v3/content/widget-templates](https://api.bigcommerce.com/stores/%7B%7BSTORE_HASH%7D%7D/v3/content/widget-templates)
X-Auth-Token: {{ACCESS_TOKEN}}
Content-Type: application/json
Accept: application/json
{
“name”: “Product Widget”,
“storefront_api_query”: “query Product($productId: Int = 1) { site { product(entityId: $productId) { name entityId prices { price { currencyCode value } } defaultImage { url(width: 500, height: 500) } } } } “,
“schema”: [
{
“type”: “hidden”,
“settings”: [
{
“type”: “graphQl”,
“id”: “graphQueries”,
“typeMeta”: {
“mappings”: {
“productId”: {
“reads”: “productId”,
“type”: “Int!”
}
}
}
}
]
},
{
“type”: “tab”,
“label”: “Content”,
“sections”: [
{
“label”: “Product”,
“settings”: [
{
“type”: “productId”,
“label”: “Product”,
“id”: “productId”,
“default”: “”,
“typeMeta”: {
“placeholder”: “Search by name or SKU”
}
}
]
}
]
}],
“template”: “<div style=\”text-align:center\”>\n<h1>{{_.data.site.product.name}}</h1>\n<div>\n<img src=\”{{_.data.site.product.defaultImage.url}}\”>\n</div>\n<div>\n<p>${{_.data.site.product.prices.price.value}}</p>\n</div>\n</div>”
}
3. Widgets applications for the BigCommerce Marketplace.
To create a widget that merchants can discover in the BigCommerce Marketplace, you have to create a Single-Click Application. In our Theme Docs under the Page Builder section, there is documentation on “Third-Party Widgets”. You can use this information to inform your build process in addition to the information in this blog post.
You may be asking yourself — why should I sell my custom Widget in the Marketplace? Well, there are a few reasons:
- You have the ability to access more data through OAuth scopes.
- You can architect solutions that utilize both the Page Builder frontend and your own backend services.
- You can give the user configuration options for styling and management of the widget.
- You can monetize your development efforts.
Building widgets that take advantage of backend services and utilize the versioning flow give your widget applications all the tools they need to create performant and reliable applications that merchants can use and maintain on their own. This is an amazing way to provide merchants with no code or low code options for store functionality.
Tips to Develop Effective Widgets
Determine your development lifecycle
To begin, a developer or team needs to define the functionality and scope of the widget. Second, devs should work on the widget template user interface. This ensures that the user interface contains all the necessary details for the merchant storefront experience before trying to implement settings or data. This confirms that the scope is fully defined and vetted. Third, continue to work on the widget template but from the perspective of the widget schema. The merchant will then have an interface for updating CSS properties like colors, fonts, and borders as well as making sure that any configuration needs are addressed. Fourth, determine what, if any, data is needed to support the widget template. If storefront data is required, then work on the GraphQL queries and verify that the widget template behaves as expected. Save application implementation and integration efforts for the end of the life cycle is an option that gives a team a lot of flexibility when iterating on widgets. You can validate that the user-facing part of the application is working as expected before requiring placement or creating mechanisms that would allow your widget to be downloaded from the BigCommerce Marketplace.
How to work with Widget Templates
The most complex part of developing widgets is architecting your template. In order to validate your development, you will need:
- A REST API client, like Postman.
- A sandbox or trial store’s API scopes for Page Builder access.
- POST the template to the storefront to which you have API token access.
- Access to that storefront to view your widget template in the store’s Page Builder.
Note: You only need to POST the Widget Template to view the Widget in Page Builder. It is not required to POST a Widget or POST a placement, these types of POST’s are optional.
Pro Tip : Before coding an application to create this template or update it, using a tool like Postman to iterate through template creation can save you and your team time. Just be sure to save your UUID to your environment or global variables.
Optimize Widgets for Page Builder
The main property that needs to be included in order to make your widget available to Page Builder is a schema. This schema can be created using the following types:
Tabs and Sections are groups of settings. Tabs require a root-level tab to contain all the visible sections of your widget. Sections contain the settings under an optional label. Settings are the configurable options for your widget. The following diagram is from our docs:
Array schemas are collections of elements that allow you to have multiple settings as each array element can contain its own schema. Array schema types are like an “inception” of settings for widgets. This unlocks the ability to use tabs and sections inside an array type.
Hidden settings are for settings you are making for the user that the user cannot interact with. These settings should be defined first in your widget template schema because they cannot interact with a tab or array. The use case here would be default things that you want the user to see when placing the widget that they override with other settings.
We talked briefly about GraphQL powered widgets above. If you wanted to have users interact with the data that is retrieved from a GraphQL query, you could use the array type and the data filter on things like a product id or other parameter that is passed into the query as variables. This would give users the greatest flexibility when leveraging storefront data.
Convert a Custom Widget to a Widget Application
So, you have a widget already. Congratulations! Now you want to turn that into an application. Where do you begin?
First, create a Single-Click app. You can use this tutorial or the blog post linked above. Second, make a call to GET your widget template by it’s UUID and either apply that widget template to the authenticated storefront or POST a widget to using the widget template UUID to the authenticated storefront. Third, is use the widget update flow to version your widgets and ensure that merchants are alerted to updates in the control panel.
This seems easy when it is one paragraph but there are a lot of steps in between. If you need help, reach out to us in the developer community spaces and we are happy to assist you.
Conclusion
Widgets are a fun way to develop sleek solutions that merchants can actively engage within Page Builder. By creating widgets and widget applications you can unlock some serious functionality that is easily implemented by many merchants. There are so many wants and needs you can fulfill with a little widget-ingenuity.
We can’t wait to see what you all create. Share your development with us at @BigCommerceDevs on Twitter and in our developer community spaces.
Top comments (0)