DEV Community: Yari Mariën

Adding Entity Actions to Trees in Umbraco 14

Yari Mariën — Mon, 14 Oct 2024 20:45:01 +0000

Introduction

In this post, we’ll build upon concepts from my previous post on Dynamic Routes and Views, where we explored how to create custom sections in Umbraco 14. Specifically, we’ll cover adding actions to trees using the Sidebar Context Menu.

Using Entity Actions

For this we can use the built-in Entity Actions. This feature automatically renders buttons for various actions directly within the sidebar context menu, providing a list of all possible actions relevant to the context.

Registering Actions

To register actions, you’ll need to create manifests of type ManifestEntityAction. When defining these, you must specify the forEntityTypes property, which determines which actions are available for each item type.

You can also define an api property, which specifies the logic that runs when the action is triggered.

manifest.ts:

const folderEntityActionManifest: Array<ManifestEntityAction> = [
    {
        type: 'entityAction',
        alias: 'deleteFolder',
        name: 'Delete Folder',
        kind: 'default',
        api: () => import('./menu-actions/folder/delete-folder-action.api.ts'),
        forEntityTypes: [FORMX_ENTITY_FOLDER_ALIAS],
        meta: {
            icon: 'icon-trash',
            label: 'Delete'
        },
    }
]

Rendering Actions

Actions can be rendered by adding a umb-entity-actions-bundle element in the action slot of a uui-menu-item. The entityType needs to match the one defined in the manifest, and the unique property represents the unique identifier of the item.

menu-items.ts:

<uui-menu-item>
    <umb-entity-actions-bundle
                            slot="actions"
                            .entityType=${element.type === 0 ? FORMX_ENTITY_FORM_ALIAS : FORMX_ENTITY_FOLDER_ALIAS}
                            .unique=${element.id}>
    </umb-entity-actions-bundle>
</uui-menu-item>

Action Logic

The functionality of an action is implemented in its corresponding api class, where you override the execute method. You can access the unique property of the selected menu item through this.args.unique.

On the end of the action logic we can dispatch an event to notify other components using actionEventContext.dispatchEvent(event). We can use this later to handle the output of the action.

In this case we can dispatch an UmbRequestReloadStructureForEntityEvent with entityType “FORMX”, because it doesn’t matter if the deleted item is a form or folder, the whole tree should be updated.

delete-folder-action.api.ts:

export class DeleteFolder extends UmbEntityActionBase<ManifestEntityActionDefaultKind> {
    override async execute() {
        // Use ModalManager to show a delete confirmation dialog
        console.log('Delete folder with id:', this.args.unique);

        const modalManager = await this.getContext(UMB_MODAL_MANAGER_CONTEXT);

        if(this.args.unique == null)
            throw new Error('Unique is required to delete folder');

        let id = parseInt(this.args.unique);

        const modal = modalManager.open(this, FORMX_DELETE_FOLDER_MODAL, {
            data: {
                id: id
            },
        });

        modal.onSubmit().then((data) => {
            console.log(`Response from modal: ${data}`);

            this.getContext(UMB_ACTION_EVENT_CONTEXT)
            .then((actionEventContext) => {
                const event = new UmbRequestReloadStructureForEntityEvent({
                    unique: this.args.unique,
                    entityType: "FORMX",
                });

                        //Dispatch an event
                actionEventContext.dispatchEvent(event);  
            })
        })
            .catch(() => {
            });
    }
}
export default DeleteFolder ;

Handling the Action Result

After the action is completed and the sidebar context menu is closed, the tree will not automatically refresh. However, we can listen for events being dispatched. So in this case we will listen for aUmbRequestReloadStructureForEntityEvent with entityType “FORMX”.

When the event is dispatched, fetch the tree items again and rerender the structure. Using the ?showChildren attribute, you can maintain the open state of tree items after the refresh.

constructor() {
    super();
    this.fetchTree(); // Start fetching on component load

    this.consumeContext(UMB_ACTION_EVENT_CONTEXT, (instance) => {
    this.#actionEventContext = instance;

        this.#actionEventContext?.removeEventListener(
        UmbRequestReloadStructureForEntityEvent.TYPE,
        this.#onReloadStructureRequest as unknown as EventListener,
    );

    this.#actionEventContext.addEventListener(
        UmbRequestReloadStructureForEntityEvent.TYPE,
        this.#onReloadStructureRequest as unknown as EventListener,
    );
});
}

#onReloadStructureRequest = async (event: UmbRequestReloadStructureForEntityEvent) => {
    if(event.getEntityType() == "FORMX"){
            //Handle rerender tree
        this.fetchTree();
    }
}

