Placements
Placements determine the Region where the widget is placed and in what order.
Currently, placements can exist on the following pages:
It is also possible to place widgets on the following custom templates, where <filename> is the name of the custom template file:
- To display a widget on the storefront, you must create a placement.
- A region can contain multiple placements with widgets.
Placements sort_order
When creating a placement with a widget, the widget content takes the full region width. The placement’s sort_order property controls the display order of the widget. You would stack any additional widgets in the same region above or below based on each placement’s sort_order property.
If you are creating marketplace applications that create placements directly, you do not need to use the sort_order property.
entity_id
When creating a placement, there is an option to provide an entity_id. The entity_id is the identifier for a specific product, brand, category, or page. For example, if a widget needs to be on all product pages, leave entity_id blank. If the widget should only appear on a certain product page, assign the product ID to entity_id.
You can use entity_id with the following page types:
- pages/brand
- pages/category
- pages/page
- pages/product
Create a Widget Placement with Region
Placements tell the Widgets API which page and region a widget should be assigned to. A placement can also define a sort order, which determines the order to display multiple widgets within a single region.
Below, the region and sort order have a value, so the widget will appear on the home page.
Create a Widget Placement without a Region
You may wish to determine a widget’s positioning not just by region, but also in relation to other widgets. In that case, you can create a widget placement without specifying a region and then include the widget placement within a layout.
Leaving the region and sort order off of the request will return just the placement_id in the response, allowing for the widget to be rendered using Layouts.
Widgets on the Storefront
Regions are output on the storefront with a data attribute, like this:
When widget placements are rendered within a region, the template contents are wrapped in a container with data attributes containing the widget’s ID and placement’s ID, like this:
A region can contain multiple widget placements.
Placements determine the region where you place widgets and in what order. There is a limit of 75 placements per template file and 10,000 total placements per store.
Create a Placement
POST /v3/content/placements
Creates a Placement.
Get Placements
GET /v3/content/placements
Returns a list of Placements. 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.
-
template_file (string) - The template file.
example: pages/home. -
widget_ uuid (string) - The identifier for a specific widget.
-
widget_template_uuid (string) - The identifier for a specific widget template.
Get a Single Placement
GET /v3/content/placements/{uuid}
Returns a single Placement.
Request Parameters:
- uuid (string) - The identifier for a specific placement.
Update Placements
PUT /v3/content/placements/{uuid}
Updates a Placement.
Delete a placement
DELETE /v3/content/placements/{uuid}
Deletes a Placement.
