Navigation panels¶
The predefined navigation panels all display products and categories based on the parameters and incoming arguments that are sent with a panel query.
For mandatory arguments for all panels including request URL format, see Panel query.
Category breadcrumb panel¶
The result of a query to this panel is a list of all parent categories of the category in the selected_category argument. The result is returned with the topmost category under the root first and ending with the category in the selected_category argument.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
presentation_attributes Guide | string | A comma-separated list of the attributes in the category data to present. Default presentation attributes are used if omitted in the query. | image_url,link |
selected_category Guide | category | The tree and category key of the selected category on the format: <tree name>:'<category key>'. Returns an empty result if omitted in the query. | category:'Ladies' |
Example panel content¶
The following example will use the panel argument selected_category=category_ids:'home_kitchen_cookware' to return the category breadcrumb.
JSON
{
"categoryBreadcrumb": [
{
"name": "category-breadcrumb",
"ticket": "Oy9jYXRlZ29yeS1icmVhZGNydW1iOyM7IzsjOyM7IzsjOyM7",
"path": "/category-breadcrumb",
"description": "Displays a breadcrumb, i.e. a list of parent categories, for the given category.",
"displayName": "Category Breadcrumb",
"attributes": {},
"resultType": "categoryList",
"categoryList": [
{
"tree": "category_ids",
"key": "home",
"parentKey": "root",
"displayName": "Home",
"attributes": {}
},
{
"tree": "category_ids",
"key": "home_kitchen",
"parentKey": "home",
"displayName": "Kitchen",
"attributes": {}
},
{
"tree": "category_ids",
"key": "home_kitchen_cookware",
"parentKey": "home_kitchen",
"displayName": "Cookware",
"attributes": {}
}
]
}
]
}
Category information panel¶
The result of a query to this panel is a list of categories specified in the categories argument. The sort order of the list is the same as specified in the categories argument.
Categories in the result can be from different category trees. Categories included in the categories argument that are not found in the data set will not be listed.
Sub-categories of a category in the categories argument will not be returned in the result. To return sub-categories the Category overview panel may be used.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
categories Guide | string | A comma-separated list of tree and category key on the form {tree 1}:'{category key 1}',{tree 2}:'{category key 2}',.... Will return an empty result if omitted in the query. | category_uk:'C1',category_se'C1' |
presentation_attributes Guide | string | A comma-separated list of the attributes in the category data to present. Default presentation attributes are used if omitted in the query. | link |
Example panel content¶
The following example will use the panel argument categories=category_ids:'home',brand_id:'2' to return category information.
JSON
{
"categoryInformation": [
{
"name": "category-information",
"ticket": "Oy9jYXRlZ29yeS1pbmZvcm1hdGlvbjsjOyM7IzsjOyM7IzsjOw",
"path": "/category-information",
"description": "Displays information for one or more specified categories. Subcategories are not included in the\n result.",
"displayName": "Category Information",
"attributes": {},
"resultType": "categoryList",
"categoryList": [
{
"tree": "category_ids",
"key": "home",
"parentKey": "root",
"displayName": "Home",
"attributes": {}
},
{
"tree": "brand_id",
"key": "2",
"parentKey": "root",
"displayName": "Rau",
"attributes": {}
}
]
}
]
}
Category navigation panel¶
The result of a query to this panel is a category navigation tree that is expanded according to the selected_category argument. The argument root_category must be included in a query to this panel.
The result tree is represented as a category object for the given root category with sub-categories. The category object follows the following rules:
- The
selected_categoryand its parent categories (up to, and including, theroot_category) will be selected. - All selected categories will have all of their sub-categories included in the result.
- Categories that are not selected will not have any sub-categories in the result.
Each category in the result has an aggregated product count of all its own products including all the products in its sub-categories. The set of products and variants that should be counted can be limited with the use of arguments for filter, facets, and search_phrase.
Categories with product count of 0 are included in the result.
The argument root_category must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
category_filter | filter | An expression defining the categories to include. The categories from the root_category and selected_category argument are always included. If the filter excludes a category, its sub-categories are also excluded. Defaults to UNIVERSE if omitted in the query. | archive:true |
facets Guide | facets | A pipe-separated list of selected facet values. Used to limit the set of products and variants to use for the product count. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression defining the product and variant set to consider. Used to limit the set of products and variants to use for the product count. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' |
include_empty_categories | boolean | A boolean that can be set to false to remove all categories with a product count of zero. The filter argument limits the set of products and variants to use for the product count. Defaults to true if omitted in the query. | false |
locale Guide | string | The locale of the sorting when the sorting is made by display_name or category_key. Sorting will be made in ASCII order if omitted in the query. | sv-SE |
presentation_attributes Guide | string | A comma-separated list of the attributes in the category data to present. Default presentation attributes are used if omitted in the query. | image_url,link |
root_category Guide | category | A tree and category key on the format: <tree>:'<category key>'. This category will be the root of the category tree in the result. Required argument. | category:'Ladies' |
search_attributes Guide | string | A comma-separated list of which configured search attributes to search for the search phrase in. A typed format is also available to enable searching in category attributes. Used to limit the set of products and variants to use for the product count. Throws an exception if search_phrase was provided but search_attributes is omitted in the query. | product_name,brand |
search_phrase | string | A search phrase to search for in the category data. Search will only be performed in the listed search_attributes. Used to limit the set of products and variants to use for the product count. Selection will not be based on a search if omitted in the query. | red dress |
selected_category Guide | category | The tree and category key of the selected category on the format: <tree name>:'<category key>'. Must be a descendant to the root_category or the root_category itself. Defaults to the value of root_category if omitted in the query. | category:'Ladies' |
sort_by | category_order | Specifies in which order the sub-categories to each category should be sorted. Secondary orders can be given using a comma-separated list. Can be one or more of relevance, product_count, display_name, category_key, or any category sort attribute. Relevance currently ranks categories according to the number of sold products in descending order. Defaults to relevance if omitted in the query. | relevance,display_name |
Example panel content¶
The following example will use the panel arguments sort_by=relevance, root_category=category_ids:'root', and selected_category=category_ids:'home' to return category navigation.
JSON
{
"categoryNavigation": [
{
"name": "category-navigation",
"ticket": "Oy9jYXRlZ29yeS1uYXZpZ2F0aW9uOyM7IzsjOyM7IzsjOyM7",
"path": "/category-navigation",
"description": "Displays a category navigation tree with product counts for each category. The counts and ranking\n can be adapted to a search result or product listing.",
"displayName": "Category Navigation",
"attributes": {},
"resultType": "categoryTree",
"categoryTree": {
"subcategories": [
{
"subcategories": [],
"key": "ladies",
"displayName": "Ladies",
"productCount": 7954,
"attributes": {}
},
{
"subcategories": [],
"key": "men",
"displayName": "Men",
"productCount": 1797,
"attributes": {}
},
{
"subcategories": [],
"key": "kids",
"displayName": "Kids",
"productCount": 2911,
"attributes": {}
},
{
"subcategories": [
{
"subcategories": [],
"key": "home_livingroom",
"displayName": "Livingroom",
"productCount": 203,
"attributes": {}
},
{
"subcategories": [],
"key": "home_decorations",
"displayName": "Decorations",
"productCount": 182,
"attributes": {}
},
{
"subcategories": [],
"key": "home_bedroom",
"displayName": "Bedroom",
"productCount": 171,
"attributes": {}
},
{
"subcategories": [],
"key": "home_kitchen",
"displayName": "Kitchen",
"productCount": 166,
"attributes": {}
},
{
"subcategories": [],
"key": "home_bedlinen",
"displayName": "Bedlinen",
"productCount": 137,
"attributes": {}
},
{
"subcategories": [],
"key": "home_cushions",
"displayName": "Cushions",
"productCount": 106,
"attributes": {}
},
{
"subcategories": [],
"key": "home_kidsroom",
"displayName": "Kidsroom",
"productCount": 103,
"attributes": {}
},
{
"subcategories": [],
"key": "home_porcelain",
"displayName": "Porcelain",
"productCount": 64,
"attributes": {}
},
{
"subcategories": [],
"key": "home_towels",
"displayName": "Towels",
"productCount": 57,
"attributes": {}
},
{
"subcategories": [],
"key": "home_pots_vases",
"displayName": "Vases",
"productCount": 55,
"attributes": {}
},
{
"subcategories": [],
"key": "home_candlescandleholders",
"displayName": "Candles & Candleholders",
"productCount": 49,
"attributes": {}
},
{
"subcategories": [],
"key": "home_bathroom",
"displayName": "Bathroom",
"productCount": 46,
"attributes": {}
},
{
"subcategories": [],
"key": "home_glasswear",
"displayName": "Glasswear",
"productCount": 46,
"attributes": {}
},
{
"subcategories": [],
"key": "home_storage",
"displayName": "Storage",
"productCount": 43,
"attributes": {}
},
{
"subcategories": [],
"key": "home_carpets",
"displayName": "Carpets",
"productCount": 28,
"attributes": {}
},
{
"subcategories": [],
"key": "home_blankets",
"displayName": "Blankets",
"productCount": 16,
"attributes": {}
},
{
"subcategories": [],
"key": "home_tablecloth",
"displayName": "Table Cloth",
"productCount": 15,
"attributes": {}
},
{
"subcategories": [],
"key": "home_outdoor",
"displayName": "Outdoor",
"productCount": 14,
"attributes": {}
},
{
"subcategories": [],
"key": "home_christmasdecorations",
"displayName": "Christmas Decorations",
"productCount": 13,
"attributes": {}
},
{
"subcategories": [],
"key": "home_bathmats",
"displayName": "Bath Mats",
"productCount": 11,
"attributes": {}
},
{
"subcategories": [],
"key": "home_teatowel",
"displayName": "Tea Towel",
"productCount": 10,
"attributes": {}
},
{
"subcategories": [],
"key": "home_curtains",
"displayName": "Curtains",
"productCount": 7,
"attributes": {}
},
{
"subcategories": [],
"key": "home_showercurtains",
"displayName": "Shower Curtains",
"productCount": 7,
"attributes": {}
},
{
"subcategories": [],
"key": "home_homewear",
"displayName": "Homewear",
"productCount": 6,
"attributes": {}
},
{
"subcategories": [],
"key": "home_placemats",
"displayName": "Placemats",
"productCount": 6,
"attributes": {}
},
{
"subcategories": [],
"key": "home_dressinggown",
"displayName": "Dressing Gown",
"productCount": 5,
"attributes": {}
},
{
"subcategories": [],
"key": "home_napkins",
"displayName": "Napkins",
"productCount": 4,
"attributes": {}
},
{
"subcategories": [],
"key": "home_picnic",
"displayName": "Picnic",
"productCount": 4,
"attributes": {}
},
{
"subcategories": [],
"key": "home_aprons",
"displayName": "Aprons",
"productCount": 2,
"attributes": {}
},
{
"subcategories": [],
"key": "home_tablerunners",
"displayName": "Table Runners",
"productCount": 2,
"attributes": {}
}
],
"selected": true,
"key": "home",
"displayName": "Home",
"productCount": 857,
"attributes": {}
}
],
"selected": true,
"key": "root",
"productCount": 13502,
"attributes": {}
}
}
]
}
Category overview panel¶
The result of a query to this panel is a category tree starting from a given root category. The result tree is represented as a category object for the given root category with sub-categories. The number of levels of sub-categories to be included in the result can be controlled wih the depth argument.
Each category in the result has an aggregated product count of all its own products including all the products in its sub-categories. The set of products and variants that should be counted can be limited with the use of arguments for filter, facets, and search_phrase.
Categories with product count of 0 are included in the result.
The argument root_category must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
category_filter | filter | An expression defining the categories to include. The categories from the root_category and selected_category argument are always included. If the filter excludes a category, its sub-categories are also excluded. Defaults to UNIVERSE if omitted in the query. | archive:true |
depth | int | The number of sub-category levels included in the result. 0 will return only the root category. 1 will return one level of sub-categories, etc. Defaults to -1 (includes the full tree) if omitted in the query. | 2 |
facets Guide | facets | A pipe-separated list of selected facet values. Used to limit the set of products and variants to use for the product count. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression defining the product and variant set to consider. Used to limit the set of products and variants to use for the product count. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' |
include_empty_categories | boolean | A boolean that can be set to false to remove all categories with a product count of zero. The filter argument limits the set of products and variants to use for the product count. Defaults to true if omitted in the query. | false |
locale Guide | string | The locale of the sorting when the sorting is made by display_name or key. Sorting will be made in ASCII order if omitted in the query. | sv-SE |
presentation_attributes Guide | string | A comma-separated list of the attributes in the category data to present. Default presentation attributes are used if omitted in the query. | image_url,link |
root_category Guide | category | A tree and category key on the format: <tree>:'<category key>'. This category will be the root of the category tree in the result. Required argument. | category:'Ladies' |
search_attributes Guide | string | A comma-separated list of which configured search attributes to search for the search phrase in. A typed format is also available to enable searching in category attributes. Used to limit the set of products and variants to use for the product count. Throws an exception if search_phrase was provided but search_attributes is omitted in the query. | product_name,brand |
search_phrase | string | A search phrase to search for in the category data. Search will only be performed in the listed search_attributes. Used to limit the set of products and variants to use for the product count. Selection will not be based on a search if omitted in the query. | red dress |
sort_by | category_order | Specifies in which order the sub-categories to each category should be sorted. Secondary orders can be given using a comma-separated list. Can be one or more of relevance, product_count, display_name, category_key, or any category sort attribute. Relevance currently ranks categories according to the number of sold products in descending order. Defaults to relevance if omitted in the query. | relevance,display_name |
Example panel content¶
The following example will use the panel arguments sort_by=display_name, root_category=category_ids:'home_bathroom', and depth=1 to return a category overview.
JSON
{
"categoryOverview": [
{
"name": "category-overview",
"ticket": "Oy9jYXRlZ29yeS1vdmVydmlldzsjOyM7IzsjOyM7IzsjOw",
"path": "/category-overview",
"description": "Displays a category overview with product counts for each category. The category overview consists\n of a category tree starting at a given root and showing a specified number of levels.",
"displayName": "Category Overview",
"attributes": {},
"resultType": "categoryTree",
"categoryTree": {
"subcategories": [
{
"subcategories": [],
"key": "home_bathroom_accessories",
"displayName": "Accessories",
"productCount": 34,
"attributes": {}
},
{
"subcategories": [],
"key": "home_bathroom_laundrybags",
"displayName": "Laundrybags",
"productCount": 7,
"attributes": {}
}
],
"key": "home_bathroom",
"displayName": "Bathroom",
"productCount": 46,
"attributes": {}
}
}
]
}
Category top sellers panel¶
The result of a query to this panel is a list of categories sorted in descending order by the sales score of the products in each respective category.
The arguments max_categories and root_category must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
category_filter | filter | An expression defining the categories to include. Defaults to UNIVERSE if omitted in the query, which means include all categories. | archive:true |
depth | int | The level down from the root_category to include nodes from. If omitted, all leaf nodes (e.g. nodes without a child) below the root_category are returned. | 2 |
max_categories | int | The maximum number of categories that will be returned. The following bounds apply: 1 ≤ max_categories ≤ 10 000. Required argument. | 10 |
presentation_attributes Guide | string | A comma-separated list of the attributes in the category data to present. Default presentation attributes are used if omitted in the query. | image_url,link |
root_category Guide | category | A tree and category key on the format: <tree>:'<category key>'. This category specifies where the results will be taken from. Required argument. | category:'Ladies' |
Example depth usage¶
The following example illustrates what categories are returned from the root_category, here root, with different depth arguments.
| Depth | Result |
|---|---|
| Omitted | C3, C5, C6 |
1 | C1, C2, C3 |
2 | C4, C5 |
Example panel content¶
The following example will use the panel arguments root_category=category_ids:'home', max_categories=3, and depth=1 to return the top selling categories.
JSON
{
"categoryTopSellers": [
{
"name": "category-top-sellers",
"ticket": "Oy9jYXRlZ29yeS10b3Atc2VsbGVyczsjOyM7IzsjOyM7IzsjOw",
"path": "/category-top-sellers",
"description": "Lists the best selling categories.",
"displayName": "Category Top Sellers",
"attributes": {},
"resultType": "categoryList",
"categoryList": [
{
"tree": "category_ids",
"key": "home_towels",
"ticket": "Oy9jYXRlZ29yeS10b3Atc2VsbGVyczsjO2NhdGVnb3J5O2NhdGVnb3J5X2lkcztob21lX3Rvd2VsczsjOyM7Izs",
"parentKey": "home",
"displayName": "Towels",
"attributes": {}
},
{
"tree": "category_ids",
"key": "home_teatowel",
"ticket": "Oy9jYXRlZ29yeS10b3Atc2VsbGVyczsjO2NhdGVnb3J5O2NhdGVnb3J5X2lkcztob21lX3RlYXRvd2VsOyM7IzsjOw",
"parentKey": "home",
"displayName": "Tea Towel",
"attributes": {}
},
{
"tree": "category_ids",
"key": "home_tablerunners",
"ticket": "Oy9jYXRlZ29yeS10b3Atc2VsbGVyczsjO2NhdGVnb3J5O2NhdGVnb3J5X2lkcztob21lX3RhYmxlcnVubmVyczsjOyM7Izs",
"parentKey": "home",
"displayName": "Table Runners",
"attributes": {}
}
]
}
]
}
Facets panel¶
The result of a query to this panel is a list of facet results, one for each attribute provided in the facets_attributes argument or less if max_facets are used and/or no facets are found for one or more of the facet attributes. A facet result is either a range or values. Each attribute must be configured before use. For more information see Working with facets.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
facet_attributes | string | A comma-separated list of facet configured filter attributes to retrieve facets from. Will use all available facets in the product set if omitted in the query. | color,size |
facet_order | facet_order | Specifies in which order the facet results should be sorted. The supported values are relevance and facet_attributes. Defaults to facet_attributes if omitted in the query and the facet_attributes argument is provided in the query. Defaults to relevance if omitted in the query and the facet_attributes argument is omitted in the query. | relevance |
facets Guide | facets | A pipe-separated list of selected facet values. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression defining the product and variant set to find facet values in. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' AND price:[200, 300]' |
locale Guide | string | The locale of the sorting when the sorting is made by value. Only relevant if any of the facet_attributes are sorted by a String attribute. Value sorting will be made in ASCII order if omitted in the query. | sv-SE |
max_facets | int | A number specifying how many different facet results that should be returned. A result for every attribute in the facet_attributes argument will be returned if omitted in the query. | 3 |
search_attributes Guide | string | A comma-separated list of which configured search attributes to search for the search phrase in. Used to limit the product and variant set from where values are selected and should be provided if a search_phrase is given. Throws an exception if search_phrase was provided but search_attributes is omitted in the query. | product_name,brand |
search_phrase | string | A search phrase to search for in the product data. Search will only be performed in the listed search_attributes. Used to limit the product and variant set from where values are selected. Value selection will not be based on a search if omitted in the query. | red dress |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. | category:'Ladies' |
Example panel content¶
The following example will use the panel arguments facet_attribute=current_price,general_color to return facets.
JSON
{
"facets": [
{
"name": "facets",
"ticket": "Oy9mYWNldHM7IzsjOyM7IzsjOyM7Izs",
"path": "/facets",
"description": "Lists values for several facet attributes.",
"displayName": "Facets",
"attributes": {},
"resultType": "facetList",
"facetList": [
{
"attribute": "current_price",
"isRange": true,
"range": {
"min": "1.99",
"max": "499.0",
"minSelected": "1.99",
"maxSelected": "499.0"
}
},
{
"attribute": "general_color",
"isRange": false,
"values": [
{
"text": "black",
"count": 5006
},
{
"text": "blue",
"count": 4268
},
{
"text": "white",
"count": 3478
},
{
"text": "beige",
"count": 1478
},
{
"text": "gray",
"count": 2256
},
{
"text": "orange",
"count": 882
},
{
"text": "red",
"count": 1345
},
{
"text": "green",
"count": 1606
},
{
"text": "yellow",
"count": 749
},
{
"text": "pink",
"count": 1812
},
{
"text": "gold",
"count": 71
},
{
"text": "turquoise",
"count": 511
},
{
"text": "brown",
"count": 285
},
{
"text": "purple",
"count": 163
},
{
"text": "silver",
"count": 51
}
]
}
]
}
]
}
Product breadcrumb panel¶
The result of a query to this panel is a list of all parent categories of the product in the product_key argument. As a product can be part of more than one category in the same tree, Elevate will personalise the breadcrumb by using session click data to determine what path the visitor has taken. The result is returned with the topmost category under the root first and ending with the category as determined by Elevate.
If no relevant categories have been found in the session click data, the breadcrumb will default to the first category defined in the product attribute during the import of products. This default method enables the setting of main category as a fallback. This is useful when a visitor enters a product page directly from an external site.
The arguments category_tree and product_key must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
category_tree Guide | string | The category tree to show the breadcrumb from. Required argument. | category |
presentation_attributes Guide | string | A comma-separated list of the attributes in the category data to present. Default presentation attributes are used if omitted in the query. | link |
product_key | string | The product to show the breadcrumb for. Required argument. | P1 |
Example panel content¶
The following example will use the panel arguments category_tree=category_ids, and product_key=0633095_en-US to return the product breadcrumb.
JSON
{
"productBreadcrumb": [
{
"name": "product-breadcrumb",
"ticket": "Oy9wcm9kdWN0LWJyZWFkY3J1bWI7IzsjOyM7IzsjOyM7Izs",
"path": "/product-breadcrumb",
"description": "Displays a breadcrumb, i.e. a list of parent categories, for the given product.",
"displayName": "Product Breadcrumb",
"attributes": {},
"resultType": "categoryList",
"categoryList": [
{
"tree": "category_ids",
"key": "home",
"parentKey": "root",
"displayName": "Home",
"attributes": {}
},
{
"tree": "category_ids",
"key": "home_bathmats",
"parentKey": "home",
"displayName": "Bath Mats",
"attributes": {}
}
]
}
]
}
Product count panel¶
The result of a query to this panel is the number of products in a search result given the specified search phrase. Variant matches for a certain product will count as a product match. Even if several variants within a product matches, the product is only counted once.
The result can be filtered to only include particular types of products and variants. A search with the added search_phrase argument will only be performed in the provided search_attributes for the filtered data set.
The result will be approximated if the number of products exceeds 10 000.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
facets Guide | facets | A pipe-separated list of selected facet values. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression defining the product and variant set to find search hits in. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' |
search_attributes Guide | string | A comma-separated list of which configured search attributes to search for the search phrase in. A typed format is also available to enable searching in category attributes. Will return an empty result if search_phrase was provided, but there are no matches within provided search_attributes. | name,brand |
search_phrase | string | The search phrase to search for in the product data. Search will only be performed in the listed search_attributes. Selection and ranking will not be based on search phrase if omitted in the query. | red dress |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. | category:'Ladies' |
Example panel content¶
The following example will use the panel arguments filter=category_ids:'home', search_attributes=product_name, and search_phrase=towel to return search data.
JSON
{
"productCount": [
{
"name": "product-count",
"ticket": "Oy9wcm9kdWN0LWNvdW50OyM7IzsjOyM7IzsjOyM7",
"path": "/product-count",
"description": "Displays the total number of products for a product listing.",
"displayName": "Product Count",
"attributes": {},
"resultType": "count",
"count": 63
}
]
}
Product list panel¶
Risk of incorrect usage
The Product list panel should be used for static product lists, such as start page product listing or category product listing. These product listings are not triggered by an explicit search performed by a visitor.
A static product listing may be related to a search phrase, but if the product listing is triggered by an explicit search performed by a visitor, the Search hits panel must be used.
The result of a query to this panel is list of products with variants. Additional arguments can be supplied to filter and order the result list and more.
The result is a list of product elements, each specifying all presentation attributes and the list rank of that product. Each product contains all its variants that match the filter ranked based on the active exposure strategy as set in the Business app. Active boost or bury may affect the ranking of products and variants in the result. Pinning may affect the returned products in the result.
The arguments window_first and window_last must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
facets Guide | facets | A pipe-separated list of selected facet values. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression defining the product and variant set. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' |
locale Guide | string | The locale of the sorting when the sorting is made by value. Value sorting will be made in Unicode order if omitted in the query. | sv-SE |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Default presentation attributes are used if omitted in the query. | name,brand,image_url |
search_attributes Guide | string | A comma-separated list of which configured search attributes to search for the search phrase in. A typed format is also available to enable searching in category attributes. Returns empty result if search_phrase was provided but search_attributes is omitted in the query. | name,brand |
search_phrase | string | An optional search phrase to search for in the product data. Search will only be performed in the listed search_attributes. Selection and ranking will not be based on search phrase if omitted in the query. | red dress |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. Required argument when using Pinning. | category:'Ladies' |
sort_by Guide | search_order | Specifies in which order the products and its variants should be sorted. Secondary orders can be given using a comma-separated list. Defaults to relevance if omitted in the query. | price asc |
variants_per_product | int | The maximum number of variants per product to include in the result. No maximum limit. | 10 |
window_first | int | The first position in the list to be presented. Products before this position, according to the sorting, are not present in the result. The position of the first product in the list is 1. Required argument. | 1 |
window_last | int | The last position in the list to be presented. Products after this position, according to the sorting, are not present in the result. The following bounds apply: 1 ≤ window_first ≤ window_last ≤ 10 000. Required argument. | 10 |
Example panel content¶
The following example will use the panel arguments search_attributes=product_name, search_phrase=towel, window_first=1, and window_last=3 to return a product list.
JSON
{
"productList": [
{
"name": "product-list",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7IzsjOyM7IzsjOyM7Izs",
"path": "/product-list",
"description": "Displays a list of products and is intended to be used for static searches.",
"displayName": "Product List",
"attributes": {},
"resultType": "products",
"products": [
{
"key": "0519169_en-US",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7Iztwcm9kdWN0X2tleTswNTE5MTY5X2VuLVVTOzA1MTkxNjkwMDFfZW4tVVM7T0JKRUNUSVZFJDtOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0519169001_en-US",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7Iztwcm9kdWN0X2tleTswNTE5MTY5X2VuLVVTOzA1MTkxNjkwMDFfZW4tVVM7T0JKRUNUSVZFJDtOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Beach Towel"
]
}
},
{
"key": "0338175_en-US",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7Iztwcm9kdWN0X2tleTswMzM4MTc1X2VuLVVTOzAzMzgxNzUwMDFfZW4tVVM7T0JKRUNUSVZFJDtOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0338175001_en-US",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7Iztwcm9kdWN0X2tleTswMzM4MTc1X2VuLVVTOzAzMzgxNzUwMDFfZW4tVVM7T0JKRUNUSVZFJDtOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Hand Towel"
]
}
},
{
"key": "0377455_en-US",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7Iztwcm9kdWN0X2tleTswMzc3NDU1X2VuLVVTOzAzNzc0NTUwMDJfZW4tVVM7T0JKRUNUSVZFJDtOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0377455002_en-US",
"ticket": "Oy9wcm9kdWN0LWxpc3Q7Iztwcm9kdWN0X2tleTswMzc3NDU1X2VuLVVTOzAzNzc0NTUwMDJfZW4tVVM7T0JKRUNUSVZFJDtOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Hand Towel with Embroidery"
]
}
}
]
}
]
}
Product list with count zone¶
This panel is a zone containing instances of Product list and Product count panels as sub-panels. Arguments to this zone are a combination of the required arguments for the two sub-panels. The result of a query to this zone is a combination of the panel content that can be retrieved by the two result panels.
The arguments window_first and window_last must be included in a query to this zone.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
facets Guide | facets | A pipe-separated list of selected facet values. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression defining the product and variant set. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' |
locale Guide | string | The locale of the sorting when the sorting is made by value. Value sorting will be made in Unicode order if omitted in the query. | sv-SE |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Default presentation attributes are used if omitted in the query. | name,brand,image_url |
search_attributes Guide | string | A comma-separated list of which configured search attributes to search for the search phrase in. A typed format is also available to enable searching in category attributes. Returns empty result if search_phrase was provided but search_attributes is omitted in the query. | name,brand |
search_phrase | string | An optional search phrase to search for in the product data. Search will only be performed in the listed search_attributes. Selection and ranking will not be based on search phrase if omitted in the query. | red dress |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. Required argument when using Pinning. | category:'Ladies' |
sort_by Guide | search_order | Specifies in which order the products and its variants should be sorted. Secondary orders can be given using a comma-separated list. Defaults to relevance if omitted in the query. | price asc |
variants_per_product | int | The maximum number of variants per product to include in the result. No maximum limit. | 10 |
window_first | int | The first position in the list to be presented. Products before this position, according to the sorting, are not present in the result. The position of the first product in the list is 1. Required argument. | 1 |
window_last | int | The last position in the list to be presented. Products after this position, according to the sorting, are not present in the result. The following bounds apply: 1 ≤ window_first ≤ window_last ≤ 10 000. Required argument. | 10 |
Top searches panel¶
The result of a query to this panel is a list of the most popular search phrases. The result can be filtered to only include search phrases that is associated with particular types of products and variants. Only phrases that has been used in ten sessions or more will be considered.
A search phrase is regarded as used when it has been confirmed a by a visitor. A specific search phrase can only be confirmed once per visitor session. The confirmation is performed when the visitor interacts with a result in the Search hits panel through click, adding to cart, or purchase.
The arguments search_attributes, window_first and window_last must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
facets Guide | facets | A pipe-separated list of selected facet values. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression limiting the considered product and variant set. | color:'red' OR color:'blue' AND in_stock:'true' |
search_attributes Guide | string | A comma-separated list of search attributes. The search_attributes must be consistent with the search_attributes for the Search hits panel which the top searches panel is intended to be used for. A typed format is also available to enable searching in category attributes. Required argument. | name,brand |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. | category:'Ladies' |
window_first | int | The first position in the list to be presented. Products before this position, according to the sorting, are not present in the result. The position of the first product in the list is 1. Required argument. | 1 |
window_last | int | The last position in the list to be presented. Products after this position, according to the sorting, are not present in the result. The following bounds apply: 1 ≤ window_first ≤ window_last ≤ 10 000. Required argument. | 10 |
Example panel content¶
The following example will use the panel arguments filter=category_ids:'root', search_attributes=product_name, window_first=1, and window_last=3 to return top searches.
JSON
{
"topSearches": [
{
"name": "top-searches",
"ticket": "Oy90b3Atc2VhcmNoZXM7IzsjOyM7IzsjOyM7Izs",
"path": "/top-searches",
"description": "Lists the most popular searches.",
"displayName": "Top Searches",
"attributes": {},
"resultType": "phrases",
"phrases": [
{
"text": "shorts"
},
{
"text": "sandals"
},
{
"text": "bikini"
}
]
}
]
}
Top sellers panel¶
The result of a query to this panel is a list of products according to Voyado's own patented Top Seller algorithm (US Patent No. 10 528 577) which intelligently balances trending products with consistent sellers. If variants are used, the products will be ranked by their highest scoring variant. Additional arguments can be supplied to filter the result list and more.
The result is a list of product elements, each specifying all presentation attributes and the list rank of that product. Each product contains all its variants that match the filter ranked by sales.
The arguments window_first and window_last must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
facets Guide | facets | A pipe-separated list of selected facet values. Ignored if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | An expression limiting the considered product and variant set. | color:'red' OR color:'blue' AND in_stock:'true' |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Default presentation attributes are used if omitted in the query. | name,brand |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. | category:'Ladies' |
variants_per_product | int | The maximum number of variants per product to include in the result. No maximum limit . | 10 |
window_first | int | The first position in the list to be presented. Products before this position, according to the sorting, are not present in the result. The position of the first product in the list is 1. Required argument. | 1 |
window_last | int | The last position in the list to be presented. Products after this position, according to the sorting, are not present in the result. The following bounds apply: 1 ≤ window_first ≤ window_last ≤ 10 000. Required argument. | 10 |
Example panel content¶
The following example will use the panel arguments filter=category_ids:'men', window_first=1, and window_last=3 to return top sellers.
JSON
{
"topSellers": [
{
"name": "top-sellers",
"ticket": "Oy90b3Atc2VsbGVyczsjOyM7IzsjOyM7IzsjOw",
"path": "/top-sellers",
"description": "Lists the most sold products right now.",
"displayName": "Top Sellers",
"attributes": {},
"resultType": "products",
"products": [
{
"key": "0226964_en-US",
"ticket": "Oy90b3Atc2VsbGVyczsjO3Byb2R1Y3Rfa2V5OzAyMjY5NjRfZW4tVVM7MDIyNjk2NDAxM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0226964013_en-US",
"ticket": "Oy90b3Atc2VsbGVyczsjO3Byb2R1Y3Rfa2V5OzAyMjY5NjRfZW4tVVM7MDIyNjk2NDAxM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Derby Shoes"
]
}
},
{
"key": "0443571_en-US",
"ticket": "Oy90b3Atc2VsbGVyczsjO3Byb2R1Y3Rfa2V5OzA0NDM1NzFfZW4tVVM7MDQ0MzU3MTAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0443571001_en-US",
"ticket": "Oy90b3Atc2VsbGVyczsjO3Byb2R1Y3Rfa2V5OzA0NDM1NzFfZW4tVVM7MDQ0MzU3MTAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Short-sleeved Shirt Slim fit"
]
}
},
{
"key": "0715684_en-US",
"ticket": "Oy90b3Atc2VsbGVyczsjO3Byb2R1Y3Rfa2V5OzA3MTU2ODRfZW4tVVM7MDcxNTY4NDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0715684001_en-US",
"ticket": "Oy90b3Atc2VsbGVyczsjO3Byb2R1Y3Rfa2V5OzA3MTU2ODRfZW4tVVM7MDcxNTY4NDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Regular Fit Denim Shirt"
]
}
}
]
}
]
}