Creating a Property Editor

A guide to creating a property editor in Umbraco.

Overview

This guide covers setting up a Property Editor and registering it as a Data Type in Umbraco.

The steps covered in part one are:

• Setting up a Plugin
• Creating a Web Component
• Registering the Data Type in Umbraco
• Adding styling and setting up events in Web Components
• Set up Event Logic

This tutorial uses TypeScript and Lit. Make sure your package is already set up before continuing.

To set up an extension using TypeScript and Lit, see the Creating your first extension 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:

• TypeScript documentation
• Lit documentation

The End Result

By the end of this tutorial, you will have a Suggestions Data Type, registered in the backoffice, and assigned to a Document Type. This Data Type can create and suggest values.

At the end of the final step, a dropdown displaying the entire suggestions-property-editor-ui.element.ts file is available.

Setting up a plugin

1. Follow the Vite Package Setup and use suggestions as the project name instead of client. Create the project in the root of your Umbraco project, next to the App_Plugins folder.
2. Create a manifest file to define and configure the property editor using either JSON or TypeScript.

JSON Manifest

Create a manifest file named umbraco-package.json in the public folder of the suggestions project. Vite copies it to App_Plugins/suggestions when building.

umbraco-package.json

{
    "$schema": "../../umbraco-package-schema.json",
    "name": "My.AwesomePackage",
    "version": "0.1.0",
    "extensions": [
        {
            "type": "propertyEditorUi",
            "alias": "My.PropertyEditorUi.Suggestions",
            "name": "My Suggestions Property Editor UI",
            "element": "/App_Plugins/suggestions/suggestions.js",
            "elementName": "my-suggestions-property-editor-ui",
            "meta": {
                "label": "Suggestions",
                "icon": "icon-list",
                "group": "common",
                "propertyEditorSchemaAlias": "Umbraco.Plain.String"
            }
        }
    ]
}

TypeScript Manifest

Extension authors define the property editor UI manifest, then register it dynamically during runtime using a Backoffice Entry Point extension.

Create a manifest file named manifests.ts in the src folder and add the following code:

manifests.ts

import type { ManifestPropertyEditorUi } from '@umbraco-cms/backoffice/property-editor';

export const propertyEditorUiManifest: ManifestPropertyEditorUi[] = [
    {
        type: 'propertyEditorUi',
        alias: 'My.PropertyEditorUi.Suggestions',
        name: 'My Suggestions Property Editor UI',
        element: () => import('./suggestions-property-editor-ui.element.js'),
        elementName: 'my-suggestions-property-editor-ui',
        meta: {
            label: 'Suggestions',
            icon: 'icon-list',
            group: 'common',
            propertyEditorSchemaAlias: 'Umbraco.Plain.String'
        }
    }
];

Create an entry point file named entrypoint.ts in the src folder to register the manifest:

entrypoint.ts

import type { UmbEntryPointOnInit } from '@umbraco-cms/backoffice/extension-api';
import { propertyEditorUiManifest } from './manifests.js';

export const onInit: UmbEntryPointOnInit = (_host, extensionRegistry) => {
    extensionRegistry.registerMany(propertyEditorUiManifest);
};

Umbraco still needs an umbraco-package.json file to load the entry point. Create it in the public folder:

umbraco-package.json

{
    "$schema": "../../umbraco-package-schema.json",
    "name": "My.AwesomePackage",
    "version": "0.1.0",
    "extensions": [
        {
            "type": "backofficeEntryPoint",
            "alias": "My.EntryPoint.Suggestions",
            "name": "My Suggestions Entry Point",
            "js": "/App_Plugins/suggestions/suggestions.js"
        }
    ]
}

The umbraco-package.json files are cached by the server. When creating new umbraco-package.json files, it might take a few seconds before those are loaded into the server cache.

It is important to select the right propertyEditorSchemaAlias as it affects how the Property Editor data is made available when rendering the website.

In this example, Umbraco.Plain.String is selected because a string value is expected. For more options, see the default Property Editor Schema aliases article.

Creating a Web Component

Create the web component for the 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:

suggestions-property-editor-ui.element.ts

import { LitElement, html, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import type { UmbPropertyEditorUiElement } 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 = '';

    override render() {
        return html`I'm a property editor!`;
    }
}

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

1. Replace the contents of the vite.config.ts file with the following code:

vite.config.ts

import { defineConfig } from "vite";

export default defineConfig({
  build: {
    lib: {
      entry: "src/suggestions-property-editor-ui.element.ts", // your web component source file
      formats: ["es"],
      fileName: "suggestions",
    },
    outDir: "../App_Plugins/suggestions", // the compiled files land in the site's `App_Plugins` folder.
    emptyOutDir: true,
    sourcemap: true,
    rollupOptions: {
      external: [/^@umbraco-cms\/.*/], // ignore the Umbraco Backoffice package in the build
    },
  },
  base: "/App_Plugins/suggestions/", // the base path of the app in the browser (used for assets)
});

If you used the TypeScript manifest, set entry to src/entrypoint.ts instead. Vite bundles the element automatically because the manifest imports it.

The basic parts of the editor are now in place:

• The package manifest, telling Umbraco what to load
• The web component for the editor

1. Run the build. In your terminal, go to the suggestions folder and run:

npm run build

1. Reload the backoffice.

