In the following section, you will find a list of the default Property Editor Schema aliases in Umbraco. We recommend you use one of these as propertyEditorSchemaAlias when defining a custom Property Editor in umbraco-package.json.

The chosen Property Editor Schema determines the resulting .NET runtime type of the stored Property Editor data. As this will ultimately be used when rendering the website, it is important to choose an appropriate Property Editor Schema.

Overview

This is the third step in the Property Editor tutorial. In this part, we will integrate built-in Umbraco Contexts. For this sample, we will use the UmbNotificationContext for some pop-ups and the UmbModalManagerContext. UmbNotificationContext is used to show a dialog when you click the Trim button and the textbox's input length is longer than the maxLength configuration.

The steps we will go through in this part are:

Setting up the contexts

1. Add the following imports in the suggestions-property-editor-ui.element.ts file. This includes the notification context.

1. Update the class to extend from UmbElementMixin. This allows us to consume the contexts that we need:

1. Create the constructor where we can consume the notification context above the render() method:

Using the notification context

Now we can use the notification context, let's change our #onTrimText method.

First, check if the length of our input is smaller or equal to our maxLength configuration. If it is, we have nothing to trim and will send a notification saying there is nothing to trim.

Here we can use the NotificationContext's peek method. It has two parameters UmbNotificationColor and anUmbNotificationDefaultData object.

1. Add the #onTextTrim()method above the render() method:

1. Add a click event to the trim text button in the render() method:

If our input length is less or equal to our maxLength configuration, we will now get a notification when pressing the Trim button.

Adding more logic to the context

Let's continue to add more logic. If the length is more than the maxChars configuration, we want to show a dialog for the user to confirm the trim.

Here, we use the ModalManagerContext which has an open method to show a dialog.

Like the notification context, we need to import it and consume it in the constructor.

1. Add the following import in the suggestions-property-editor-ui.element.ts file:

1. Remove the UmbNotificationContext from the "@umbraco-cms/backoffice/notification" import:

1. Update the constructor to consume the UMB_MODAL_MANAGER_CONTEXTand the UMB_CONFIRM_MODAL.

1. Add more logic to the onTextTrim method:

1. Run the command npm run build in the suggestions folder.

2. Run the project.

3. Go to the Content section of the Backoffice.

4. Ask for suggestions and click on the Trim text button. If the suggested text is long enough to be trimmed, you will be asked for confirmation:

Wrap up

Over the previous steps, we have:

• Created a plugin.

• Defined an editor.

• Registered the Data Type in Umbraco.

• Added configuration to the Property Editor.

• Connected the editor with UmbNotificationContext and UmbModalManagerContext.

• Looked at some of the methods from notification & modal manager contexts in action.

• Integrated one of the built-in Umbraco Contexts with the Property Editor.

Overview

This guide explains how to set up a property editor and hook it into Umbraco's Data Types. It also covers the creation of a basic property editor and how we can test our property editor.

The steps we will go through in part one are:

This tutorial uses Typescript and Lit with Umbraco, It is expected that your package is already .

To see how to set up an extension in Umbraco using Typescript and Lit, read the article .

Resources

This tutorial will not go in-depth on how Typescript and Lit work. To learn about Typescript and Lit, you can find their documentation below:

The End Result

At the tutorial's end, we'll have a Umbraco Suggestions Data Type, registered in the backoffice, and assigned to a Document Type. This Data Type can create and suggest values.

Setting up a plugin

2. Then create the manifest file named umbraco-package.json at the root of the suggestions folder. Here we define and configure our dashboard.

3. Add the following code to umbraco-package.json:

Creating a Web Component

Now let's create the web component we need for our property editor.

1. Create a file in the src folder with the name suggestions-property-editor-ui.element.ts

2. In this new file, add the following code:

1. In the vite.config.ts file replace the entry to our newly created .ts file:

Now our basic parts of the editor are done, namely:

• The package manifest, telling Umbraco what to load

• The web component for the editor

1. Reload the backoffice.

Registering the Data Type in Umbraco

1. Add our newly added property editor "Suggestions" in the Document Type and save it.

We can now edit the assigned property's value with our new property editor.

1. Check out the content where you will see the property editor that looks like this:

Adding styling and setting up events in the Web Components

Let's start by creating an input field and some buttons that we can style and hook up to events.

1. Update the render method to include some input fields and buttons in the suggestions-property-editor-ui.element.ts file:

1. Add some styling. Update the import from lit to include CSS:

1. Add the CSS:

