DEV Community: Kevin Jump

Battle scarred developer's guide to Umbraco v17 -Workspaces

Kevin Jump — Fri, 27 Feb 2026 09:50:36 +0000

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

In the last article we got to the point where we had our own custom section, with a side menu (or "sidebarApp") and a basic menu item.
but for now clicking on that menu item just shows us some loading dots 😞

What we need to do know is define a workspace.

So what are workspaces ? well to lift the description directly from the umbraco docs :

Workspaces provide dedicated editing environments for specific entity types in Umbraco. They create isolated areas where users can edit content, media, members, or other entities with specialized interfaces and functionality.

basically menu items are assigned an 'entity type' and when you click on them Umbraco looks for the workspace that renders that entity type.

entity types are really just Identifiers at this point, usually you might have in two entity types a 'root' and and 'item' - the root is as you might expect the one at the root, and the item is an item in your tree (if you have one.

Item workspace

For our "simple" time item, we only have a single "do-stuff-time-item" entity type, and that's the one we need to build a workspace for to show information to the user.

Workspaces at their most basic have two things, a workspace context and a workspace element.

Workspace Context

Your workspace context is the code that controls the state and data for your workspace. here you have all your data and ways to fetch and save it.

To be clear, you don't need to do this in a context, you can just fetch , store and manipulate data in the element, but as you will see in a bit, that is probably going to lead to duplication and a more complex bunch of code

So without being to complicated a workspace will look something like this:

export class MySampleWorkspaceContext 
  extends UmbEditableWorkspaceContextBase<TimeSettings>
  implements UmbSubmittableWorkspaceContext
{
  #settingsRepository = new DoStuffTimeSettingsRepository(this);
  readonly unique: Observable<string | null | undefined>;

  public readonly workspaceAlias = DOSTUFF_WORKSPACE_ALIAS;

  constructor(host: UmbControllerHost) {
    super(host, DOSTUFF_WORKSPACE_ALIAS);
    this.provideContext(DOSTUFF_WORKSPACE_CONTEXT, this);
  }

  getUnique() {
    return undefined;
  }

  getData() {
    return this.#timeSettings.value;
  }

  getEntityType() {
    return DOSTUFF_TIME_ITEM_ALIAS;
  }

  protected submit() {
    const settings = this.#timeSettings.value;
    if (!settings) return;
    await this.#settingsRepository.saveTimeSettings(settings);
  }
}

Workspaces can even be simpler than this, but here we are implementing a UmbSubmittableWorkspaceContext because we want to be able to save things that we update on our context, if you don't want to tie into other things like workspace actions, you don't need to do this, but its a relatively simple implementation, so in my opinion it's worth it.

There are few things we are going to pick out in the context :

ProvideContext

You can see that inside the constructor for the context we are calling this.provideContext . this tells the rest of the app, that we are responsible for the DOSTUFF_WORKSPACE_CONTEXT so if anything wants to interact with this context they can. by asking for it in their own constructor.

For example - a view might ask for the context like this.

this.consumeContext(DOSTUFF_WORKSPACE_CONTEXT, (context) => {
  // do stuff with the context here.
});

Workspace contexts have a scope, they will only exist while you are in the workspace, you can't call a workspace context from somewhere else or another section - if you need to do that you might need a global context, which work in a similar way they are just defined slightly differently

Repositories

Another thing you might have noticed about this context is we randomly just call save in a #settingsRepository and we've haven't told you what one of them is yet - we will get to them in a bit.

But for now, that's just the place where the actual calls to API end points and the like are stored - it means our context doesn't need to know the inner workings of the API it can just say go get this or save that.

Views

So now we have registered our workspace and we have a workspace context, you will notice, we still have nothing to show to our user! So now its time to fix that, and present them with something. You define what things show in a workspace via workspaceView elements.

again we define these in a manifest.

   type: "workspaceView",
    alias: "DoStuff.DefaultWorkspaceView",
    name: "DoStuff Default Workspace View",
    js: () => import("./default-workspace-view.element.js"),
    weight: 500,
    meta: {
      label: "#doStuff_defaultWorkspaceViewName",
      pathname: "default",
      icon: "icon-alarm-clock",
    },
    conditions: [
      {
        alias: "Umb.Condition.WorkspaceAlias",
        match: DOSTUFF_WORKSPACE_ALIAS,
      },
    ],
  },

