logo
logo

Load configurations

The SDK uses load configurations and load options to specify:

  • Whether entities need to be loaded or not
  • Which cultures an entity has to be loaded in
  • Which members to load in an entity
Note

The load configurations are located at: Stylelabs.M.Framework.Essentials.LoadConfigurations.
The load options are located at: Stylelabs.M.Framework.Essentials.LoadOptions.

Tip

Try to load the least amount of data using the load options and configurations to minimize the overhead on the server.

In this section, we first explained the different load options, then how to use the load configurations with the load options.

Load options

Load options are an "atomic unit" which specifies how to load a specific item. The currently supported load options are:

  • Culture load option
  • Property load option
  • Relation load option

Every load option has a default, a static and a read-only instance for common use cases. Also, loading options have a copy constructor. This can be used to copy the read-only loading options so that they can be modified.

All the above mentioned load option classes have a LoadOption (an enum) property which can be:

  • None
  • Default
  • Custom
  • All

When set to Custom, the object has to specify what to load by providing a list of property names for the PropertyLoadOption. When the LoadOption is not set to Custom, the list is ignored.

Culture load option

The following are the default culture load options :

  • CultureLoadOption.All: loads all registered cultures in Sitecore Content Hub.
  • CultureLoadOption.Default: loads the default culture in Sitecore Content Hub.
  • CultureLoadOption.None: loads no cultures.
Note

When entities are loaded without cultures, there will be no culture sensitive properties on the entity.

When entities are loaded in a specific set of cultures, culture sensitive properties will only be available in those cultures.

To load a specific set of cultures, create a new CultureLoadOption by using one of the following methods:

  • By passing locale identifiers (LCID) comma separated:
import { CultureLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/culture-load-option";

var cultures = [
    "en-US", 
    "nl-BE"
];

new CultureLoadOption(cultures);
  • By passing CultureInfo instances (comma separated):
import { CultureLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/culture-load-option";

var cultures: CultureInfo[] = [
    "en-US",
    "nl-BE"
];

new CultureLoadOption(cultures);

Property load option

The following are the default property load options:

  • PropertyLoadOption.All: loads all properties on the entity.
  • PropertyLoadOption.None: loads no properties on the entity.

To load a specific set of properties, create a new PropertyLoadOption using one of the following methods :

  • By passing the property names (comma separated):
import { PropertyLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/property-load-option";

var names = ["propertyName1", "propertyName2"]
new PropertyLoadOption(names);
  • By passing any type of collection (deriving from IEnumerable) of property names:
import { PropertyLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/property-load-option";

new PropertyLoadOption("propertyName1");

Relation load option

The following are the default relation load options:

  • RelationLoadOption.All: loads all relations on the entity.
  • RelationLoadOption.None: loads no relations on the entity.

To load a specific set of relations, create a new RelationLoadOption using one of the following methods :

  • By passing the relation names (comma separated):
import { RelationLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/relation-load-option";

var names = ["relationName1", "relationName2"]
new RelationLoadOption(names);
  • By passing any type of collection (deriving from IEnumerable) of relation names:
import { RelationLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/relation-load-option";

new RelationLoadOption("relationName1");

Load configurations

Loading configurations are a "molecular unit" which aggregates multiple load options.

Note

Loading configurations also have default configuration values and support copy constructors.

Note

Previously the IQueryLoadConfiguration was mentioned here, but since the split of the Query and LoadConfiguration, the IQueryLoadConfiguration should only be used internally in the SDK.

Entity load configuration

The configuration consists of:

  • CultureLoadOption
  • PropertyLoadOption
  • RelationLoadOption

The following are the default entity loading configurations :

  • EntityLoadConfiguration.Minimal: loads entities without any cultures, properties and relations. Only system properties are available (id, definition, created on, created by...).
  • EntityLoadConfiguration.Default: loads entities in the default culture, all properties and no relations.
  • EntityLoadConfiguration.DefaultCultureFull: loads entities in the default culture, with all properties and all relations.
  • EntityLoadConfiguration.Full: loads entities in all cultures, all properties and all relations.

A Custom configuration is created in the following method :

import { EntityLoadConfiguration } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/entity-load-configuration";
import { CultureLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/culture-load-option";
import { PropertyLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/property-load-option";
import { RelationLoadOption } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/relation-load-option";

new EntityLoadConfiguration(
    CultureLoadOption.Default,
    new PropertyLoadOption([
        "Title",
        "FileName"
    ]),
    new RelationLoadOption([
        "AssetTypeToAsset"
    ])
);

This example loads the entity without any cultures, with the Title and FileName properties, and with the AssetTypeToAsset relation.

Note

It is also possible to set the load options using the properties instead of the constructor.

Note

When no EntityLoadConfiguration is specified, the SDK always uses the Default configuration.

Entity load configuration builder

The IEntityLoadConfiguration comes with a builder to easily create or extend load configurations.

The following example starts from the minimal load configuration, but adds two relations:

import { EntityLoadConfiguration } from "@sitecore/sc-contenthub-webclient-sdk/dist/contracts/querying/entity-load-configuration";

EntityLoadConfiguration.Minimal.builder().withRelations(["Relation1", "Relation2"]).build();

This line consists of multiple parts:

  • EntityLoadConfiguration.Minimal: it starts from a default provided load configuration.
  • Builder(): to build a new configuration, we need to get the builder.
  • WithRelations(new[] { "Relation1", "Relation2" }): changes the load configuration inside the builder. This can be chained with all other builder methods.
  • .Build(): finally we finish the build process and get the final load configuration.

Can we improve this article ? Provide feedback