Next, I added an "Add" action, which will result in the following:

Adding Dynamic Routes to Umbraco 14 Sections

Yari Mariën — Mon, 07 Oct 2024 13:30:55 +0000

Introduction

In this post, I'll be building on concepts from my previous post, where we covered creating custom sections in Umbraco 14.

We'll focus on the following topics:

Adding routing to our section view
Creating a root page for our custom section
Displaying a detailed view when a tree item is clicked

Setting Up a Generic Section View

Adding a page behind a tree item is essential for adding functionality to our custom section. In this example, I'll demonstrate how to add a page to tree items of the type "Form." Upon clicking, a view containing a form builder will be displayed. For this, we’ll use a SectionView along with Umbraco's Router functionality.

Section View Manifest

We’ll use the same section view as in the previous example, but with updates. Specifically, we’ll add conditions so it's only rendered within our custom section and update the pathname to "forms", which will be reused across all routes.

manifest.ts:

const sectionViews: Array<ManifestSectionView> = [
    {
        type: "sectionView",
        alias: FORMX_CREATEFORM_SECTION_VIEW_ALIAS,
        name: "Create Form Section View",
        element: () => import('./form-section.ts'),
        meta: {
            label: "Create Form",
            pathname: "forms",
            icon: "icon-add"
        },
        conditions: [
            {
                alias: 'Umb.Condition.SectionAlias',
                match: FORMX_SECTION_ALIAS,
            }
        ]
    }
];

export const sectionViewsManifest = [...sectionViews];

Adding Routing

We'll use the form-section.ts component as a wrapper for all possible routes in our custom section. First, define an array of possible routes using UmbRoute. Each route will have a component and setup property, which we can use to load components and pass relevant properties.

In this example, I’ve added routes for a section root, create form, and edit form.

form-section.ts:

const element = "formx-section";
@customElement(element)
export class FormXSection extends UmbLitElement {

    #routes: UmbRoute[] = [
        {
                //Section & Tree root
            path: 'root',
            component: () => import('./form-section-root'),
        },
        {
                //Create form route
            path: 'create/:parentId',
            component: () => import('./form-section-create-form')
        },
        {
                //Edit form route
            path: 'edit/:id',
            component: () => import('./form-section-create-form')
        },
        {
                //Catch empty routes and redirect to root
            path: '',
            redirectTo: 'root',
        },
        {
                //Catch other routes and return to not Found
            path: `**`,
            component: async () => (await import('@umbraco-cms/backoffice/router')).UmbRouteNotFoundElement,
        },
    ];


//...

Next, pass the routes to an umb-router-slot to enable navigation.

form-section.ts:

render() {
    return html`
    <umb-router-slot id="router-slot" .routes=${this.#routes}></umb-router-slot>
`
}

Root Route

To set up the root route, we can use a simple Lit Element to display some basic information.

const element = "formx-section-root";

@customElement(element)
export class FormxSectionRoot extends UmbLitElement{
    protected render = () => {
        return html`<div>Form Section Root... Some information here.</div>`;
    }
}

export default FormxSectionRoot;

declare global {
    interface HTMLElementTagNameMap {
        [element]: FormxSectionRoot;
    }
}

When you navigate to the section, the root element will be displayed.

Setting Up Create & Edit Route Components

In this example, I’m using the same component for both the create and edit routes, enabling the form builder to be used for both scenarios.

The component has two key properties: editMode and idProp. The idProp is used for the parentId or formId, while editMode determines if the form is in create or edit mode. If editMode is true, idProp will contain the formId; otherwise, it will hold the parentId.

form-section-create-form.ts:

@customElement(element)
export class FormxSectionCreateForm extends UmbLitElement {

    //Id of the form or parent
    @property({ type: String })
    public idProp!: string;

    //If edit mode is enabled the id is the id of the form
    //If edit mode is disabled the id is the id of the parent
    @property({ type: Boolean })
    public editMode: boolean = false;

    @state()
    items: CreateFormField[] = [];

      private _parentId: number = -1; 
    private _id: number = 0;
    private _title: string = "Create Form";

    constructor() {
        super();
    }

//....

We can set the values of these properties using the setup property of the UmbRoute.

form-section.ts:

const element = "formx-section";
@customElement(element)
export class FormXSection extends UmbLitElement {

