Working with categories¶
Category is one of the main data entity types in Voyado Elevate 3. Categories and products are tightly coupled and can be used together to create large datasets for navigation, product listings, and more.
Categories also support custom attributes enabling retrieval of images, links, or localised names directly from a result without multiple queries. Attribute configuration is done in the Voyado Elevate manager.
Categories are modeled as tree structures that are defined during imports. There is always a root and all categories have an identifying parent category. The only category of a tree that does not have a parent is the implicit root node, which has the key
This model allow every category to have multiple sub-categories but only one parent category. As opposed to products, category keys are not required to be globally unique. The category keys must however be unique within a category tree.
During the import, category trees are assigned a product attribute, sometimes referred to as tree name. The product attribute link individual products to a specific category tree, if it has been configured as a category reference attribute. A category tree can have a maximum depth of 10 levels.
Products and categories¶
A category holds several products, and a product can at the same time be part of several categories. Category reference attributes for a product is a comma-separated list of one or more category keys.
The following example visualises a category tree with two sub-trees,
Collections. The product
P_2 belongs to the
Jeans category while
P_1 belongs to both the
Tops category and the
Panels, such as the Product list panel, can be used to find member products of a category by using the
selected_category parameter in a panel query. This will return products in all sub-categories to the category defined in
selected_category. Depending on the panel used, a filter argument can be added to further define the product and variant set of the result.
selected_category parameter can take one entry and uses the format:
<tree name>:'<category key>'. The tree name is the same as the category reference attribute.
selected_category is used with a zone, all sub-panels taking the argument will use the same parameter value. This also includes a
filter argument for the category.
Filtering can be used as with predefined category attributes, see Category filters, and user defined attributes and category reference attributes. A common use of filters with categories is to exclude sub-categories from a result. This is done by adding a
filter argument on the form
NOT <tree name>:'<category key>' to the query.
Predefined category attributes¶
Categories can have user-defined attributes such as products and ads, but they can also have predefined attributes within their own namespace. This prevents name collisions with user-defined attributes. If user-defined attributes are used, they must be placed within the
| ||string||An attribute that allows for sorting and to show a human-readable name for categories.|| |
| ||string||A |
| ||element||Group element that includes all user-defined attributes for the category.||N/A|
Imports and data structure¶
Categories are imported as UTF-8 formatted XML through the RESTful API. The data structure of imports of categories vary depending on the import method.
Full import example
<?xml version='1.0' encoding='UTF-8'?> <operations> <clear> <category_tree/> </clear> <add> <category_tree product_attribute="section"> <category key="men" parent="root"> <display_name>Men</display_name> <locale>en-GB</locale> <attributes> <url>/categories/men</url> <department>Men</department> </attributes> </category> <category key="mens-shoes" parent="men"> <display_name>Mens shoes</display_name> <locale>en-GB</locale> <attributes> <url>/categories/men/shoes</url> <department>Men</department> </attributes> </category> <category key="men-shoes-running-shoes" parent="mens-shoes"> <display_name>Running shoes</display_name> <locale>en-GB</locale> <attributes> <url>/categories/men/shoes/running-shoes</url> <department>Men</department> </attributes> </category> <category key="men-shoes-tennis-shoes" parent="mens-shoes"> <display_name>Tennis shoes</display_name> <locale>en-GB</locale> <attributes> <url>/categories/men/shoes/tennis-shoes</url> <department>Men</department> </attributes> </category> </category_tree> </add> </operations>