So the things to note :

the js entry points the file that will render the element
the meta data defines the name and icon for the view
the conditions make sure our view only shows up on our workspace.

View element

The view element is a UmbLitElement that renders what you want to show the user

@customElement("do-stuff-default-workspace-view-element")
export class DoStuffDefaultWorkspaceViewElement extends UmbLitElement {

  override render() {
    return html`<umb-body-layout>
      <div class="layout">
        <uui-box
          .headline=${this.localize.term("doStuff_defaultWorkspaceTitle")}
        >
          <h1>Hello Time</h1>
        </uui-box>
      </div>
    </umb-body-layout>`;
  }
}

With this in place we get something to show the user !

Multiple views, and icons.

So we defined that icon, and name, but it's not anywhere on the screen, what's up with that?.

Well the icon and name are used when we have multiple views in a workspace. so if we add another workspaceView manifest to the workspace

{
  type: "workspaceView",
  alias: "DoStuff.SettingsWorkspaceView",
  name: "DoStuff Settings Workspace View",
  js: () => import("./settings-workspace-view.element.js"),
  weight: 200,
  meta: {
    label: "#doStuff_settingsWorkspaceViewName",
    pathname: "settings",
    icon: "icon-settings",
  },
  conditions: [
    {
      alias: "Umb.Condition.WorkspaceAlias",
      match: DOSTUFF_WORKSPACE_ALIAS,
    },
  ],
},

We get our 'tabs'

Summarry

This gets us the skeleton of our workspace up and showing something to the user - there is much more to workspaces , and we will go into them in some later posts, but for now, we have a section, a menu and some workspaces. so 🎉

Battle scarred developer's guide to Umbraco v17 - Sections

Kevin Jump — Wed, 25 Feb 2026 17:21:17 +0000

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

1. Sections

(see DoStuffWithUmbracoRepo : Sections)

A section in umbraco is something accessed from the top bar navigation menu.

Its quite simple to add a new section - all you need is the manifest.

const sectionManifest: UmbExtensionManifest = {
  type: "section",
  alias: DOSTUFF_SECTION_ALIAS,
  name: "DoStuff Section",
  weight: 10,
  meta: {
    label: "#doStuff_sectionName",
    pathname: "do-stuff",
  },
};

Constants
Here we have used a constant for the alias, because its often true you will need to reference the section alias in other places on your site.

The alias is defined in another file.
export const DOSTUFF_SECTION_ALIAS = "DoStuff.Section";
and this replaces the string value in the manifest.

Localization
You might also notice that the label value starts with a '#', this tells umbraco that we want to use a localize value for the label. we will cover them a bit later, but for now just to so you know you can just put a string in for the label value if you want

2. Dashboard

(see DoStuffWithUmbraco repo : Dashboards)

At this point your section is quite empty, but you can add a dashboard quite easily to get some content in there.

Dashboards are pages that sit at the top level of a section, almost all the sections in umbraco already have dashboards (Content has news, and redirect, settings has, examine, health checks and profiling to name a few).

you can add your own dashboard to your own sections or existing sections as you choose.

const dashboardManifest: UmbExtensionManifest = {
  type: "dashboard",
  alias: "DoStuff.Dashboard",
  name: "DoStuff Dashboard",
  js: () => import("./dashboard.element.js"),
  meta: {
    label: "#DoStuff_DashboardName",
    pathname: "do-stuff-dashboard",
  },
  conditions: [
    {
      alias: "Umb.Condition.SectionAlias",
      match: DOSTUFF_SECTION_ALIAS,
    },
  ],
};

