Widgets

Widgets are units of content placed on specific pages in a Stencil theme. Widgets consist of a widget configuration and a widget template UUID and render as part of the storefront’s HTML.

Widget Configuration

A widget configuration is the JSON payload that defines the content you can render with a given widget template. In the previous list example, the widget template loops over an array of list items using {{#each}}.

In the following example, we define the list_items array and supply values for the color and text of each list item. Since you create the template separately from the configuration, you can use the same template UUID multiple times.

{
	"list_items": [{
		"color": "orange",
		"text": "Item One"
   },
   {
		"color": "blue",
		"text": "Item Two"
   }
  ]
}

{
  "slides": [
    {"image":"http://imageurl.com/nh35jn/test.png"},
    {"image":"http://imageurl.com/fdhdfh/test2.png"}
  ]
}

Reusing Widget Configuration

You set the widget configuration name when creating the widget template. When reusing the widget configuration, the objects array must use the name established during the initial configuration. Otherwise, you will create the widget on the frontend, but there will be no data and nothing displayed.

When reusing the widget configuration from our list example, you must call the items array list_items, because you defined the list_items array when creating the widget template.

{
  "name": "List",
  "widget_configuration": {
    "list_items_two": [
      {
        "color": "orange",
        "text": "Fifth item"
      },
      {
        "color": "blue",
        "text": "Sixth item"
      }
    ]
  },
  "widget_template_uuid": "7bfb9a46-75cc-45bc-bf39-a6a43b77111f"
}

The example above uses list_items_two in the configuration, which is not the same as list_items. If you have already established list_items during the initial configuration, it must be set as list_items when you use it again.

{
  "name": "List",
  "widget_configuration": {
    "list_items": [
      {
        "color": "orange",
        "text": "Fifth item"
      },
      {
        "color": "blue",
        "text": "Sixth item"
      }
    ]
  },
  "widget_template_uuid": "7bfb9a46-75cc-45bc-bf39-a6a43b77111f"
}

Create a Widget

POST /v3/content/widgets

Creates a Widget.

Required Fields

• name
• widget_template_uuid

Get All Widgets

GET /v3/content/widgets

Returns a list of Widgets. Optional parameters can be passed in.

Request Parameters:

• page - (integer) Specifies the page number in a limited (paginated) list of products.
• limit - (integer) Controls the number of items per page in a limited (paginated) list of products.
• widget_template_kind (string) - The kind of widget template.
• widget_template_uuid (string) - The identifier for a specific widget template.
• name (string) - The URL encoded name of the widget.

Use name:in to pass in comma-separated list of widget names.

Ex: /widgets?name:in=test-widget-name,header%20images

Get a Widget

GET /v3/content/widgets/{uuid}

Returns a single Widget.

Request Parameters:

• uuid (string) - The identifier for a specific widget.

Update a Widget

PUT /v3/content/widgets/{uuid}

Updates a Widget.

Delete a Widget

DELETE/v3/content/widgets/{uuid}

Deletes a Widget.