Skip to content

Modernize Custom Property Editors/Delivery API away from IPublishedSnapshotAccessor #7573

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+152 −162
Open

Modernize Custom Property Editors/Delivery API away from IPublishedSnapshotAccessor #7573

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
157 changes: 76 additions & 81 deletions 15/umbraco-cms/reference/content-delivery-api/custom-property-editors-support.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,35 +1,31 @@
---
description: >-
Discover how to customize the Content Delivery API's response for your custom
property editors.
Discover how to customize the Content Delivery API's response for custom property editors.
---

# Custom property editors support

Out of the box, the Delivery API supports custom property editors, ensuring they are rendered alongside the built-in ones in Umbraco. However, if the output generated by your property editor isn't optimal for a headless context, you have the ability to customize the API response. This customization won't impact the Razor rendering, allowing you to tailor the Content Delivery API response according to your specific requirements.
Out of the box, the Delivery API supports custom property editors, ensuring they are rendered alongside the built-in ones in Umbraco. However, if the output generated by a property editor isn't optimal for a headless context, developers can customize the API response. This customization won't impact the Razor rendering, allowing developers to tailor the Content Delivery API response according to their specific requirements.

In this article, we'll look into how you can work with the `IDeliveryApiPropertyValueConverter` interface and implement custom [property expansion](./property-expansion-and-limiting.md) for your custom property editors.
This article will demonstrate how to work with the `IDeliveryApiPropertyValueConverter` interface and implement custom [property expansion](./property-expansion-and-limiting.md) for custom property editors.

## Prerequisite

The examples in this article revolve around the fictional `My.Custom.Picker` property editor. This property editor stores the key of a single content item and is backed by a property value converter.

We will not dive into the details of creating a custom property editor for Umbraco in this article. If you need guidance on that, please refer to the [Creating a Property Editor](../../tutorials/creating-a-property-editor/README.md) and [Property Value Converters](../../customizing/property-editors/property-value-converters.md) articles.
This article will not dive into the details of creating a custom property editor for Umbraco. Guidance on that can be found in these articles: [Creating a Property Editor](../../tutorials/creating-a-property-editor/README.md) and [Property Value Converters](../../customizing/property-editors/property-value-converters.md).

## Implementation

To customize the output of a property value editor in the Delivery API, we need to opt-in by implementing the `IDeliveryApiPropertyValueConverter` interface.
To customize the output of a property value editor in the Delivery API, opt-in by implementing the `IDeliveryApiPropertyValueConverter` interface.

The code example below showcases the implementation of this interface in the property value converter for `My.Custom.Picker`. Our focus will be on the methods provided by the `IDeliveryApiPropertyValueConverter`, as they are responsible for customizing the Delivery API response.
The code example below showcases the implementation of this interface in the property value converter for `My.Custom.Picker`. The focus will be on customizing the methods provided by the `IDeliveryApiPropertyValueConverter`, as they are responsible for customizing the Delivery API response.

Towards the end of the example, you will find the response models that we will be using.
Response model classes can be found near the end of this article.

The `IsConverter()` and `GetPropertyValueType()` methods are inherited from the `PropertyValueConverterBase` class, which is covered in the [Property Value Converters](../../customizing/property-editors/property-value-converters.md) article.

{% include "../../.gitbook/includes/obsolete-warning-snapshot.md" %}

{% code title="MyCustomPickerValueConverter.cs" lineNumbers="true" %}

```csharp
using Umbraco.Cms.Core.DeliveryApi;
using Umbraco.Cms.Core.Models.DeliveryApi;
Expand All @@ -38,21 +34,11 @@ using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.PropertyEditors.DeliveryApi;
using Umbraco.Cms.Core.PublishedCache;

namespace Umbraco.Docs.Samples;

public class MyCustomPickerValueConverter : PropertyValueConverterBase, IDeliveryApiPropertyValueConverter
public class MyCustomPickerValueConverter(
IPublishedContentCache publishedContentCache,
IApiContentRouteBuilder apiContentRouteBuilder):
PropertyValueConverterBase, IDeliveryApiPropertyValueConverter
{
private readonly IPublishedSnapshotAccessor _publishedSnapshotAccessor;
private readonly IApiContentRouteBuilder _apiContentRouteBuilder;

public MyCustomPickerValueConverter(
IPublishedSnapshotAccessor publishedSnapshotAccessor,
IApiContentRouteBuilder apiContentRouteBuilder)
{
_publishedSnapshotAccessor = publishedSnapshotAccessor;
_apiContentRouteBuilder = apiContentRouteBuilder;
}

public override bool IsConverter(IPublishedPropertyType propertyType)
=> propertyType.EditorAlias.Equals("My.Custom.Picker");

Expand Down Expand Up @@ -86,38 +72,28 @@ public class MyCustomPickerValueConverter : PropertyValueConverterBase, IDeliver

private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool expanding)
{
if (!_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) ||
publishedSnapshot?.Content is null)
if (!Guid.TryParse(inter as string, out Guid id))
{
return null;
}

var content = publishedContentCache.GetById(id);

if (!Guid.TryParse(inter as string, out Guid id))
if (content is null)
{
return null;
}

return new DeliveryApiCustomPicker { Id = id };
}
}

public class DeliveryApiCustomPicker
{
public Guid Id { get; set; }

public DeliveryApiItemDetails? ItemDetails { get; set; }
}

public class DeliveryApiItemDetails
{
public string? Name { get; set; }

public IApiContentRoute? Route { get; set; }
}
```

{% endcode %}