Here we define the alias and element we want to use for our dashboard, and the condition determines where it lives.

there are all sorts of conditions in umbraco, but here we are saying if the section alias is that of our custom section then we are happy. If we didn't have a condition the dashboard would appear in all sections

Again note the use of a constant for the section alias_

Dashboards are WebComponents, they are probibly the simplest ones in umbraco you don't have to inherit anything (if you don't want to) - there are no contexts, or stores or tree's required, you element can just render some HTML.

@customElement("do-stuff-dashboard-element")
export class DoStuffDashboardElement extends UmbLitElement {
  override render() {
    return html`<umb-body-layout
      .headline=${this.localize.term("doStuff_dashboardTitle")}
    >
      <uui-box>
        <umb-localize key="doStuff_dashboardIntro"></umb-localize>
      </uui-box>
    </umb-body-layout>`;
  }
}

export default DoStuffDashboardElement;

Note : We do inherit from UmbLitElement as opposed to LitElement, this gives you access to the localization helpers amongst other things, so it's worth doing, even though you don't have to.

3. Sidebar App.

You have probibly notices that almost all existing sections in umbraco have some form of menu or tree down the left hand side. In Umbraco speak this is a "SidebarApp" and it can contain almost anything! - but usually its menu items and trees.

A sidebar is registered in a manifest file.

const sidebarManifest: UmbExtensionManifest = {
  type: "sectionSidebarApp",
  kind: "menu",
  alias: "DoStuff.SectionSidebarApp",
  name: "DoStuff Section Sidebar App",
  meta: {
    label: "#doStuff_sidebarStaticAppName",
    menu: "DoStuff.Static.Menu",
  },
  conditions: [
    {
      alias: "Umb.Condition.SectionAlias",
      match: DOSTUFF_SECTION_ALIAS,
    },
  ],
};

On its own a sidebar app is quite empty.

So we need to add some menus and items.

4. Menus

Within a standard sidebar you can have a number of 'menus' these are the sections you see in the settings section, "Structure", "Templating" and "Advanced" are Menus

to add your own, we have a manifest.

const menuManifest: UmbExtensionManifest = {
  type: "menu",
  alias: "DoStuff.Static.Menu",
  name: "DoStuff Static Menu",
};

but with out any menu items you won't see much , so lets add a menu item.

const timeItemManifest: UmbExtensionManifest = {
  type: "menuItem",
  alias: "DoStuff.TimeItem",
  name: "DoStuff Time Item",
  weight: 10,
  meta: {
    label: "#doStuff_timeItemName",
    icon: "icon-time",
    entityType: DOSTUFF_TIME_ITEM_ALIAS,
    menus: ["DoStuff.Static.Menu"],
  },
};

You can see how we assign the menu item to the menu, and the menu is actually assigned in the section definition.

Don't worry to much about the entityType just yet, its going to get funky when we talk about workspaces. but for now lets just bask in the menu glory.

All the client code in this article is available in the DoStuffWithUmbraco Client repo

Battle scarred developer's guide to Umbraco v17 - Entry Points

Kevin Jump — Wed, 25 Feb 2026 17:21:02 +0000

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

So now that bundles have replaced entry points as the place to integrate your Umbraco extension, do we still need entry points?

Yes, i most cases you will still need an entry point, to initialize things like the authentication for your client to talk to the server. or if you are feeling really mischievous to unload other entries from the umbraco registry !

Register your entry point via a manifest.

all the extension template will do this one for you, but to show the process

export const manifests: Array<UmbExtensionManifest> = [
  {
    name: "Do Stuff Client Entrypoint",
    alias: "DoStuff.Client.Entrypoint",
    type: "backofficeEntryPoint",
    js: () => import("./entrypoint.js"),
  },
];

this is then imported and registered via your bundle.manifest.ts file.

