Working with Categories

Category is one of the main data entity types in Apptus eSales. 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.

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.

// Visualisation example

      Clothes               Collections
         │                      │
      Ladies            Summer Collection
  ┌──────┴──────┐               │
Jeans         Tops              │
  │             └───────┬───────┘
 P_2                   P_1

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.

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

Imports and data structure

Ads are imported as UTF-8 formatted XML through the RESTful API. The data structure of imports of ads vary depending on the import method.

Full import example
<?xml version='1.0' encoding='UTF-8'?>
        <category_tree product_attributes="section">
            <category key="men-shoes-running-shoes" parent="men-shoes">
                <display_name>Running shoes</display_name>
            <category key="men-shoes-tennis-shoes" parent="men-shoes">
                <display_name>Tennis shoes</display_name>