Relations

Content Hub features four main relation types:

These are the most strongly typed interfaces and are recommended to be used most of the time. However, they also derive from the following interfaces, where appropriate:

These interfaces can be used for polymorphism or quickly working with relations, if not specifying the type exactly.

Relations can be retrieved from an entity.

To get a relation without specifying the type:

import { IRelation } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relation";

var relation : IRelation = entity.getRelation("AssetTypeToAsset");

The preferred approach to getting a typed relation is as follows:

import { IRelation, RelationBase } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relation";
import { IChildToManyParentsRelation } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relations/child-to-many-parents-relation";

var childToManyParentsRelation = entity.getRelation("AssetTypeToAsset") as IChildToManyParentsRelation;

To check the type of a relation, run a script similar to the following:

import { IRelation, RelationBase } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relation";
import { IChildToManyParentsRelation } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relations/child-to-many-parents-relation";

var relation: IRelation = entity.getRelation("AssetTypeToAsset");
if (RelationBase.isChildToManyParentsRelation(relation)){
}

Depending on the relation interface being used, there are different ways to get and set values. For a complete overview, see the API reference.

IRelation supports a few operations on values. While this might be the easiest way to work with relations, it is also more error prone. It is advised to use the four main relation interfaces and use their properties.

Getting the values will always return a list of ids. If the relation is a IToManyRelation, the list can contain zero to many values. If the relation is a IToOneRelation it will either return an empty list or exactly one value.

var values: number[] = relation.getIds();

Setting values is done by passing a collection of ids. If the relation is a IToManyRelation, the list can contain zero to many values. If the relation is a IToOneRelation , the list can contain zero or exactly one value.

relation.setIds(ids)

To clear a relation's values:

relation.clear();

The strongly typed relations have better support for values. Take for example the IParentToManyChildrenRelation parentToManyChildrenRelation.

To get its children:

var children :number[] = parentToManyChildrenRelation.children;

To add a child:

parentToManyChildrenRelation.add(id);

Another useful example is the addRange, which can add multiple items at once:

parentToManyChildrenRelation.addRange(ids);

Self-referencing relations are relations that point to the same entity definition on both sides of the relation. This results in two relation objects with the same name on the entity.

When getting a relation in a non-generic way, it is necessary to specify the role required. If not, an InvalidOperationException will be thrown, since there are two matching relations.

import { IRelation } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relation";
import { RelationRole } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base";

var relation: IRelation = entity.getRelation("SelfReferencingRelation", RelationRole.Child);

When getting the relation in a generic way, the SDK extracts the role from the interface. So the following example will work for normal and self-referencing relations:

import { IRelation, RelationBase } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relation";
import { IChildToManyParentsRelation } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/relations/child-to-many-parents-relation";

var childToManyParentsRelation = entity.getRelation("SelfReferencingRelation
") as IChildToManyParentsRelation;

This will extract the role Child internally.