It should now look something like this:

It's starting to look good! Next, let's look into setting up the event logic.

Setup Event Logic

Setup Input Field

Let's start with the input field. When we type something in the input field, we want the property editor's value to change to the input field's current value.

We then have to dispatch an property-value-change event which can be done in two ways:

• Using new CustomEvent('property-value-change') or

• Using new UmbPropertyValueChangeEvent() which is recommended as you can leverage the core class

1. Add the import so the event can be used:

1. Add the event to the property editor:

Let's look at the suggestions button next.

Setup Suggestions Button

• When we press the suggestion button we want the text to update to the suggestion that we get. Similar to how the value of our property editor changes when we write in the input field.

• We also want the value to change when we press the suggestion button.

1. Update the import for Lit:

1. Add suggestions to the property editor:

1. Update the suggestion button in the render method to call a onSuggestion method when we press the button:

1. Clear your cache, reload the document, and see the Suggestions Data Type running.

When we save or publish, the value of the Data Type is now automatically synced to the current content object and sent to the server.

Going further

With all the steps completed, we have created a Suggestion data type running in our property editor.

In the next part, we will look at adding configurations to our property editor.

Overview

In the previous steps, we created a custom Property Editor for the Umbraco backoffice client. In this step, we will discuss how to convert the Property Editor values for use when rendering the website.

To this end, we will create a Property Value Converter that converts the stored suggestion text into a custom rendering model.

When should I use a Property Value Converter?

A Property Value Converter is usually not necessary. Based on the chosen propertyEditorSchemaAlias, Umbraco will automatically provide appropriately typed models for rendering the Property Editor. For more information, see the Default Property Editor Schema Alias options article.

The most common use-cases for building a Property Value Converter are:

• Property Editors that store values which require server-side conversion, in order to render an appropriate output.

• Property Editors with specific caching requirements.

• Tailoring the Property Editor output value specifically for the Content Delivery API.

Implementing a Property Value Converter

A Property Value Converter must meet a few required responsibilities:

1. Identifying itself as being able to convert values for a given Property Editor.

2. Declaring the concrete runtime type it will be outputting.

3. Performing the value conversion from the stored

The following code snippet outlines how these could be solved for our suggestion Property Editor.

using Umbraco.Cms.Core.Models.PublishedContent;
using Umbraco.Cms.Core.PropertyEditors;

namespace Umbraco.Docs.PropertyEditors;

// the Property Value Converter that handles the suggestions Property Editor
public class MySuggestionsPropertyValueConverter : PropertyValueConverterBase
{
    // 1. converts properties with the property type editor UI alias "My.PropertyEditorUi.Suggestions"
    public override bool IsConverter(IPublishedPropertyType propertyType)
        => propertyType.EditorUiAlias == "My.PropertyEditorUi.Suggestions";

    // 2. yields outputs of type MySuggestionsModel
    public override Type GetPropertyValueType(IPublishedPropertyType propertyType)
        => typeof(MySuggestionsModel);

    // 3. converts the suggestion (string) to the output type (MySuggestionsModel)
    public override object? ConvertIntermediateToObject(
        IPublishedElement owner,
        IPublishedPropertyType propertyType,
        PropertyCacheLevel referenceCacheLevel,
        object? inter,
        bool preview)
        => inter is string suggestion
            ? new MySuggestionsModel
            {
                Suggestion = $"Here's a suggestion for you: {suggestion}"
            }
            : null;
}

// the custom rendering model for the suggestions Property Editor
public class MySuggestionsModel
{
    public required string Suggestion { get; init; }
}

For more advanced Property Value Converter techniques (for example, controlling caching), see the Property Value Converters article.

Overview

When creating Property Editors, our intended audience is trusted (logged-in) backoffice users. Therefore, we can rely on client-side validation of user inputs. However, there are occasions when server-side validation is necessary as well.

Server-side validation is performed by implementing a Data Editor, which is the server-side pendent to the Property Editor.

In this article, we will implement server-side validation for the Suggestion Property Editor created in the previous steps.

When should I use a Data Editor?

As mentioned above, server-side validation is the most common use-case for implementing a Data Editor.

Less common use-cases include:

• Custom content indexing for search,

• Server-side conversion of the data that is passed to - and received from - the Property Editor UI,

• and more.

These will be discussed briefly at the end of this article.

Implementing server-side validation

Validation is initiated by the Data Editor, but the actual handling is performed in a Data Value Editor implementation:

using Umbraco.Cms.Core.Models;
using Umbraco.Cms.Core.PropertyEditors;

