CMS Element (for Shopping Experiences)
In order for Shopware6 to make Boxalino API requests from the context of CMS pages, the Boxalino API Narrative CMS element must be used.
The CMS element is part of the Framework Layer repository.
The CMS element is part of the Commerce Block category.
Once added on a Layout, the CMS element must be configured
Configurations
Property | Required | Description | |
---|---|---|---|
1 | Widget | yes | The widget property on the API Request Schema
|
2 | Sidebar Layout | no | If set to yes - the API Request will have a context parameter position:sidebar
|
3 | Add Store Filterable Properties to API Request | no | When active, will add all the Properties defined in your e-shop that have the filterable flag active to the API request. |
4 | Nr of products returned | yes | The hitCount property on the API Request Schema Narrative API - Technical Reference | Base parameters |
5 | Group by (field name) | yes (default provided) | The groupBy property on the API Request Schema Narrative API - Technical Reference | Typical parameters |
6 | Apply Request Parameters | yes | If set to yes - the API request will read the page URL and set the facets
|
7 | Returned Fields | no (default provided) | The returnFields property on the API Request Schema Narrative API - Technical Reference | Typical parameters
|
8 | Filters | no | default filters (per integration context) are status, visibility and the Category Filter configuration
|
9 | Category Filter | no (default provided) | Setting a category ID as a filter
|
10 | Category List for Filters | no | When the “Category Filter” option is set to “Custom category IDs”, add the category IDs (HEX) divided by a comma (,) |
11 | Facets | no | List of custom selected facet filters on the CMS element (ex: products_brand=Killing Inc|Mann Inc,products_size=37 ):
|
12 | Sort | no | The sort option key (for pre-selected sorting in the request)
|
13 | Context Parameters | no | Available from tag 2.4.1 List of custom parameters to be added to the API Request properties (key-value) (ex: campaign=christmas-bestsellers):
|
Practices
For a transparent integration and a consistency across your project, the following practices are recommended:
Creating a Boxalino Navigation Sidebar Landing Page (in Shopping Experiences Layouts)
to be used for navigation-like widgets, as a layout for Category pages (with Navigation CMS element)
to be used for other pages with facets, on which the navigation CMS element is also desired
you can also add EMPTY sections above and bellow (for content top and bottom)
Creating a Boxalino Full Layout Landing Page (in Shopping Experiences Layout)
to be used for navigation-like widget, as a layout for Category pages (without Navigation CMS element)
to be used for other pages, where the Navigation CMS element is not needed
Creating a Boxalino Sidebar Layout Landing Page (in Shopping Experiences)
to be used for sidebar layout contexts
the sidebar content is to be defined in the narrative structure in Boxalino Intelligence Admin
The above elements are contextual.
When used as Layout Assignment in a Category or CMS page, the widget and the other properties can be edited.
How the CMS request is done
This is a topic useful for integrators in order to understand how the CMS elements can be extended or rewritten.
The following elements have to be reviewed:
ApiCmsLoaderSubscriber
reads the CMS configurations (as set in the CMS element)
makes the API request (via the ApiCmsLoader)
loads the data in the block/section/slot
updates the sidebar section with the left content
it is used only when integrated in the project`s Integration Layer https://github.com/boxalino/rtux-integration-shopware/blob/master/src/Resources/config/services/api/cms.xml#L25
it is a kernel event subscriber for the
CmsPageLoadedEvent
CmsContext
per any integration requirement, the context is explicit defined in the Integration Layer
used to define the default return fields for the CMS context request
it uses the Framework Layer CmsContextAbstract class as base
https://github.com/boxalino/rtux-shopware/blob/master/src/Framework/Request/CmsContextAbstract.php
function addContextParameters(RequestInterface $request) : void
used to add new properties (key-value) to the Api Request Schema Narrative API - Technical Reference | Typical parametersfunction getContextNavigationId(RequestInterface $request): array
used to set the category ID filter (from the options defined in the CMS configurations view)function addFilters(RequestInterface $request) : void
adds the default filters (visibility, active, category ID) and the ones defined in the CMS configurations for filtersfunction addFacets(RequestInterface $request): ListingContextAbstract
: if Apply Request Parameters : yes - parses the URL for the facet filters; else - will set the facets values defined in the CMS configuration
ApiCmsLoader
https://github.com/boxalino/rtux-shopware/blob/master/src/Framework/Content/Page/ApiCmsLoader.php
based on the Shopware6 concept of PageContentLoader
it will return a Shopware6 page https://github.com/boxalino/rtux-shopware/blob/master/src/Framework/Content/Listing/ApiCmsModel.php
the Shopware6 page is declared as a public service https://github.com/boxalino/rtux-shopware/blob/master/src/Resources/config/services/api.xml#L22
it loads the Shopware6 Category model/data which can be used in templates
it is used only when integrated in the project`s Integration Layer https://github.com/boxalino/rtux-integration-shopware/blob/master/src/Resources/config/services/api/cms.xml#L18