A guide to creating a property editor in Umbraco.
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 set up to use Typescript and Lit.
To see how to set up an extension in Umbraco using Typescript and Lit, read the article Creating your first extension.
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:
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.
At each step, you will find a dropdown forsuggestions-property-editor-ui.element.ts, and umbraco-package.json
to confirm your placement for code snippets.
Follow the Vite Package Setup by creating a new project folder called "suggestions
" in App_Plugins
.
Then create the manifest file named umbraco-package.json
at the root of the suggestions
folder. Here we define and configure our dashboard.
Add the following code to umbraco-package.json
:
Make sure to restart the application after you create and updateumbraco-package.json
Now let's create the web component we need for our property editor.
Create a file in the src
folder with the name suggestions-property-editor-ui.element.ts
In this new file, add the following code:
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
Restart the application.
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.
Check out the content where you will see the property editor that looks like this:
Let's start by creating an input field and some buttons that we can style and hook up to events.
Update the render method to include some input fields and buttons in the suggestions-property-editor-ui.element.ts
file:
The Umbraco UI library is already a part of the backoffice, which means we can start using it.
Add some styling. Update the import from lit to include CSS:
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.
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
Add the import so the event can be used:
Add the event to the property editor:
Let's look at the suggestions button next.
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.
Update the import for Lit:
Add suggestions to the property editor:
Update the suggestion button in the render method to call a onSuggestion
method when we press the button:
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.
Learn more about extending this service by visiting the Property Editors page.
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.
Integrate one of the built-in Umbraco Contexts.
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:
Add the following imports in the suggestions-property-editor-ui.element.ts
file. This includes the notification context.
Update the class to extend from UmbElementMixin. This allows us to consume the contexts that we need:
Create the constructor where we can consume the notification context above the render()
method:
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.
Add the #onTextTrim()
method above the render()
method:
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.
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.
Add the following import in the suggestions-property-editor-ui.element.ts
file:
Remove the UmbNotificationContext
from the "@umbraco-cms/backoffice/notification"
import:
Update the constructor to consume the UMB_MODAL_MANAGER_CONTEXT
and the UMB_CONFIRM_MODAL.
Add more logic to the onTextTrim
method:
After asking for a suggestions and then clicking on "Trim text", you will be asked if you are sure that you want the text to be trimmed. This is if the suggested text is long enough to be trimmed:
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.
Adding configuration options to the editor.
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:
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.
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
.
Add some properties
:
Above we added two configuration fields. Each entry of the properties
collection represents a Configuration field. Each has the information needed for a field.
The Property Editor UI needs to be declared as it declares what User Interface should be used for this field.
The field with the label "Disabled
" uses the Toggle Property Editor UI. This will allow us to turn the suggestion button on/off and will provide the user with a toggle button.
The field with the label "Placeholder text
" uses the TextBox Property Editor UI. This will allow the user to write a text.
We can now also set some default data on our new configurations:
Save the files and rebuild the application.
To access the configuration options, enable/disable the disabled
option.
Additionally, you can set a default value in the placeholder
field and see the Suggestions Data Type at play.
Since we are using the Umbraco.TextBox
Property Editor Schema, we inherit a maxChars
configuration field from the Property Editor Schema. Let's save it as 20.
The next step is to gain access to our new configuration options. For this, open the suggestions-property-editor-ui.element.ts
file.
Create some state variables that can store our configurations:
Let's create a config property. Add a new import and add the following property:
Look up the alias of the config and then grab the value by said alias:
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.
Add a new import ifDefined
:
Update the render method:
In the suggestions
folder run npm run build
and then run the project. In the content section of the Backoffice you will see the new changes in the property editor:
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.