@tridion-sites/models NPM

Tridion Sites models for Extensions

This NPM package provides a set of domain models specifically designed for frontend development of Tridion Sites. These models encapsulate domain-specific logic and provide a convenient abstraction for interacting with the backend data.

Note

Due to reliance on various functionality provided at runtime by Tridion Sites, this package is not suitable for standalone usage and can only be utilized as a part of an extension.

Features

Class-based definitions allow for easy item type checks
Quality of life utilities provided as class instance methods
Handling of TCM / ECL URI formats
Easy conversion from and to @tridion-sites/open-api-client objects

Installation

To install @tridion-sites/models, you can use npm or yarn:

$ npm install @tridion-sites/models
# or
$ yarn add @tridion-sites/models

Mapping to and from the backend data

Converting from a `@tridion-sites/open-api-client` response to a model

Primary utility methods for conversion of the backend DTOs to models are:

tryMapToModel<TModel>(backendDto) - maps provided dto to a model, returns undefined on failure. Important: generic argument is provided to simplify usage of the utility. It doesn't check that the provided type actually corresponds with the realtime type after the conversion.
mapToModel<TModel>(backendDto) - convenience method that throws an error instead of returning undefined if conversion has failed.
mapToModels<TModel>(backendDto[]) - maps an array of backend DTOs to models, returning only successfully mapped objects.

import type { ActivityInstance, ItemUri } from '@tridion-sites/models';
import { mapToModel } from '@tridion-sites/models';
import { ItemsService } from '@tridion-sites/open-api-client';

const getActivityById = async (activityId: ItemUri) => {
    const activity = await ItemsService.getItem(activityId.asString);
    return mapToModel<ActivityInstance>(activity);
};

Converting from a model to a `@tridion-sites/open-api-client` DTO

Every model contains .getInternalModel() method that allows to get the underlying backend DTO.

import { IdentifiableObject } from '@tridion-sites/models';
import { ItemsService } from '@tridion-sites/open-api-client';

const updateItem = async (item: IdentifiableObject) => {
    const backendDto = item.getInternalModel();
    await ItemsService.update(backendDto.Id, backendDto);
};

Item URI handling

There are 2 primary methods for parsing string URIs:

tryParseItemUri - parses a string into an ItemUri object. Returns undefined if the conversion has failed
parseItemUri - convenience method that throws an error instead of returning undefined if conversion has failed.