    #routes: UmbRoute[] = [
        {
                //Section & Tree root
            path: 'root',
            component: () => import('./form-section-root'),
        },
        {
                //Create form route
            path: 'create/:parentId',
            component: () => import('./form-section-create-form'),
            setup: (component, info) => {
                const element = component as FormxSectionCreateForm;
                element.idProp = info.match.params.parentId;
                element.editMode = false;
            }
        },
        {
                //Edit form route
            path: 'edit/:id',
            component: () => import('./form-section-create-form'),
            setup: (component, info) => {
                const element = component as FormxSectionCreateForm;
                element.idProp = info.match.params.id;
                element.editMode = true;
            }
        },
        {
                //Catch empty routes and redirect to root
            path: '',
            redirectTo: 'root',
        },
        {
                //Catch other routes and return to not Found
            path: `**`,
            component: async () => (await import('@umbraco-cms/backoffice/router')).UmbRouteNotFoundElement,
        },
    ];


//...

To capture the updated values, use the firstUpdated method.

form-section-create-form.ts:

  firstUpdated(): void {

      if(this.editMode){
          this._id = parseInt(this.idProp);
          this._title = "Edit Form";
      }
      else{
          this._parentId = parseInt(this.idProp);
          this._title = "Create Form";
      }

            //... Use values
  }

Adding Routing to the Tree

To add routing to the tree items, use the href attribute to navigate to the appropriate route.

//Type 0 === form
<uui-menu-item  href=${element.type == 0 ? `section/FormX/view/forms/edit/${element.id}` : ''}>
</uui-menu-item>

When a tree item is clicked, the edit component will be displayed.

Building Custom Trees in Umbraco 14 using menus!

Yari Mariën — Wed, 25 Sep 2024 15:01:51 +0000

Some Thoughts
Building Custom Menu Item Components
- Rendering Menu Items with Umbraco's UI Menu Item Component
- Example: Fetching and Rendering a Dynamic Tree
Manifests
- Defining the Tree Space with ManifestSectionSidebarApp
- Defining the Menu with ManifestMenu
- Linking the Custom Elements with ManifestMenuItem
Final Result

Some Thoughts

There are several methods to create custom trees. One approach is using a full Tree structure, which involves numerous components like ManifestTree, ManifestTreeItem, ManifestTreeStore, DataSource, Repository, and many more files.

However, I find this approach overly complex and unnecessary for small, simple trees.

For a basic tree with, I prefer using a menu with custom-rendered menu items using a custom Lit element, as I will demonstrate in this example.

Building Custom Menu Item Components

Rendering Menu Items with Umbraco's UI Menu Item Component

To render your menu items in Umbraco, you can make use of the powerful Umbraco UI Menu Item component. This component allows you to easily create nested menu structures with just a few lines of code.

Example:

<uui-menu-item label="Menu Item 1" has-children>
    <uui-menu-item label="Nested Menu Item 1"></uui-menu-item>
    <uui-menu-item label="Nested Menu Item 2"></uui-menu-item>
</uui-menu-item>

Example: Fetching and Rendering a Dynamic Tree

In this example, the entire tree is fetched when the component is rendered. Once the data is loaded, we put the items in a @state(). This will trigger a re-render of the tree because it is a reactive property.

With the retrieved data, I dynamically render nested menu items, each with relevant icons. The core functionality of the tree such as opening, closing, and indenting nodes comes from the menu item component itself.

To display the caret icon indicating nested items, you can set the has-children attribute dynamically like this: ?has-children=${bool}.

menu-items.ts:

import { UmbMenuItemElement } from '@umbraco-cms/backoffice/extension-registry';
import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element';
import { html, TemplateResult } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import { FormXTreeItemResponseModel, FormXTreeResource } from '../../../api';


const elementName = 'formx-menu-item';

@customElement(elementName)
class FormXMenuItems extends UmbLitElement implements UmbMenuItemElement {
    @state()
    private _items: FormXTreeItemResponseModel[] = []; // Store fetched items
    @state()
    private _loading: boolean = true; // Track loading state
    @state()
    private _error: string | null = null; // Track any errors

    constructor() {
        super();
        this.fetchInitialItems(); // Start fetching on component load
    }

    // Fetch initial items
    async fetchInitialItems() {
        try {
            this._loading = true;
            this._items = ((await FormXTreeResource.getFormxApiV1Tree()).items); // Fetch root-level items
        } catch (e) {
            this._error = 'Error fetching items';
        } finally {
            this._loading = false;
        }
    }

    // Render items
    renderItems(items: FormXTreeItemResponseModel[]): TemplateResult {
        return html`
            ${items.map(element => html`
                <uui-menu-item label="${element.name}" ?has-children=${element.hasChildren}>
                ${element.type === 1 
                ? html`<uui-icon slot="icon" name="icon-folder"></uui-icon>` 
                : html`<uui-icon slot="icon" name="icon-autofill"></uui-icon>`}
                    ${element.hasChildren ? this.renderItems(element.children) : ''}
                </uui-menu-item>
            `)}
        `;
    }

