Categorizations

This document describes how to work with categorizations, in relation to the content model.

How it works

Categorizations are represented by the EPiServer.Commerce.Linking.NodeRelation class and administered using the EPiServer.Commerce.Linking.ILinksRepository service.

The Target property of the NodeRelation contains the ContentReference of the category. Both entries and categories can be categorized. The class also has a SortOrder property describing the order of the categorizations. In the case of entries, the NodeRelation with the lowest SortOrder will also determine the content's ParentLink, defining the home location of the entry in the content tree. If an entry has no categorizations it will appear directly under the catalog itself.

A NodeRelation is uniquely defined by the ContentReference in its Target property together with its Source property (referencing the item being categorized), i.e. the same categorization can not be added more than once to an entry or another category.

Getting the categorizations of an entry or category

By calling the GetRelationsBySource method of ILinksRepository with the ContentReference of a entry or category, and filtering for NodeRelation you get the categorizations:

public IEnumerable<NodeRelation> ListCategories(ContentReference referenceToEntryOrCategory)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();
    var allRelations = linksRepository.GetRelationsBySource(referenceToEntryOrCategory);

    // Relations to categories are of the type NodeRelation
    var categories = allRelations.OfType<NodeRelation>().ToList();
    return categories;
}

Adding a categorization to an entry or category

The UpdateRelations method or UpdateRelation extension method of ILinksRepository can be used to add new NodeRelation objects to an entry or category. The new categorization has to have a Target ContentReference and a Source ContentReference.

public void AddCategory(ContentReference referenceToEntryOrCategory, ContentReference referenceToCategory)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();

    var newCategory = new NodeRelation
        {
            SortOrder = 100,
            Source = referenceToEntryOrCategory,
            Target = referenceToCategory
        };

    linksRepository.UpdateRelation(newCategory);
}

Removing a categorization from an entry or category

By calling the RemoveRelations method or RemoveRelation extension method of ILinksRepository with a NodeRelation object matching an existing categorization, that categorization will be removed. You can either construct a matching object, or use GetRelationsBySource/GetRelationsByTarget to get the existing Relations, filter out the object you want to remove, and pass it to RemoveRelation.

public void RemoveCategory(ContentReference referenceToEntryOrCategory, ContentReference referenceToCategory)
{
    var linksRepository = ServiceLocator.Current.GetInstance<ILinksRepository>();

    // Define a relation matching the one to remove, or use
    // GetRelations to find the one you want to remove and pass that to
    // RemoveRelation
    var relationToRemove = new NodeRelation
    {
        // Source is required here to match the correct relation
        Source = referenceToEntryOrCategory,
        Target = referenceToCategory
    };

    // Removes matching NodeRelation, or no action if no match exists
    linksRepository.RemoveRelation(relationToRemove);
}