Registering the Data Type in Umbraco

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

Suggestions Property Editor

The property can now be edited using the new Property Editor.

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

The Suggestions property editor in the content editor.

Adding styling and setting up events in the Web Components

Start by creating an input field and some buttons to 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:

suggestions-property-editor-ui.element.ts

override render() {
    return html`
      <uui-input
        id="suggestion-input"
        class="element"
        label="text input"
        .value=${this.value || ""}
      >
      </uui-input>
      <div id="wrapper">
        <uui-button
          id="suggestion-button"
          class="element"
          look="primary"
          label="give me suggestions"
        >
          Give me suggestions!
        </uui-button>
        <uui-button
          id="suggestion-trimmer"
          class="element"
          look="outline"
          label="Trim text"
        >
          Trim text
        </uui-button>
      </div>
    `;
  }

The Umbraco UI library is already a part of the backoffice, which means it can be used immediately.

1. Add some styling. Update the import from lit to include css and UmbTextStyles:

suggestions-property-editor-ui.element.ts

import { LitElement, html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import { UmbTextStyles } from '@umbraco-cms/backoffice/style';

1. Add the CSS:

suggestions-property-editor-ui.element.ts

render() {
  ...
}

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

See the entire `suggestions-property-editor-ui.element.ts` file

suggestions-property-editor-ui.element.ts

import { LitElement, html, css, customElement, property } from '@umbraco-cms/backoffice/external/lit';
import type { UmbPropertyEditorUiElement } from '@umbraco-cms/backoffice/property-editor';
import { UmbTextStyles } from '@umbraco-cms/backoffice/style';

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

    override render() {
        return html`
          <uui-input
            id="suggestion-input"
            class="element"
            label="text input"
            .value=${this.value || ""}
          >
          </uui-input>
          <div id="wrapper">
            <uui-button
              id="suggestion-button"
              class="element"
              look="primary"
              label="give me suggestions"
            >
              Give me suggestions!
            </uui-button>
            <uui-button
              id="suggestion-trimmer"
              class="element"
              look="outline"
              label="Trim text"
            >
              Trim text
            </uui-button>
          </div>
        `;
    }

    static override readonly styles = [
        UmbTextStyles,
        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 build. In your terminal, go to the suggestions folder and run:

npm run build

1. Reload the backoffice.

It should now look something like this:

The property editor after adding the input field and buttons.

Next, set up the event logic.

Set up Event Logic

Set up Input Field

Start with the input field. When typing something in the input field, the property editor's value should change to the input field's current value.

Dispatch a change event using one of two approaches:

• Using new CustomEvent('change') or
• Using new UmbChangeEvent() which is recommended as you can leverage the core class

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

suggestions-property-editor-ui.element.ts

import { UmbChangeEvent } from '@umbraco-cms/backoffice/event';

1. Add the event to the property editor:

suggestions-property-editor-ui.element.ts

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

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

  override render() {
    return html`
      <uui-input
        id="suggestion-input"
        class="element"
        label="text input"
        .value=${this.value || ""}
        @input=${this.#onInput}
      >
      </uui-input>

      ....
}

Look at the suggestions button next.

Setup Suggestions Button

• When pressing the suggestion button, the text should update to the suggestion received. Similar to how the value of the property editor changes when writing in the input field.
• The value should also change when pressing the suggestion button.

1. Update the import for Lit:

suggestions-property-editor-ui.element.ts

import { LitElement, html, css, customElement, property, state } from '@umbraco-cms/backoffice/external/lit';

1. Add suggestions to the property editor:

suggestions-property-editor-ui.element.ts

  @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?',
  ];

  override render() {...}

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

suggestions-property-editor-ui.element.ts

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

override render() {
    return html`

    ...

    <uui-button
        id="suggestion-button"
        class="element"
        look="primary"
        label="give me suggestions"
        @click=${this.#onSuggestion}
        >
        Give me suggestions!
        </uui-button>
    ...
    `;
}

See the entire file: suggestions-property-editor-ui.element.ts

suggestions-property-editor-ui.element.ts

import { UmbChangeEvent } from '@umbraco-cms/backoffice/event';
import { css, customElement, html, LitElement, property, state } from '@umbraco-cms/backoffice/external/lit';
import type { UmbPropertyEditorUiElement } from '@umbraco-cms/backoffice/property-editor';
import { UmbTextStyles } from '@umbraco-cms/backoffice/style';

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

	@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?',
	];

	#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 UmbChangeEvent());
	}

	override render() {
		return html`
			<uui-input
				id="suggestion-input"
				class="element"
				label="text input"
				.value=${this.value || ''}
				@input=${this.#onInput}>
			</uui-input>
			<div id="wrapper">
				<uui-button
					id="suggestion-button"
					class="element"
					look="primary"
					label="give me suggestions"
					@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 override readonly styles = [
		UmbTextStyles,
		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 build. In your terminal, go to the suggestions folder and run:

npm run build

1. Clear your cache and reload the backoffice.
2. Click on the Give me suggestions button to see the Suggestions Data Type in action.

The completed Suggestions property editor with event logic in place.

When saving or publishing, the value of the Data Type is automatically synced to the current content object and sent to the server.

To learn more, visit the Property Editors page.

Going further

The Suggestions Data Type is now set up and running. The next part covers adding configurations to the property editor.