Properties

Property types

The SDK uses two types of properties:

ICultureSensitiveProperty - properties with a value per culture.
ICultureInsensitiveProperty - properties that have one value and do not support cultures.

Note

This is related to the IsMultiLanguage property on the property definition.

Getting properties

For the following examples, assume that:

entity is an M.Asset entity
Title is a culture-insensitive property
Description is culture-sensitive property

Note

Property names are not case sensitive.

Non-generic

All property subtypes derive from IProperty, but to access the values, a cast to the specific subtype is required.

RequestResponse

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

var titleProperty: IProperty = entity.getProperty("Title");

Warning

Exceptions will be thrown when casting to the wrong type of property. Check the property definition when in doubt whether a property is culture sensitive or not. IProperty.IsCultureSensitive can also be used.

Generic

Alternatively, use the generic overloads to cast it automatically to either a ICultureInsensitiveProperty or ICultureSensitiveProperty.

RequestResponse

import { ICultureInsensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-insensitive-property";
import { ICultureSensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-sensitive-property";

var titleProperty = entity.getProperty ICultureInsensitiveProperty ("Title");
var descriptionProperty = entity.getProperty ICultureSensitiveProperty ("Description");

Note

When the property is not found or is not loaded, null is returned. However, properties can be lazy loaded.

Note

All loaded properties can also be accessed using the IEntity.Properties property. This is useful for things such as filtering properties with LINQ.

Getting property values

To get a value from a ICultureInsensitiveProperty property, use:

RequestResponse

import { ICultureInsensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-insensitive-property";

var titleProperty = entity.getProperty ICultureInsensitiveProperty ("Title");
var title = titleProperty.getValue();

To get a value from a ICultureSensitiveProperty property, you also have to pass a culture. This will get the description in English:

RequestResponse

import { ICultureSensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-sensitive-property";

var descriptionProperty = entity.getProperty ICultureSensitiveProperty ("Description");
var description = descriptionProperty.getValue("en-US");

Setting property values

To set a value on a ICultureInsensitiveProperty property, use:

RequestResponse

import { ICultureInsensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-insensitive-property";

var titleProperty = entity.getProperty ICultureInsensitiveProperty ("Title");
titleProperty.setValue("a new title");

To set a value on a ICultureSensitiveProperty property, it is also required to pass a culture.

RequestResponse

import { ICultureSensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-sensitive-property";

var descriptionProperty = entity.getProperty ICultureSensitiveProperty ("Description");
var description = descriptionProperty.setValue("en-US","a new description");

Multi-value properties

When properties are multi-value, their type changes to an array. Suppose that MultiDescription is multi-value and a culture sensitive string property, getting the property value can be done like this:

RequestResponse

import { ICultureSensitiveProperty } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base/culture-sensitive-property";
import { PropertyValuePerCulture } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/base";

var multiDescriptionProperty = entity.getProperty ICultureSensitiveProperty ("MultiDescription");
var values: PropertyValuePerCulture = multiDescriptionProperty.getValues(["en-US","fr-BE"]);
var enUsValue = values["en-US"];

Note

This is related to the IsMultiValue property on the property definition.

Using property values directly on an entity

It is also possible to get and set property values directly from an IEntity. This acts as a shortcut where internally the property is fetched and then the value of that property is either returned or set.

Getting values

To get a value from a ICultureInsensitiveProperty property, use:

RequestResponse

var title = entity.getPropertyValue("title");

To get a value from a ICultureSensitiveProperty property, you also need to pass the culture.

RequestResponse

var description = entity.getPropertyValue("description", "en-US");

Warning

If the property does not exist, or if it is not loaded, the default value of the requested type (here, string) will be returned. It is advised to pass nullable types (like long? instead of long for primitives), so that null can be returned. Otherwise the default value of a primitive might cause confusion.

Warning

Keep in mind what type of property is being used when getting a property value directly from the entity. If it is a culture-sensitive property, make sure to pass a culture, otherwise an InvalidOperationException exception will be thrown.

Setting values

To set a value on a ICultureInsensitiveProperty property, use:

RequestResponse

entity.setPropertyValue("Title", "a new title");

To set a value on a ICultureSensitiveProperty property, it is necessary to pass the culture also.

RequestResponse

entity.setPropertyValue("Description", "a new description", "en-US")

Warning

If the property does not exist, or if it is not loaded, SDK will throw an PropertyNotFoundException.

Warning

Similar to getting property values, keep in mind which type of property is being used when getting a property value directly from the entity.