namespace Umbraco.Docs.PropertyEditors;

[DataEditor("My.DataEditor.Suggestions", ValueEditorIsReusable = true)]
public class MySuggestionsDataEditor : DataEditor
{
    public MySuggestionsDataEditor(IDataValueEditorFactory dataValueEditorFactory)
        : base(dataValueEditorFactory)
    {
    }

    protected override IDataValueEditor CreateValueEditor()
        => DataValueEditorFactory.Create<MySuggestionsDataValueEditor>(Attribute!);
}

The Data Value Editor in turn employs Value Validators to handle specific aspects of validation. Usually we'll create our own Value Validator implementations, but we could also reuse the ones in Umbraco (for example, the EmailValidator).

using Umbraco.Cms.Core.IO;
using Umbraco.Cms.Core.PropertyEditors;
using Umbraco.Cms.Core.PropertyEditors.Validators;
using Umbraco.Cms.Core.Serialization;
using Umbraco.Cms.Core.Strings;

namespace Umbraco.Docs.PropertyEditors;

public class MySuggestionsDataValueEditor : DataValueEditor
{
    public MySuggestionsDataValueEditor(
        IShortStringHelper shortStringHelper,
        IJsonSerializer jsonSerializer,
        IIOHelper ioHelper,
        DataEditorAttribute attribute)
        : base(shortStringHelper, jsonSerializer, ioHelper, attribute)
        => Validators.Add(new MySuggestionsValueValidator());
}

The Value Validator performs validation based on the user input from the Property Editor along with the configuration of the Data Type:

using System.ComponentModel.DataAnnotations;
using Umbraco.Cms.Core.PropertyEditors;

namespace Umbraco.Docs.PropertyEditors;

public class MySuggestionsValueValidator : IValueValidator
{
    public IEnumerable<ValidationResult> Validate(object? value, string? valueType, object? dataTypeConfiguration)
    {
        // do we have a string value and a valid set of configuration data?
        if (value is not string stringValue
            || dataTypeConfiguration is not Dictionary<string, object?> dataTypeConfigurationValues)
        {
            // no - let's not attempt to handle this.
            return [];
        }

        // do we have a "maxChars" int configuration?
        if (dataTypeConfigurationValues.TryGetValue("maxChars", out object? maxCharsConfigurationValue) is false
            || maxCharsConfigurationValue is not int maxCharsValue)
        {
            // no - nothing to base our validation on.
            return [];
        }

        return stringValue.Length <= maxCharsValue
            ? []
            : [new ValidationResult($"The suggestion exceeded the max allowed characters ({maxCharsValue})")];
    }
}

Coupling the Property Editor and the Data Editor

With the Data Editor in place, update the Property Editor propertyEditorSchemaAlias in umbraco-package.json to match the Data Editor alias (My.DataEditor.Suggestions):

{
    "$schema": "../../umbraco-package-schema.json",
    "name": "My.AwesomePackage",
    "version": "0.1.0",
    "extensions": [
        {
            ...
            "meta": {
                ...
                "propertyEditorSchemaAlias": "My.DataEditor.Suggestions",
                ...
            }
        }
    ]
}

Reload the backoffice and open the "Suggestions" Data Type:

The Umbraco UI already lists the Data Type as using the Data Editor. However, the Data Type configuration is still stored in the database using Umbraco.Plain.String. To effectively apply the Data Editor, we must re-save the Data Type.

Advanced Data Editor use-cases

As mentioned earlier, the Data Editor has more use-cases than adding server-side validation.

While it is beyond the scope of this article to discuss these in depth, a few of them deserve a mention.

Custom content indexing for search

We can control how property data is indexed by overriding the PropertyIndexValueFactory property of the DataEditor base class.

The Tags Property Editor contains an example of how this is done. The Property Editor stores a CSV value, which is split and indexes as individual tags for search.

Server-side data conversion to and from the client

Sometimes it is necessary to perform outbound and/or inbound conversion of property data (to/from the Property Editor UI). Some known use-cases are:

• Cleaning up property data - for example, removing previously selected options that no longer apply at server level.

• Transforming property data to/from a format supported by the Property Editor UI.

These operations can be performed in the DataValueEditor implementation:

• Override ToEditor() to perform outbound conversion.

• Override FromEditor() to perform inbound conversion.

The Markdown Property Editor contains an example of data conversion. It sanitizes the property data before storing the data in the database.

Overview

