diff --git a/assets/images/widgets-tutorial-01.gif b/assets/images/widgets-tutorial-01.gif new file mode 100644 index 0000000000..a742929ca0 Binary files /dev/null and b/assets/images/widgets-tutorial-01.gif differ diff --git a/docs/api-docs/storefront/widgets/schema.json b/docs/api-docs/storefront/widgets/schema.json new file mode 100644 index 0000000000..963871a662 --- /dev/null +++ b/docs/api-docs/storefront/widgets/schema.json @@ -0,0 +1,23 @@ +{ + "name": "Header Images", + "template": "{{#each images}}{{/each}}", + "schema": [ + { + "type": "tab", + "label": "Content", + "sections": [ + { + "label": "Product cards", + "settings": [ + { + "type": "boolean", + "label": "Show product name", + "id": "showProductName", + "default": true + } + ] + } + ] + } + ] +} \ No newline at end of file diff --git a/docs/api-docs/storefront/widgets/widgets-tutorial.md b/docs/api-docs/storefront/widgets/widgets-tutorial.md index ec2861e198..a1675d3c94 100644 --- a/docs/api-docs/storefront/widgets/widgets-tutorial.md +++ b/docs/api-docs/storefront/widgets/widgets-tutorial.md @@ -1,63 +1,28 @@ # Widgets Tutorial -
-

On This Page