{% hint style="info" %}
Umbraco developers will need to inject `IPublishedContentCache`, `IPublishedMediaCache`, `IPublishedMemberCache` and `IPublishedContentTypeCache` dependencies individually, instead of injecting the `IPublishedSnapshotAccessor` as would have been done previously.
{% endhint %}

The Implementation of the `IDeliveryApiPropertyValueConverter` interface can be found in the following methods:

* `GetDeliveryApiPropertyCacheLevel()`: This method specifies the cache level used for our property representation in the Delivery API response.
Expand All @@ -129,14 +105,12 @@ In the given example, the content key (`Guid` value) is used when rendering with

The following example request shows how our custom implementation is reflected in the resulting API response. In this case, our custom property editor is configured under the alias `"pickedItem"`.

**Request**

**Sample Request**
```http
GET /umbraco/delivery/api/v2/content/item/blog
```

**Response**

**Sample Response**
```json
{
"name": "Blog",
Expand All @@ -163,57 +137,60 @@ GET /umbraco/delivery/api/v2/content/item/blog

## Property expansion support

Property expansion allows us to conditionally add another level of detail to the Delivery API output. Usually, these additional details are "expensive" to retrieve (for example, requiring database access to populate). By applying property expansion, we provide the option for the caller of the API to opt-in explicitly to this "expensive" operation. From the caller's perspective, the alternative might be an even more expensive additional round-trip to the server.

In our example, property expansion is implemented within `ConvertIntermediateToDeliveryApiObject()`. By considering the value of the `expanding` parameter, we can modify the `BuildDeliveryApiCustomPicker()` method as follows:
Property expansion allows developers to conditionally add another level of detail to the Delivery API output. Usually, these additional details are "expensive" to retrieve (for example, requiring database access to populate). By applying property expansion, Umbraco developers provide the option for the caller of the API to opt-in explicitly to this "expensive" operation. From the caller's perspective, the alternative might be an even more expensive additional round-trip to the server.

{% include "../../.gitbook/includes/obsolete-warning-ipublishedsnapshotaccessor.md" %}
In this example, property expansion is implemented within `ConvertIntermediateToDeliveryApiObject()`. By considering the value of the `expanding` parameter, the `BuildDeliveryApiCustomPicker()` method can be modified as follows:

{% code title="MyCustomPickerValueConverter.cs" lineNumbers="true" %}
```csharp
private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool expanding)
public class MyCustomPickerValueConverter(
IPublishedContentCache publishedContentCache,
IApiContentRouteBuilder apiContentRouteBuilder):
PropertyValueConverterBase, IDeliveryApiPropertyValueConverter
{
if (!_publishedSnapshotAccessor.TryGetPublishedSnapshot(out IPublishedSnapshot? publishedSnapshot) ||
publishedSnapshot?.Content is null)
{
return null;
}

if (!Guid.TryParse(inter as string, out Guid id))
// ...
private DeliveryApiCustomPicker? BuildDeliveryApiCustomPicker(object inter, bool expanding)
{
return null;
}
if (!Guid.TryParse(inter as string, out Guid id))
{
return null;
}

// Property expansion support
if (expanding == false)
{
return new DeliveryApiCustomPicker { Id = id };
}
// Property expansion support
if (!expanding)
{
return new DeliveryApiCustomPicker { Id = id };
}

IPublishedContent? content = publishedSnapshot.Content.GetById(id);
if (content is null)
{
return new DeliveryApiCustomPicker { Id = id };
}
var content = publishedContentCache.GetById(id);
if (content is null)
{
return new DeliveryApiCustomPicker { Id = id };
}

IApiContentRoute? route = _apiContentRouteBuilder.Build(content);
var itemDetails = new DeliveryApiItemDetails { Name = content.Name, Route = route };
var route = apiContentRouteBuilder.Build(content);
var itemDetails = new DeliveryApiItemDetails
{
Name = content.Name,
Route = route
};

return new DeliveryApiCustomPicker { Id = id, ItemDetails = itemDetails };
return new DeliveryApiCustomPicker { Id = id, ItemDetails = itemDetails };
}
}
```
{% endcode %}

If the `expanding` parameter is `false`, the method returns the same shallow representation of the referenced content item as before. Otherwise, we retrieve the corresponding `IPublishedContent` and construct our response object accordingly.

To see the expanded output in the API response, we need to add the `expand` query parameter to our request. We can use either `?expand=properties[$all]` to expand all properties or `?expand=properties[pickedItem]` to expand the specific `'pickedItem'` property.
If the `expanding` parameter is `false`, the method returns the same shallow representation of the referenced content item as before. Otherwise, retrieve the corresponding `IPublishedContent` and construct the response object accordingly.

**Request**
To see the expanded output in the API response, add the `expand` query parameter to the request. This parameter can be applied using either `?expand=properties[$all]` to expand all properties or `?expand=properties[pickedItem]` to expand the specific `'pickedItem'` property.

**Sample Request**
```http
GET /umbraco/delivery/api/v2/content/item/blog?expand=properties[pickedItem]
```

**Response**

**Sample Response**
```json
{
"name": "Blog",
Expand Down Expand Up @@ -250,3 +227,21 @@ GET /umbraco/delivery/api/v2/content/item/blog?expand=properties[pickedItem]
```

The `itemDetails` property of the `pickedItem` in the JSON response contains the additional details of the selected content item.

## Supporting Model Classes

{% code title="MyCustomPickerValueConverter.cs" %}
```csharp
public class DeliveryApiCustomPicker
{
public Guid Id { get; set; }
public DeliveryApiItemDetails? ItemDetails { get; set; }
}

public class DeliveryApiItemDetails
{
public string? Name { get; set; }
public IApiContentRoute? Route { get; set; }
}
```
{% endcode %}
Loading