Categorizations

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

How it works

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

The Target property of the NodeRelation contains the ContentReference of the category. You can categorize each entry and category. The class also has a SortOrder property that describes the order of the categorizations. In the case of entries, the NodeRelation with the lowest SortOrder also determines the content's ParentLink, defining the home location of the entry in the content tree. If an entry has no categorizations, it appears 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); that is, you cannot add the same categorization 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;
}

You can use the UpdateRelations method or UpdateRelation extension method of ILinksRepository to add new NodeRelation objects to an entry or category. The new categorization must 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);
}

By calling the RemoveRelations method or RemoveRelation extension method of ILinksRepository with a NodeRelation object matching an existing categorization, that categorization is removed. You can construct a matching object, or use GetRelationsBySource or 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);
}