    // Main render function
    render() {
        if (this._loading) {
            return html`<uui-loader></uui-loader>`;
        }

        if (this._error) {
            return html`<uui-menu-item active disabled label="Could not load form tree!">
        </uui-menu-item>`;
        }

        // Render items if loading is done and no error occurred
        return html`${this.renderItems(this._items)}`;
    }
}



export { FormXMenuItems as element };

declare global {
    interface HTMLElementTagNameMap {
        [elementName]: FormXMenuItems;
    }
}

The result will be a menu that looks like the following:

Manifests

For this setup, you'll need three key manifests that work together to render a tree using a custom menu.

Let’s start by defining a reusable alias:

const FORMX_MENU_ALIAS = "Our.Umbraco.FormX.menu";

Defining the Tree Space with `ManifestSectionSidebarApp`

The first manifest defines the space where your tree will appear. This is achieved by creating a ManifestSectionSidebarApp. We can connect the menu to the sidebar using the menu alias.

const sidebarApps: Array<ManifestSectionSidebarApp> = [
    {
        type: 'sectionSidebarApp',
        kind: 'menuWithEntityActions',
        alias: 'Our.Umbraco.FormX.sidebar',
        name: 'FormX Sidebar App',
        meta: {
            label: "Forms",
            menu: FORMX_MENU_ALIAS
        },
        conditions: [
            {
                alias: "Umb.Condition.SectionAlias",
                match: "Our.Umbraco.FormX.section"
            }
        ]
    }
];

Defining the Menu with `ManifestMenu`

Next, you’ll define the actual menu where your items will be rendered. For this we can use a ManifestMenu.

const menuManifest: Array<ManifestMenu> = [
    {
        type: 'menu',
        alias: FORMX_MENU_ALIAS,
        name: 'FormX Menu'
    }
];

Linking the Custom Elements with `ManifestMenuItem`

Lastly, we need to link our custom elements that fetch and render your menu items. This is where the ManifestMenuItem comes in.

const menuItemManifest: Array<ManifestMenuItem> = [
    {
        type: 'menuItem',
        alias: 'formx-menu-items',
        name: 'FormX Menu Items',
        meta: {
            label: 'FormX',
            menus: [FORMX_MENU_ALIAS]
        },
        element: () => import('./menu-items.ts')
    }
];

Final Result

Once the SectionSidebarApp is linked to our custom section, the tree will be rendered with the specified label and custom elements.

Doing custom sections in Umbraco 14

Yari Mariën — Wed, 25 Sep 2024 15:01:32 +0000

Intro
Setting up a section
- Create a ManifestSection
Add a dashboard
- Create dashboard component
- Setup manifest
- Checking the result
Adding a tree
Add section view
- What are section views?
- Create section view web component
- Setup manifest
- Checking the result

Intro

I originally wrote a post about creating custom trees in Umbraco v14 because I struggled to make things work using the existing documentation.

I decided to share additional examples here for setting up sections with dashboards, trees, and sectionviews in Umbraco v14. I'll also work on getting this information added to the official documentation.

Setting up a section

Let’s create a custom section for the v14 backoffice.

We need a ManifestSection for this. Make sure to define the alias in an exported variable so it can be used throughout the application.

import { ManifestSection } from "@umbraco-cms/backoffice/extension-registry";

export const FORMX_SECTION_ALIAS = "Our.Umbraco.FormX.section";

const sections : Array<ManifestSection> = [
    {
        type: 'section',
        alias: FORMX_SECTION_ALIAS,
        name: 'FormX Section',
        weight: 10,
        meta: {
            label: 'FormX',
            pathname: 'FormX'
        }
    }
];

export const manifests = [...sections];

Once this component is registered and the application starts, you'll see the new section in the navigation.

Example of what the newly created section looks like.

Add a dashboard

Now let’s add a custom dashboard to the newly created section.

Create dashboard component

This basic web component will render a box element with a title and description.

import { UmbElementMixin } from "@umbraco-cms/backoffice/element-api";
import { LitElement, html, css, customElement, property } from "@umbraco-cms/backoffice/external/lit";

@customElement('our_umbraco_formx-dashboard')
export class Our_Umbraco_FormXDashboard extends UmbElementMixin(LitElement) {

    constructor() {
        super();
    }

    @property()
    title = 'Dashboard title goes here'

    render() {
        return html`
            <uui-box headline="${this.title}">
                Dashboard content goes here
            </uui-box>
        `
    }

