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	`en-GB`
`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'?>
<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>