- -
-In this tutorial, we will cover: -* Creating a Region -* Creating a Widget Template -* Creating a Widget -* Placing the Widget +
-This tutorial assumes knowledge of [Widgets](/api-docs/storefront/widgets/widgets-overview). +### On This Page +- [Create a region](#create-a-region) +- [Verify region creation](#verify-region-creation) +- [Create a widget template](#create-a-widget-template) +- [Create a widget](#create-a-widget) +- [Create a placement](#create-a-placement) +- [Create a user interface](#create-a-user-interface) +- [Resources](#resources) -
-
-
- - -### Cornerstone Theme -> The instructions below use the Cornerstone Theme. Your theme may differ. - -
-
- +In this tutorial, you'll create a [category page widget](https://raw.githubusercontent.com/bigcommerce/dev-docs/master/assets/images/widgets-tutorial-01.gif) (github) that displays a row of three images. -## Prerequisites: -* Stencil Theme. This tutorial uses Cornerstone. -* Scopes -The following Oauth scopes are required: - * [Content](/api-docs/getting-started/authentication#authentication_oauth-scopes) set to Modify -* Image URL. If you don’t have one, there is an example in the tutorial. -* Category Page ID. A [GET Categories](/api-reference/catalog/catalog-api/category/getcategories) request will returns a list of category IDs. +### Prerequisites +* API `access_token` with `content modify` scope. +* Knowledge of [Widgets](https://developer.bigcommerce.com/api-docs/storefront/widgets/widgets-overview). -To follow along we have created a Postman collection. +## Create a region -[![Run in Postman](https://run.pstmn.io/button.svg)](https://app.getpostman.com/run-collection/068117f7cbf510527e49) +In the UI, users drag and drop widgets to *place* them in a region on a page. Theme developers add, remove, and position regions by editing a page's template. Let's add a new region called `category_header_banner` to the category page; we'll place our widget here later. -In this tutorial, we'll create a widget that shows three images with a hover effect. Each image will link out to a different location. - - -![#### Category Page Widget -](//s3.amazonaws.com/user-content.stoplight.io/6012/1551898706416 "#### Category Page Widget -") - -## Adding a Region In `templates/pages/category.html`, add `{{{region name="category_header_banner"}}}` below the page heading. ```html @@ -67,74 +32,86 @@ In `templates/pages/category.html`, add `{{{region name="category_header_banner" {{/unless}} {{{region name="category_header_banner"}}} - -{{{category.description}}} -
``` +If you're using [Stencil CLI](https://developer.bigcommerce.com/stencil-docs/installing-stencil-cli/installing-stencil) and editing theme files locally, push and apply your changes before proceeding to the next step. +
- - -> Regions can only be added to files under pages/templates, including subfolders. + +> ### Note +> * Regions can only be added to templates in [`templates/pages/`](https://developer.bigcommerce.com/stencil-docs/storefront-customization/directory-structure). +> * [Install and Configure Stencil CLI](https://developer.bigcommerce.com/stencil-docs/installing-stencil-cli/installing-stencil) to edit theme files locally. +> * Use [Page Builder](https://support.bigcommerce.com/s/article/Stencil-Themes#edit) to edit theme files via control panel UI.
-To check if the region was added successfully, use [Get Content Regions](/api-reference/storefront/widgets-api/regions/getcontentregions). +## Verify region creation -`GET https://api.bigcommerce.com/stores/vm2iajhsih/v3/content/regions?template_file=pages/category` +To verify region creation, send a `GET` request to [`/v3/content/regions`](https://developer.bigcommerce.com/api-reference/storefront/widgets-api/regions/getcontentregions). + +```http +GET /stores/{{STORE_HASH}}/content/regions?template_file=pages/category +Host: api.bigcommerce.com +X-Auth-Token: {{ACCESS_TOKEN}} +X-Auth-Client: {{CLIENT_ID}} +Accept: application/json +``` - +[![Open in Request Runner](https://storage.googleapis.com/bigcommerce-production-dev-center/images/Open-Request-Runner.svg)](https://developer.bigcommerce.com/api-reference/storefront/widgets-api/regions/getcontentregions#requestrunner) + +Then, look for the region's name in the response. ```json { -"data": [ + "data": [ { - "name": "header_bottom" + "name": "header_bottom" }, { - "name": "category_header_banner" + "name": "category_header_banner" } -], -"meta": {} + ], + "meta": {} } ``` -## Creating a Widget Template +
+
+
-Widget Templates are resuable pieces of HTML. In this tutorial we are creating a header image. You can set `image_source` property using Handlebars so the header image can be changed every time you reuse a template. You can also take advantage of the conditional logic within a template using `#each images`. Instead of creating a template with three lines of code for each image, you can loop through each image using one line of code. +>### Note +> * Use the `?template_file=pages/category` query string parameter to get the category template's regions. -* `name` -- Name of the widget template (required) -* `template` -- HTML to create the widget template (required) +
+
+
-The response returns the UUID for the widget template. Make note of it for when we create the widget later. +## Create a widget template -**Example Create Widget Template** -`POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/content/widget-templates` +Widgets derive from widget templates. Before we create our widget, we must first create it's template. To do so, send a `POST` request to [`/v3/content/widget-templates`](https://developer.bigcommerce.com/api-reference/storefront/widgets-api/widget-template/createwidgettemplate). + +```http +POST /stores/{{store_hash}}/v3/content/widget-templates +Host: api.bigcommerce.com +X-Auth-Token: {{ACCESS_TOKEN}} +X-Auth-Client: {{CLIENT_ID}} +Content-Type: application/json +Accept: application/json -```json { "name": "Header Images", "template": "{{#each images}}{{/each}}" } ``` - +[![Open in Request Runner](https://storage.googleapis.com/bigcommerce-production-dev-center/images/Open-Request-Runner.svg)](LINK_TO_OPERATION#requestrunner) -**Example Response Create Widget Template** -`POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/content/widget-templates` +**Response:** ```json { @@ -151,30 +128,31 @@ lineNumbers: true } ``` -## Creating a Widget - -Next, we will use the widget template to add the links and images. For more examples, see [Code Samples](/api-docs/storefront/widgets/widgets-code-samples). +
+
+
-* `name` -- This should be a short and descriptive name for the widget (required) -* `description` -- A longer explanation of the widget, if needed -* `widget_configuration` -- Based on the original `widget_template` configuration and can vary by the widget created - * `image_source` -- Since this is the Handlebar placeholder, it requires an image value. -* `widget_template_uuid` -- UUID from the Widget Template response +> ### Note +> * The response contains the `uuid` of the widget template. Make note of it; its used to create the widget later. +> * Widget templates accept [Handlebars expressions](https://developer.bigcommerce.com/stencil-docs/reference-docs/handlebars-helpers-reference). +> * Multiple widgets can use the same widget template. -For widget_configuration `images` is the top level array, with `image_url` and `image_source` for each object. There are three images in this example since the width of each was set to 33.3%. +
+
+
-In the response the Widget UUID is returned. Make note of it for use later when creating the Placement. +## Create a widget - +Now, use the widget template to create the widget. To do so, send a `POST` request to [`/v3/content/widgets`](https://developer.bigcommerce.com/api-reference/storefront/widgets-api/widget/createwidget). -**Example Create a Widget** -**`/POST`** `https://api.bigcommerce.com/stores/{{store_hash}}/v3/content/widgets` +```http +POST /stores/{{STORE_HASH}}/v3/endpoint +Host: api.bigcommerce.com +X-Auth-Token: {{ACCESS_TOKEN}} +X-Auth-Client: {{CLIENT_ID}} +Content-Type: application/json +Accept: application/json -```json { "name": "Header Images", "template": "{{#each images}}{{/each}}", @@ -195,66 +173,39 @@ lineNumbers: true } ``` -**Create A Widget Response** +[![Open in Request Runner](https://storage.googleapis.com/bigcommerce-production-dev-center/images/Open-Request-Runner.svg)](https://developer.bigcommerce.com/api-reference/store-management/widgets/widget/createwidget#requestrunner) -```json -{ - "data": { - "uuid": "a8940709-5655-4401-a341-62c44e3180b2", - "name": "Header Images", - "widget_configuration": { - "images": [ - { - "image_url": "{where-the-image-should-link-to}", - "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/91/309/thekinfolktablecover_1024x1024__80715.1456436719.jpg?c=2&imbypass=on" - }, - { - "image_url": "{where-the-image-should-link-to}", - "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on" - }, - { - "image_url": "{where-the-image-should-link-to}", - "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on" - } - ], - "_": { - "id": "a8940709-5655-4401-a341-62c44e3180b2" - } - }, - "widget_template": { - "uuid": "3a1b0044-c9b3-47d3-9929-01ab0c20243b", - "name": "Header Images", - "schema": [], - "template": "{{#each images}}{{/each}}", - "date_created": "2019-02-25T18:35:04.904Z", - "date_modified": "2019-02-25T18:35:04.904Z", - "kind": "custom" - }, - "date_created": "2019-02-25T18:36:45.238Z", - "date_modified": "2019-02-25T18:36:45.238Z", - "description": "" - }, - "meta": {} -} -``` +| Property | Description | +|---|---| +| `name` | short widget name displayed to user (required) | +| `description` | long description displayed to user (optional) | +| `template` | widget's template; overrides `widget_template_uuid` template | +| `widget_configuration` | data for Handlebars context | +| `widget_template_uuid` | default template `uuid` | -## Creating the Placement +
+
+
-Placement defines the page and region where the widget should appear. Remember that [Placements](/api-docs/storefront/widgets/widgets-overview#widgets_placements) can either lead to a Layout or they can be used on their own. In this walkthrough we will use Layouts. +> ### Note +> * Note the widget's UUID in the response for creating the placement in the next step. -* `widget_uuid` -- UUID of the Widget -* `entity_id` -- The page, category, brand or product ID where the widget should appear -* `sort_order` -- If there is more than one Widget on a page, use the sort order to control the order they are displayed. -* `region` -- Region where the template will show. It should match the template file. -* `template_file` -- Template file the region was added to -* `status` -- Whether the widget is active or inactive +
+
+
-If you want to see the results of the widget without a layout, use the placement without the layout code sample below. If you would like to learn more about layouts, use the Create Placement code sample below. +## Create a placement -**Example Create a Placement** -`/POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/content/placements` +In the UI, users drag and drop widgets to *place* them in a region on a page. Here, we'll use the API to programmatically place our widget. To do so, send a `POST` request to [`/v3/content/placements`](https://developer.bigcommerce.com/api-reference/storefront/widgets-api/placement/createplacement). + +```http +POST /stores/{{store_hash}}/v3/content/placements +Host: api.bigcommerce.com +X-Auth-Token: {{ACCESS_TOKEN}} +X-Auth-Client: {{CLIENT_ID}} +Content-Type: application/json +Accept: application/json -```json { "widget_uuid": "{your-widget-uuid}", "entity_id": "{your-category-id}", @@ -265,87 +216,57 @@ If you want to see the results of the widget without a layout, use the placement } ``` - +[![Open in Request Runner](https://storage.googleapis.com/bigcommerce-production-dev-center/images/Open-Request-Runner.svg)](LINK_TO_OPERATION#requestrunner) + +| Property | Description | +|---|---| +| `widget_uuid` | UUID of the widget | +| `entity_id` | page, category, brand, or product ID | +| `sort_order` | widget sort order | +| `region` | region the template will show | +| `template_file` | template file region added to | +| `status` | active or inactive | -**Example Response Create Placement** -`/POST https://api.bigcommerce.com/stores/{{store_hash}}/v3/content/placements` +## Create a user interface + +In the control panel, users use [Page Builder](https://developer.bigcommerce.com/stencil-docs/page-builder/page-builder-overview) to move and configure widgets. You can optionally add custom configuration settings to your a widget's [Page Builder UI](https://developer.bigcommerce.com/stencil-docs/page-builder/page-builder-overview) by including the `schema` property in the create [widget template request](#create-a-widget-template). ```json { - "data": { - "uuid": "bb34b23b-0d4b-4b9b-9e24-c8b0dcfd5e08", - "template_file": "pages/category", - "region": "", - "sort_order": 0, - "entity_id": "21", - "status": "active", - "widget": { - "uuid": "a8940709-5655-4401-a341-62c44e3180b2", - "name": "Header Images", - "widget_configuration": { - "images": [ - { - "image_url": "{where-the-image-should-link-to}", - "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/91/309/thekinfolktablecover_1024x1024__80715.1456436719.jpg?c=2&imbypass=on" - }, - { - "image_url": "{where-the-image-should-link-to}", - "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/1280x1280/products/109/361/kinfolkessentialissue_1024x1024__22507.1456436715.jpg?c=2&imbypass=on" - }, - { - "image_url": "{where-the-image-should-link-to}", - "image_source": "https://cdn11.bigcommerce.com/s-n0i50vy/images/stencil/500x659/products/85/282/livingwithplants_grande__26452.1456436666.jpg?c=2&imbypass=on" - } - ], - "_": { - "id": "a8940709-5655-4401-a341-62c44e3180b2" - } - }, - "widget_template": { - "uuid": "3a1b0044-c9b3-47d3-9929-01ab0c20243b", - "name": "Header Images", - "schema": [], - "template": "{{#each images}}{{/each}}", - "date_created": "2019-02-25T18:35:04.904Z", - "date_modified": "2019-02-25T18:35:04.904Z", - "kind": "custom" - }, - "date_created": "2019-02-25T18:36:45.238Z", - "date_modified": "2019-02-25T18:36:45.238Z", - "description": "" - }, - "date_created": "2019-02-25T18:37:10.658Z", - "date_modified": "2019-02-25T18:37:10.658Z" - }, - "meta": {} + "name": "Header Images", + "template": "{{#each images}}{{/each}}", + "schema": [ + { + "type": "tab", + "label": "Content", + "sections": [ + { + "label": "Product cards", + "settings": [ + { + "type": "boolean", + "label": "Show product name", + "id": "showProductName", + "default": true + } + ] + } + ] + } + ] } - ``` -## Reusing the widget template - -Now that you have created the widget template, you can reuse it on different pages. - -To reuse the widget template: -1. Choose where to display the widget by either creating a [Region](/api-reference/storefront/widgets-api/regions/getcontentregions) or use and existing one -2. Decide if the Widget should appear on all pages or if it should use an `entity_id` -3. Get the [Widget Template ID](/api-reference/storefront/widgets-api/widget-template/getwidgettemplates) -4. [Create the Widget](/api-reference/storefront/widgets-api/widget/createwidget) with the Widget Template ID -5. [Create a Placement](/api-reference/storefront/widgets-api/placement/createplacement) using the Widget - -## Creating user interfaces for Widgets -Customers use the drag-and-drop editor, [Page Builder](https://developer.bigcommerce.com/stencil-docs/page-builder/page-builder-overview), to rearrange and edit BigCommerce's built-in widgets. You can create a user interface for custom widget settings using pre-defined schema. For more information, see [Page Builder Overview](https://developer.bigcommerce.com/stencil-docs/page-builder/page-builder-overview). +[![Open in Request Runner](https://storage.googleapis.com/bigcommerce-production-dev-center/images/Open-Request-Runner.svg)](https://developer.bigcommerce.com/api-reference/storefront/widgets-api/widget-template/createwidgettemplate#requestrunner) +For more information, see [Page Builder Overview](https://developer.bigcommerce.com/stencil-docs/page-builder/page-builder-overview). ## Resources -### Related Endpoints +### Related endpoints * [Widgets API](/api-reference/storefront/widgets-api) -### Related Articles +### Related articles * [Widgets Overview](/api-docs/storefront/widgets/widgets-overview) * [Wigets Code Samples](/api-docs/storefront/widgets/widgets-code-samples) +* [Page Builder Overview](https://developer.bigcommerce.com/stencil-docs/page-builder/page-builder-overview) \ No newline at end of file