Auth.

The examples that you get with the templates contain most of the code you will need here for authentication.

 _host.consumeContext(UMB_AUTH_CONTEXT, async (authContext) => {
    // Get the token info from Umbraco
    const config = authContext?.getOpenApiConfiguration();

    client.setConfig({
      auth: config?.token ?? undefined,
      baseUrl: config?.base ?? "",
      credentials: config?.credentials ?? "same-origin",
    });
  });
};

As we've said in another post we like to add a bit - which keeps the token fresh for each request.

    // client interceptor will get the latest token for the auth
    // context for a request, so if the token has been refreshed
    // since we first got it, we'll still have a valid token.
    client.interceptors.request.use(async (request, _options) => {
      const token = await authContext?.getLatestToken();
      request.headers.set("Authorization", `Bearer ${token}`);
      return request;
    });

honesty - i am not 100% sure this extra bit is in fact needed - it's something we might revisit.

Unregistering things!

So your onInit method runs when your extension is loaded, and you can if you want start to manipulate Umbraco's register, you could for example remove the welcome dashboard this way.

extensionRegistry.unregister('Umb.Dashboard.UmbracoNews');

Be carefull! removing things from the register might well make bits of the umbraco backoffice unstable.

Battle scarred developer's guide to Umbraco v17 - Bundles

Kevin Jump — Wed, 25 Feb 2026 17:20:52 +0000

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

With the Early adopters guide we talked about Entry points as the start of your front end code journey, but now with a few tweaks since v14 bundles are where it's at.

What's a bundle.

A bundle is an extension point in Umbraco's Backoffice that lets you load JavaScript files and register manifests inside Umbraco's system so your code is loaded as part of the Backoffice.

Put simply it's the loader of your extension.

typically your entry point javascript file will only import manifest from around your project and return them for umbraco to ingest.

export const manifests: Array<UmbExtensionManifest> = [
  ...entrypoints,
  ...sectionManifests,
  ...dashboardManifests,
  ...localizationManifests,
  ...menuManifests,
  ...workspaceManifests,
  ...editorManifests,
  ...modalManifests,
];

As your project grows so will this list, to keep it simple and organised i would recommend that at each level you have manifest that might also import from child folders, before finally having everything brought into the bundle file.

For example in the DoStuffWithUmbraco repository. we might have a /workspaces/views/manfiest.ts file, that is then imported into the /workspace/manifest.ts file which is the one we import into our bundle file.

+-- src
  - bundle.manifest.ts
  +-- workspaces
    - manifest.ts
    +-- views
      - manifest.ts

This means everything needed for the workspace is in /workspace/manifest.ts and we can if need be move it about knowing it's all there. It also means any one manifest definition file doesn't contain two much information.

What about manifests in umbraco-package.json

There is quite a bit in the umbraco docs about how you can define your manifests inside the umbraco-package.json file, and you can, but once you go beyond something very very basic (e.g. not just adding localization). you will want to do it via a bundle.

Adding all the manifests via the bundle gives you better typescript & checking support in your project, its neater and it catches the errors quicker.

Adding via the umbraco-package.json also requires that the site be restarted for the packages to be loaded (these files are read in by the Backoffice code on start-up). using a bundle as the entry point you can add new things build the scripts and it all appears.

Battle scarred developer's guide to Umbraco v17 - Setup

Kevin Jump — Wed, 25 Feb 2026 17:20:43 +0000

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

In our previous post we've gotten our basic structure for our umbraco extension, but before we dive into code. there are a couple things i like to tweak.

You can choose to ignore this post!, these are my personal preferences for some of the more obscure bits of the setup, they are not required but they can make things a bit easier later on.

PackageManifestReader vs umbraco-package.json

umbraco-package.json

When you create a new umbraco extension you will get a umbraco-package.json file created in your client/public folder. this file defines the entry point for Umbraco to fetch and initialize your package

