Doing custom sections in Umbraco 14

Table of Contents

1. Intro
2. Setting up a section
   • Create a ManifestSection
3. Add a dashboard
   • Create dashboard component
   • Setup manifest
   • Checking the result
4. Adding a tree
5. 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.

Comments

[Dalton]

Thanks for this, the official documentation on this really sucks right now.