Skip to content

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 localized names directly from a result without multiple queries. Attribute configuration is done in the Voyado Elevate manager.

Category trees

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 root.

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, Clothes and Collections. The product P_2 belongs to the Jeans category while P_1 belongs to both the Tops category and the Summer Collectioncategory.

Category tree visualization example

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.

The 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.

When 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 attributes element.

Name Type Description Example
display_name string An attribute that allows for sorting and to show a human-readable name for categories. Shoes
locale string A locale identifier usually consists of at least a language identifier and a region identifier. The locale determines what language the attribute text is written in and define how data and search queries are managed and how results are sorted. The locale attribute must not be placed within the attributes element.
Recommended attribute
attributes 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'?>
        <category_tree product_attribute="section">
            <category key="men" parent="root">
            <category key="mens-shoes" parent="men">
                <display_name>Mens shoes</display_name>
            <category key="men-shoes-running-shoes" parent="mens-shoes">
                <display_name>Running shoes</display_name>
            <category key="men-shoes-tennis-shoes" parent="mens-shoes">
                <display_name>Tennis shoes</display_name>

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.