{
  "id": "MySuperPackage",
  "name": "MySuperPackage",
  "version": "0.0.0",
  "allowTelemetry": true,
  "extensions": [
    {
      "name": "My Super Package Bundle",
      "alias": "MySuperPackage.Bundle",
      "type": "bundle",
      "js": "/App_Plugins/MySuperPackage/my-super-package.js"
    }
  ]
}

and this works fine - but it has one or two issues.

1. the version number is just sitting there in a json file.
This can be a pain, because what happens when you release a new version ?well you either have to change this value or run some form of build script to change it for you.

2. the JavaScript file never changes and might be cached between releases
Because the main JavaScript file is in this file it doesn't change between releases, this means if someone updates your package to a new version this file URL is still the same and their browser might not fetch the newer version from the server.

IPackageManaifestReader

Another alternative is to use a IPackageManifestReader (https://dev.to/skttl/server-side-registering-of-package-manifest-in-umbraco-14-49go by @skttl) which allows you to register your package via your backend code (see DoStuffPackageManifestReader.cs

public Task<IEnumerable<PackageManifest>> ReadPackageManifestsAsync()
{
  var version = Assembly.GetAssembly(typeof(DoStuffPackageManifestReader))?
   .GetName()
   .Version?.ToString() ?? "1.0.0";

  return Task.FromResult<IEnumerable<PackageManifest>>(new[]
  {
    new PackageManifest
    {
      Id = "DoStuff.Client",
      Name = "DoStuff with Umbraco client",
      AllowTelemetry = true,
      Version = version,
      Extensions = [
        new {
          name = "DoStuff Client Bundle",
          alias = "DoStuff.Client.Bundle",
          type = "bundle",
          js = "/App_Plugins/DoStuffClient/do-stuff-client.js?v=" + version
        }
     ]
   }
  });
}

You can see there is a little bit more code here but the basic information is the same as the umbraco-package.json file.

The key difference is we can fetch the version from the running assembly(dll).

When you build your NuGet packages of your extension the version will be stamped on the dll's in the package by NuGet's pack process. and once its there the code in your IPackageManifestReader will use that version value to update your package version and add it to the end of the JavaScript file's URL. meaning for each new version the browser will fetch the file again.

You need to remember to register your package manifest in a composer
builder.Services
  .AddSingleton<IPackageManifestReader, DoStuffPackageManifestReader>();

Entry points Auth.

Another change that we will go into more detail in, when we talk about entry points and APIs is the code for setting up the authentication between sites.

if you use the opinionated starter kit (or the umbraco-extension with the `-ex' flag) you will get the skeleton of the code for communicating with the server from your font end code.

`ts
_host.consumeContext(UMB_AUTH_CONTEXT, async (authContext) => {
// Get the token info from Umbraco
const config = authContext?.getOpenApiConfiguration();

client.setConfig({
auth: config?.token ?? undefined,
baseUrl: config?.base ?? "",
credentials: config?.credentials ?? "same-origin",
});
});
`

This is fine and it works - but from a bit of experience there is another bit you can add, that helps to keep things fresh should you have the browser open all day

ts // client interceptor will get the latest token for the auth // context for a request, so if the token has been refreshed // since we first got it, we'll still have a valid token. client.interceptors.request.use(async (request, _options) => { const token = await authContext?.getLatestToken(); request.headers.set("Authorization",Bearer ${token}); return request; });
A client interceptor will run when the requests are fired and just make sure you have the latest token from the user send over as part of the request.

Again this isn't something you have to do, everything works fine in the examples, this just smooths the odd edge I have seen during development.

Battle scarred developer's guide to Umbraco v17 - Getting Started

Kevin Jump — Wed, 25 Feb 2026 17:20:29 +0000

All the code for this series of posts is available in the DoStuffWithUmbraco Repository on GitHub

umbraco-extensions

If you are starting out on a new umbraco extension or package you will probably want to start with the umbraco-extension template that comes as part of the Umbraco templates.

So if you haven't already you will want the Umbraco templates

dotnet new install Umbraco.Templates@17.*

and once you have these templates installed you 'could' just run the umbraco extension.

dotnet new umbraco-extension -n MySuperNewUmbracoPackage

and this will crate you a new package to pay about with, but at this point you won't have an Umbraco site just an extension, so you will probably want to think about that.

Opinionated starter kit template.

if you actually want to have a site and a bit more structure around your development then you might want to consider @lottepitcher's Opinionated starter kit template, this adds stuff around the edges of the standard umbraco-extension, such as a test site, GitHub scripts and umbraco-marketplace files which will help when you come to release your super package.

You can install the templates for the Opinonated starter kit like so:

dotnet new install Umbraco.Community.Templates.PackageStarter

you can then start a new project

dotnet new umbracopackagestarter -n MySuperPackage

after this you get your extension and a test site, and scripts all nicely laid out for you.

Project Structure

For the DoStuffWithUmbraco repository that we are using as a reference for these blog posts you will notice there are a few slight differences with both the umbraco-extensions and the opinionated starter kit.

These changes are not major, and for the most part you can ignore them, but for information we have laid the project out like so.

+-- src
  +-- DoStuff
  +-- DoStuff.Client
  +-- DoStuff.Core
+-- demo
  +-- DoStuff.Website

DoStuff.Client

Client contains all the "front end" code and API controllers for the extension to render inside Umbraco. There is no real 'business logic' inside this layer, it's the UI and the c# code required to get data to the UI.

DoStuff.Core

The core project contains the backend logic for the application - this is where services, repositories, data layers etc all live. we sperate this out from the client, because then well it's separate and we can in theory use the core logic of our code without the front end, or on a different front end should it ever change 😧

DoStuff

The parent to all of these projects is the 'DoStuff' library - no really this has no code it in, but it would be the library that became the NuGet package that people would install (if we made the library a package).

The "DoStuff" has dependencies on the .Client and .Core projects so when someone would install the "DoStuff" NuGet package that would also fetch the client and the core.

DoStuff.Website

Our website is off in a 'demo' folder, just so we can have it separate from our project. If this wasn't a reference library we would probably exclude the 'demo' folder from the source repository, then the site is independent of our package's code.

Battle scarred developer's guide to Umbraco v17 - Intro

Kevin Jump — Wed, 25 Feb 2026 17:20:19 +0000

Introduction

It's almost two years now since I wrote a quite large series of blog posts about the then very new umbraco Backoffice.

The early adopters' guide to the Umbraco Backoffice was really just a way for me to write down my thoughts and discoveries as I started the process of moving our packages to the brave new world.

As it turned out quite a few people found those posts useful, and they are still being referenced by people today (the Umbraco.AI Skills even use them), but you can learn a lot in two years and Umbraco has gone from v14 to v17, and there has been loads of refinements and tweaks. as such the early adopters guide series are good, but they could be a lot better.

So - now that we've come out of the other side of two years of upgrading and developing packages for the "new" Umbraco back office, I thought it was time to dust off the code and re-visit the guides.

So today, we are starting the "Battle scarred developer's guide to Umbraco v17" - this is a series of blog posts aimed at package and extension developers - giving them a leg up for a quick start, and tips and tricks on how to do things 'right'

It's also worth noting the Umbraco documentation has also improved greatly since we did the first round of posts - so you should check out https://docs.umbraco.com/umbraco-cms/customizing/overview it may already tell you what you need to know.

All of the code referenced in these blogs is available via GitHub:
https://github.com/KevinJump/DoStuffWithUmbraco/tree/v17/main

EarlyAdopter's Guide Umbraco v14 - Updates - typescript codegen tool.

Kevin Jump — Wed, 10 Apr 2024 15:11:28 +0000

Most of the Early adopter posts were written against, preview releases of Umbraco and several small things have changed since then.

Where possible I have gone back into the original posts and made a note of the change. This post details a change since those early releases.

Codegen changes.

All credit to @leekelleher for this, there has been an update to the codegen tool - read the PR in the core umbraco project

In the early releases we were using openapi-typescript-codegen library to generate the typescript libraries for our c# api.

this library is being deprecated in May 2024, so the core team have switched over to Hey API's fork of this tool.

there are some little changes in the commands (and some switches are being deprecated) - but in general it's a direct swap, our generate command now looks like this:

"scripts": {
  "generate": "openapi-ts 
      --input http://localhost:123/umbraco/swagger 
      --output src/api 
      --debug true
      --enums typescript 
      --lint true 
      --schemas false"
}

n.b you might have to turn this back into a single line in the package.json file

code changes.

really there are nearly no code changes switching to this library.

the new library is deprecating the postfixServices command which in our examples we used to make our resulting classes end with 'Resource' (e.g timeResource).

you can still use this today, but it will be removed shortly from the new tool.

With this option removed all of the resources will now be 'services' (e.g timeService). so a rename of that will be required in any code you are upgrading to the new codegen tool.

Umbraco 14 - "Authing" your extensions.

Kevin Jump — Sat, 02 Mar 2024 19:07:45 +0000

We covered how to get Umbraco 14, Front->Backend Authentication working in our Umbraco Early Adopters series, in that we suggested you can add the auth code to your context(s) to ensure your instance of the openAPI model matches.

But in conversation with quite a few people, both in the community and the core team, esp. @mattbrailsford & @iovergaard , its certainly neater, cleaner, and better to put this in your entry point. then it happens once, for all your extension/contexts, and it happens when everything is loaded.

So. as an example, entry point we know have:

import { UmbEntryPointOnInit }
  from '@umbraco-cms/backoffice/extension-api';
import { UMB_AUTH_CONTEXT } 
  from '@umbraco-cms/backoffice/auth';
import { OpenAPI } 
  from './api/index.ts';

// load up the manifests here.
import { manifests as dashboardManifests }
  from './dashboards/manifest.ts';

export const onInit: UmbEntryPointOnInit 
   = (_host, extensionRegistry) => 
{

    // register manifests here. 
    extensionRegistry.registerMany([
        ...dashboardManifests,
    ]);

    // setup OpenAPI Token here
    _host.consumeContext(UMB_AUTH_CONTEXT, (_auth) => {
        const umbOpenApi = _auth.getOpenApiConfiguration();
        OpenAPI.BASE = umbOpenApi.base;
        OpenAPI.TOKEN = umbOpenApi.token;
        OpenAPI.WITH_CREDENTIALS = umbOpenApi.withCredentials;
        OpenAPI.CREDENTIALS = umbOpenApi.credentials;
    });

};

Early Adopter's guide to Umbraco v14 - Trees

Kevin Jump — Wed, 21 Feb 2024 12:32:43 +0000

We've finnaly gotten to trees. A topic i've been putting off.

because building custom trees in Umbraco has a lot of moving parts I've splt this off into its own series.

EarlyAdopter's Guide Umbraco v14 - Trees Series

Early Adopter's guide to Umbraco v14 [Trees] - Manifests

Kevin Jump — Wed, 21 Feb 2024 12:29:26 +0000

Now, we have hopefully created all the bits of code we need to render the tree in the backoffice.

Code for these posts is avalible in our TimeDashboard Repository FrontEnd (typescript) & Backend (c#)

we now have to define it in a series of manifests so Umbraco knows how and where to render it in the backoffice.

Some constants

There is a lot of cross referencing when setting up a tree, so its best to define things like aliases upfront so you don't get a typo.



export const TIME_TREE_REPOSITORY_ALIAS = 'Time.Tree.Repository';
export const TIME_TREE_STORE_ALIAS = 'Time.Tree.Store';
export const TIME_TREE_ALIAS = 'Time.Tree';
export const TIME_TREE_MENU_ALIAS = 'time.menu';

Manifest TreeRepository



const treeRepository : ManifestRepository = {
    type: 'repository',
    alias: TIME_TREE_REPOSITORY_ALIAS,
    name: 'Time Tree repository',
    api: TimeTreeRepository
};

Manifest : Tree Store



const treeStore: ManifestTreeStore = {
    type: 'treeStore',
    alias: TIME_TREE_STORE_ALIAS,
    name: 'Time tree Store',
    api: TimeTreeStore
};

Manifest : Tree & root

Now we define the tree and root item.



const tree: ManifestTree = {
    type: 'tree',
    alias: TIME_TREE_ALIAS,
    name: 'Time tree',
    meta: {
        repositoryAlias: TIME_TREE_REPOSITORY_ALIAS
    }
};

and the root tree item.



const treeItem: ManifestTreeItem = {
    type: 'treeItem',
    kind: 'unique',
    alias: 'Time.Tree.RootItem',
    name: 'Time Tree Item',
    meta: {
        entityTypes: [
            TIME_TREE_ROOT_ITEM_TYPE,
            TIME_TREE_ITEM_TYPE
        ]
    }
}

The menu & item.

Now i am not 100% sure you need all of this, but defining the menu and the menu item tell Umbraco which workspace to put your tree in, and without this, your tree isn't going to appear.

We previously setup a menu in the sectionBarApp post for completness. it looks like this.



const menu: ManifestMenu = {
    type: 'menu',
    alias: TIME_TREE_MENU_ALIAS,
    name: 'Time Tree Menu',
    meta: {
        label: 'Times'
    }
}

note : the menu is referenced in the sidebar app, which what makes it appear in Umbraco

For our tree we need to define a menu item that is the hook for our tree into the wider umbraco system.



const menuItem:  ManifestTypes = {
    type: 'menuItem',
    kind: 'tree',
    alias: 'Time.Tree.MenuItem',
    name: 'Time Tree Menu Item',
    weight: 400,
    meta: {
        label: 'Times',
        icon: 'icon-alarm-clock',
        entityType: TIME_TREE_ITEM_TYPE,
        menus: [TIME_TREE_MENU_ALIAS],
        treeAlias: TIME_TREE_ALIAS,
        hideTreeRoot: false
    }
};

And fingers crossed we are back where we started with a tree in Umbraco...

What we don't have yet is anything happening when you click on the nodes, but... that is workspaces, and views, which we have covered before.....

Code for these posts is avalible in our TimeDashboard Repository FrontEnd (typescript) & Backend (c#)

Early Adopter's guide to Umbraco v14 [Trees] - Repositories

Kevin Jump — Wed, 21 Feb 2024 12:29:14 +0000

Once we have our data out in to a datasource, we can add it to our repository pattern and we are soooo nearly there !

Code for these posts is avalible in our TimeDashboard Repository FrontEnd (typescript) & Backend (c#)

Tree Repository.

Again to save on so much code, we are extending an umbraco UmbTreeRepositoryBase class.

This class takes our item/entity models. which is why we set them up first.

export class TimeTreeRepository extends 
    UmbTreeRepositoryBase<TimeTreeItemModel, TimeTreeRootModel>
    implements UmbApi

in our constructore we pass our datasource, and a refernce to the store context.

    constructor(host: UmbControllerHost) {
        super(host, TimeTreeServerDataSource, TIME_TREE_STORE_CONTEXT);
    }

The all we have to do is prodivde a requestTreeRoot method to return our tree route model

    async requestTreeRoot() {

        const data: TimeTreeRootModel = {
            unique: null,
            entityType: TIME_TREE_ROOT_ITEM_TYPE,
            name: 'time',
            hasChildren: true,
            isFolder: true,
        };

        return { data };

    }

now we have a repo, we are set to define everything....