This is step two in our guide to building a Property Editor. This step continues work on the Suggestion Data Type we built in part one but goes further to show how to add configuration options to our editor.

The steps we will go through in the second part are:

• Adding settings object to umbraco-package.json

• Using the configuration

Configuration

An important part of building good Property Editors is to build something flexible, so we can reuse it many times, for different things. Like the Rich Text Editor in Umbraco, which allows us to choose which buttons and stylesheets we want to use on each instance of the editor.

An editor can be used again and again, with different configurations, and that is what we will be working on now.

Adding settings object to umbraco-package.json

To add a Data Type configuration field when using our Suggestion Property Editor, open the umbraco-package.json file. Inside the meta object, we can add the settings object, which has the optional objects properties and defaultData.

1. Add some properties:

    ...
    "meta": {
        ...
        "settings": {
            "properties": [
                {
                    "alias": "disabled",
                    "label": "Disabled",
                    "description": "Disables the suggestion button",
                    "propertyEditorUiAlias": "Umb.PropertyEditorUi.Toggle"
                },
                {
                    "alias": "placeholder",
                    "label": "Placeholder text",
                    "description": "A nice placeholder description to help out our editor!",
                    "propertyEditorUiAlias": "Umb.PropertyEditorUi.TextBox"
                },
                {
                    "alias": "maxChars",
                    "label": "Max characters allowed",
                    "description": "The maximum number of allowed characters in a suggestion",
                    "propertyEditorUiAlias": "Umb.PropertyEditorUi.Integer"
                }
            ]
        }
        ...
    }

In the section above, we added three configuration fields. Each entry in the properties collection represents a Configuration field. It contains the necessary information for that field.

• The field labeled "Disabled" uses the Toggle Property Editor UI. This enables to switch the suggestion button on or off and provides the user with a toggle button.

• The field labeled "Placeholder text" uses the TextBox Property Editor UI, allowing the user to write a text.

• The field labeled "Max characters allowed" uses the Integer Property Editor UI, enabling the user to enter a numeric value.

