# Custom Grid Editors
{% hint style="warning" %}
The grid editor Data Type in Heartcore is deprecated and will be retired in June 2025 or thereafter. For more information read the following [blog post](https://umbraco.com/blog/umbraco-heartcore-update-october-2023#editors).
{% endhint %}
In this tutorial, we will create a Custom Grid Editor using [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) and [Lit](https://lit.dev/). We will look at how we can define what the API response for our data should look like.
## Content
* [Create a Document Type and Grid configuration](#create-a-document-type-and-grid-configuration)
* [A look at a default grid editor](#a-look-at-a-default-grid-editor)
* [Create a custom grid editor](#create-a-custom-grid-editor)
* [Using module aliases](#using-module-aliases)
* [Describing the grid editor using JSON schema](#describing-the-grid-editor-using-json-schema)
## Create a Document Type and grid configuration
First, we will need to create a Document Type containing the Grid Layout property editor.
* Go to the **Settings** section.
* Create a new Document Type called **Grid Page**.
* Add a new property called **Grid Content**.
* Select the **Grid layout** editor.
* Accept the default configuration.
The Document Type should now look like this:
To allow the Document Type to be created in the tree we need to change the permissions:
* Select the **Permissions** tab.
* Ensure **Allow as root** is checked.
To verify the configuration follow these steps:
* Go to the **Content** section.
* Create a new page based on the **Grid Page** Document Type we created.
* Give it a name.
* Save the page.
Try choosing a layout, add a row and click **Add content**. Here we will see that we have a couple of editors to choose from.
Try adding one of them to the page to see how they work.
## A look at a default grid editor
Before we start writing our own Grid Editor, let's have a look at the **Headline** Grid Editor.
As we can see the page is divided into two sections; one with a Text Editor with the code for the editor and one with a preview of the editor.
Let's take a look at the code.
A custom editor inherits from `HTMLElement` and must be the default export.
```javascript
export default class extends HTMLElement {
```
A couple of [private fields](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/Private_class_fields) are defined. One for storing a reference to the `textarea` field and one for the HTML template.
```javascript
#textarea
#template = ``
```
In the constructor we set the inner HTML of our custom element to our template and set the `#textarea` field to a reference to the textarea.
```javascript
constructor() {
super()
this.innerHTML = this.#template
this.#textarea = this.querySelector('textarea')
}
```
The `click` method is called when the grid control is clicked. In this case we use it to set focus on the textarea.
```javascript
click() {
this.#textarea.focus()
}
```
A `value` property is needed for the value to be stored when a page is saved and to set the value when the editor is loaded.
In this example the value property is setting and returning the value of the textarea.
```javascript
get value() { return this.#textarea.value }
set value(value) {
this.#textarea.value = value || ''
}
}
```
## Create a custom grid editor
For this tutorial we will create an image gallery editor using [Lit](https://lit.dev). Lit builds on top of the Web Components standards and helps us avoid a lot of boilerplate code.
* Go to the **Settings** section.
* Create a new **Grid Editor**.
* Choose an icon.
* Name it **Image Gallery**.
* Change the alias to `my-image-gallery`.
{% hint style="info" %}
The alias is used as the custom element tag name and must be unique. By choosing a prefix that is less likely to used by any other HTML element, in this case `my-`, there is less chance for running into conflicts.
{% endhint %}
In the `JS` view we can see there is already some boilerplate code. Let's replace it with the following:
```javascript
import { LitElement, css, html } from 'https://cdn.jsdelivr.net/gh/lit/dist@2/all/lit-all.min.js'
export default class extends LitElement {
static properties = {
value: { type: Array },
}
static styles = css`
.container {
display: grid;
grid-gap: 5px;
grid-template-columns: repeat(auto-fit, 200px);
padding: 5px;
}
.add-button {
font-family: var(--font-family-base);
font-size: var(--font-size-base);
line-height: var(--line-height-base);
cursor: pointer;
width: 200px;
height: 200px;
padding: 20px;
padding-bottom: 30px;
background-color: var(--color-white);
border: 4px dashed var(--color-gray-8);
text-align: center;
box-sizing: border-box;
}
.add-button svg {
display: block;
fill: var(--color-gray-8);
font-size: 85px;
line-height: 1;
display: inline-block;
height: 1.15em;
width: 1.15em;
margin: 10px auto;
}
.add-button div {
color: var(--color-black);
font-size: 14px;
font-weight: 700;
}
`
render() {
return html`
`
}
}
```
The preview should now look like this:
Let's break down the code.
```javascript
import { LitElement, css, html } from 'https://cdn.jsdelivr.net/gh/lit/dist@2/all/lit-all.min.js'
```
Here we're importing `LitElement`, CSS and HTML from the Lit library.
```javascript
export default class extends LitElement {
```
We're exporting a default class inheriting from `LitElement`.
```javascript
static properties = {
value: { type: Array },
}
```
We tell Lit that we have a `value` property which we expect to be an `Array`.
```javascript
static styles = css`
.container {
display: grid;
grid-gap: 5px;
grid-template-columns: repeat(auto-fit, 200px);
padding: 5px;
}
.add-button {
font-family: var(--font-family-base);
font-size: var(--font-size-base);
line-height: var(--line-height-base);
cursor: pointer;
width: 200px;
height: 200px;
padding: 20px;
padding-bottom: 30px;
background-color: var(--color-white);
border: 4px dashed var(--color-gray-8);
text-align: center;
box-sizing: border-box;
}
.add-button svg {
display: block;
fill: var(--color-gray-8);
font-size: 85px;
line-height: 1;
display: inline-block;
height: 1.15em;
width: 1.15em;
margin: 10px auto;
}
.add-button div {
color: var(--color-black);
font-size: 14px;
font-weight: 700;
}
```
We define the styles in a static field called `styles`. This will make Lit automatically inject a stylesheet into our custom element. The text returned needs to use the `css` tag from `Lit`. For more info see the [Lit styles documentation](https://lit.dev/docs/components/styles/).
```javascript
render() {
return html`
`
}
}
```
The render method returns the HTML we want to show. It needs to be tagged with `html`. For more info see the [Lit templates documentation](https://lit.dev/docs/templates/overview/).
Let's save the editor and see how it looks when adding it to the a content item.
We now have the **Add image** button rendering, but clicking it does nothing. Let's do something about that.
* Go back to the **Settings** section.
* Click on the **Image Gallery** Grid Editor.
We will start by adding the following to the top of the file:
```javascript
import { mediaPicker } from 'https://cdn.jsdelivr.net/npm/@umbraco/headless-backoffice-bridge@0/headless-backoffice-bridge.min.js'
```
This imports the `mediaPicker` function from the [backoffice bridge](https://github.com/umbraco/Umbraco.Headless.Backoffice.Bridge) library.
We will add another function before the `render` function:
```javascript
showPicker() {
mediaPicker.show({
disableFolderSelect: true,
onlyImages: true,
showDetails: true,
submit: (items) => {
const selected = items[0]
if(!this.value) this.value = []
this.value.push(({ url: selected.udi, ...selected }))
this.requestUpdate('value')
}
})
}
```
This will open the Media Picker with a configuration that only allows selecting images and showing the detail view, which allows us to enter an alt text, caption and choose a focal point.
The submit callback is called when the **Submit** is clicked. It will contain an array of the selected items. In this case it will contain a single item, but if we set `multiple` to `true` multiple items can be returned.
In our callback method we check if `this.value` has been initialized. If it has not we initialize a new array. We then push the selected image to the array. Note that we also store the `udi` (the id of the media) in a `url` property. We will come back to why we do that later.
Since we add to the array and do not set the `value` property we need to tell Lit that the property was updated. We do this by calling `this.requestUpdate('value')`.
We will also need to add a `click` event to the button so it will show the dialog:
```html