        //Basic umbraco box spacing
    static styles = css`
        :host {
            display: block;
            padding: 20px;
        }
    `
}

export default Our_Umbraco_FormXDashboard;

declare global {
    interface HtmlElementTagNameMap {
        'Our.Umbraco.FormX-dashboard': Our_Umbraco_FormXDashboard
    }
}

Setup manifest

We can use the ManifestDashboard to add a dashboard and link it to the custom section via its alias. The js property links our custom element.

import type { ManifestDashboard } from "@umbraco-cms/backoffice/extension-registry";
import { FORMX_SECTION_ALIAS } from "../section/manifest.js";

const dashboards: Array<ManifestDashboard> = [
    {
        type: 'dashboard',
        name: 'FormX Dashboard',
        alias: 'Our.Umbraco.FormX.dashboard',
        elementName: 'our_umbraco_formx-dashboard',
        js: ()=> import('./dashboard.element.js'),
        weight: -10,
        meta: {
            label: 'FormX',
            pathname: 'FormX.Dashboard'
        },
        conditions: [
            {
                alias: 'Umb.Condition.SectionAlias',
                match: FORMX_SECTION_ALIAS
            }
        ]
    }
]

export const manifests = [...dashboards];

Checking the result

Once registered and running, the dashboard will be rendered in the section.

Adding a tree

For more information on adding trees, check out my other post.

Add sectionview

What are section views?

Section views are similar to content apps in earlier versions. They’re used to display additional features or information.

Create section view web component

This process is nearly identical to creating the dashboard component.

import { UmbLitElement } from "@umbraco-cms/backoffice/lit-element";
import { css, html, customElement, property } from '@umbraco-cms/backoffice/external/lit';

@customElement('our_umbraco_formx-create-form')
export class Our_Umbraco_FormX_CreateForm_SectionView extends UmbLitElement {

    @property()
    title = 'Sectionview title goes here'

    render() {
        return html`
            <uui-box headline="${this.title}">
                Sectionview content goes here
            </uui-box>
        `
    }

    static override styles = [
        css`
            :host {
                display: block;
                padding: 20px;
            }
        `,
    ];

}

export default Our_Umbraco_FormX_CreateForm_SectionView;

declare global {
    interface HTMLElementTagNameMap {
        'our_umbraco_formx-create-form': Our_Umbraco_FormX_CreateForm_SectionView;
    }
}

Setup sectionview manifest

To add a section view, we use ManifestSectionView. By linking the custom element, we can specify what content appears when the section view is opened.

We also define the button and route for the section view by setting the label, pathname, and icon.

import { ManifestSectionView } from "@umbraco-cms/backoffice/extension-registry";

export const FORMX_CREATEFORM_SECTION_VIEW_ALIAS = "Our.Umbraco.FormX.createform.sectionview";

const sectionViews: Array<ManifestSectionView> = [
    {
        type: "sectionView",
        alias: FORMX_CREATEFORM_SECTION_VIEW_ALIAS,
        name: "Create Form Section View",
        element: () => import('./create-form.element.ts'),
        meta: {
            label: "Create Form",
            pathname: "create-form",
            icon: "icon-add"
        }
    }
]

export const sectionViewsManifest = [...sectionViews];

Checking the sectionview result

After registering the section view, you'll see a new button at the top right where content apps used to be in older versions.

Clicking the button will display the custom Lit element.

DEV Community: Yari Mariën

Adding Entity Actions to Trees in Umbraco 14

Introduction

Using Entity Actions

Registering Actions

Rendering Actions

Action Logic

Handling the Action Result

Adding Dynamic Routes to Umbraco 14 Sections

Introduction

Setting Up a Generic Section View

Section View Manifest

Adding Routing

Root Route

Setting Up Create & Edit Route Components

Adding Routing to the Tree

Building Custom Trees in Umbraco 14 using menus!

Table of Contents

Some Thoughts

Building Custom Menu Item Components

Rendering Menu Items with Umbraco's UI Menu Item Component

Example: Fetching and Rendering a Dynamic Tree

Manifests

Defining the Tree Space with ManifestSectionSidebarApp

Defining the Menu with ManifestMenu

Linking the Custom Elements with ManifestMenuItem

Final Result

Doing custom sections in Umbraco 14

Table of Contents

Intro

Setting up a section

Add a dashboard

Create dashboard component

Setup manifest

Checking the result

Adding a tree

Add sectionview

What are section views?

Create section view web component

Setup sectionview manifest

Checking the sectionview result

Defining the Tree Space with `ManifestSectionSidebarApp`

Defining the Menu with `ManifestMenu`

Linking the Custom Elements with `ManifestMenuItem`