1. We can now also set some default data on our new configurations:

  ...
  "meta": {
    ...
    "settings": {
      "properties": [...],
      "defaultData": [
        {
          "alias": "disabled",
          "value": true
        },
        {
          "alias": "placeholder",
          "value": "Write a suggestion"
        },
        {
          "alias": "maxChars",
          "value": 50
        }
      ]
   }
   ...

{
    "$schema": "../../umbraco-package-schema.json",
    "id": "My.AwesomePackage",
    "name": "My Awesome Package",
    "version": "0.1.0",
    "extensions": [
        {
            "type": "propertyEditorUi",
            "alias": "My.PropertyEditorUi.Suggestions",
            "name": "My Suggestions Property Editor UI",
            "element": "/App_Plugins/Suggestions/dist/suggestions.js",
            "elementName": "my-suggestions-property-editor-ui",
            "meta": {
                "label": "Suggestions",
                "icon": "icon-list",
                "group": "common",
                "propertyEditorSchemaAlias": "Umbraco.Plain.String",
                "settings": {
                    "properties": [
                        {
                            "alias": "disabled",
                            "label": "Disabled",
                            "description": "Disables the suggestion button",
                            "propertyEditorUiAlias": "Umb.PropertyEditorUi.Toggle"
                        },
                        {
                            "alias": "placeholder",
                            "label": "Placeholder text",
                            "description": "A nice placeholder description to help out our editor!",
                            "propertyEditorUiAlias": "Umb.PropertyEditorUi.TextBox"
                        },
                        {
                            "alias": "maxChars",
                            "label": "Max characters allowed",
                            "description": "The maximum number of allowed characters in a suggestion",
                            "propertyEditorUiAlias": "Umb.PropertyEditorUi.Integer"
                        }
                    ],
                    "defaultData": [
                        {
                            "alias": "disabled",
                            "value": true
                        },
                        {
                            "alias": "placeholder",
                            "value": "Write a suggestion"
                        },
                        {
                            "alias": "maxChars",
                            "value": 50
                        }
                    ]
                }
            }
        }
    ]
}

1. Save the files and reload the backoffice. We can now configure our Data Type:

Using the configuration

The next step is to gain access to our new configuration options. For this, open the suggestions-property-editor-ui.element.ts file.

1. Create some state variables that can store our configurations:

  @state()
  private _disabled?: boolean;

  @state()
  private _placeholder?: string;

  @state()
  private _maxChars?: number;

1. Let's create a config property. Add a new import and add the following property:

import { type UmbPropertyEditorConfigCollection } from "@umbraco-cms/backoffice/property-editor";

1. Look up the alias of the config and then grab the value by said alias:

  @property({ attribute: false })
  public set config(config: UmbPropertyEditorConfigCollection) {
    this._disabled = config.getValueByAlias("disabled");
    this._placeholder = config.getValueByAlias("placeholder");
    this._maxChars = config.getValueByAlias("maxChars");
  }

We can now use the configurations. Let's use the placeholder and maxChars for the input field and the disabled option for the suggestion button.

1. Add a new import ifDefined :

import { ifDefined } from "@umbraco-cms/backoffice/external/lit";

1. Update the render method:

  render() {
    return html`
      <uui-input
        id="suggestion-input"
        class="element"
        label="text input"
        placeholder=${ifDefined(this._placeholder)}
        maxlength=${ifDefined(this._maxChars)}
        .value=${this.value || ""}
        @input=${this.#onInput}
      >
      </uui-input>
      <div id="wrapper">
        <uui-button
          id="suggestion-button"
          class="element"
          look="primary"
          label="give me suggestions"
          ?disabled=${this._disabled}
          @click=${this.#onSuggestion}
        >
          Give me suggestions!
        </uui-button>
        <uui-button
          id="suggestion-trimmer"
          class="element"
          look="outline"
          label="Trim text"
        >
          Trim text
        </uui-button>
      </div>
    `;
  }

import { LitElement, css, html, customElement, property, state, ifDefined } from "@umbraco-cms/backoffice/external/lit";
import { type UmbPropertyEditorUiElement } from "@umbraco-cms/backoffice/extension-registry";
import { type UmbPropertyEditorConfigCollection } from "@umbraco-cms/backoffice/property-editor";
import { UmbPropertyValueChangeEvent } from '@umbraco-cms/backoffice/property-editor';

@customElement('my-suggestions-property-editor-ui')
export default class MySuggestionsPropertyEditorUIElement extends LitElement implements UmbPropertyEditorUiElement {
    @property({ type: String })
    public value = "";

    @state()
    private _disabled?: boolean;

    @state()
    private _placeholder?: string;

    @state()
    private _maxChars?: number;

    @state()
    private _suggestions = [
        "You should take a break",
        "I suggest that you visit the Eiffel Tower",
        "How about starting a book club today or this week?",
        "Are you hungry?",
    ];

    @property({ attribute: false })
    public set config(config: UmbPropertyEditorConfigCollection) {
        this._disabled = config.getValueByAlias("disabled");
        this._placeholder = config.getValueByAlias("placeholder");
        this._maxChars = config.getValueByAlias("maxChars");
    }

    #onInput(e: InputEvent) {
        this.value = (e.target as HTMLInputElement).value;
        this.#dispatchChangeEvent();
    }

    #onSuggestion() {
        const randomIndex = (this._suggestions.length * Math.random()) | 0;
        this.value = this._suggestions[randomIndex];
        this.#dispatchChangeEvent();
    }

    #dispatchChangeEvent() {
        this.dispatchEvent(new UmbPropertyValueChangeEvent());
    }

    render() {
        return html`
            <uui-input
                id="suggestion-input"
                class="element"
                label="text input"
                placeholder=${ifDefined(this._placeholder)}
                maxlength=${ifDefined(this._maxChars)}
                .value=${this.value || ""}
                @input=${this.#onInput}
            >
            </uui-input>
            <div id="wrapper">
                <uui-button
                    id="suggestion-button"
                    class="element"
                    look="primary"
                    label="give me suggestions"
                    ?disabled=${this._disabled}
                    @click=${this.#onSuggestion}
                >
                    Give me suggestions!
                </uui-button>
                <uui-button
                    id="suggestion-trimmer"
                    class="element"
                    look="outline"
                    label="Trim text"
                >
                    Trim text
                </uui-button>
            </div>
        `;
    }

    static styles = [
        css`
            #wrapper {
                margin-top: 10px;
                display: flex;
                gap: 10px;
            }
            .element {
                width: 100%;
            }
        `,
    ];
}

declare global {
    interface HTMLElementTagNameMap {
        'my-suggestions-property-editor-ui': MySuggestionsPropertyEditorUIElement;
    }
}

1. Run the command npm run build in the suggestions folder.

2. Run the project.

3. Go to the Content section of the Backoffice to see the new changes in the property editor:

Going further

We have now added some configurations to our data type and used them in our Property Editor.

In the next step, we are going to integrate context with our Property Editor.