Battle scarred developer's guide to Umbraco v17 - Sections

#umbraco

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.