diff --git a/16/umbraco-cms/.gitbook/assets/sections-assigning.png b/16/umbraco-cms/.gitbook/assets/sections-assigning.png new file mode 100644 index 00000000000..bad7898e2ac Binary files /dev/null and b/16/umbraco-cms/.gitbook/assets/sections-assigning.png differ diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md index 49c73872256..498954cfad1 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/README.md @@ -1,6 +1,6 @@ --- description: >- - An overview of the available extension types related to sections. + A comprehensive summary of the available extension types associated with sections. --- # Extension Types: Sections diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md index ed0b739f634..98affff72c5 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-sidebar.md @@ -1,79 +1,158 @@ +--- +description: >- + Use Section Sidebar extensions to add navigation, coordinate Section Views, and provide additional functionality inside Section extensions. +--- + # Section Sidebar -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} +[Section extensions](./section.md) can add a Section Sidebar to add navigation, coordinate subviews such as +[Section View extensions](./section-view.md), and provide Section-wide functionality. + +Section Sidebar extensions are optional; if not defined, the Section extension defaults to a single full-screen subview.

Section Sidebar

-## Section Sidebar Apps +## Section Sidebar Apps + +Section Sidebar extensions can be composed of **one or more** section sidebar apps. Extension authors can include common Umbraco types, such as menus and trees, or create custom sidebar apps using web components.

Section Sidebar Apps

-**Manifest** +### Custom Sidebar App Example -```typescript -{ - "type": "sectionSidebarApp", - "alias": "My.SectionSidebarApp", - "name": "My Section Sidebar App", - "conditions": [ - { - "alias": "Umb.Condition.SectionAlias", - "match": "My.Section" - } - ] -} -``` +Section Sidebar extension authors can place any custom web component into the sidebar. Extension authors will need to +supply the `element` property with the path of their custom web component. Specify the full path, starting from the +Umbraco project root. -**Default Element** +Sidebar Section extension authors may specify where the Section Sidebar app appears using +[extension conditions](../condition.md). -```typescript -interface UmbSectionSidebarAppElement {} +{% code title="umbraco-package.json" %} +```json +{ + "type": "sectionSidebarApp", + "alias": "My.SectionSidebarApp", + "name": "My Section Sidebar App", + "element": "/App_Plugins//sidebar-app.js", + "conditions": [{ + "alias": "Umb.Condition.SectionAlias", + "match": "My.Section" + }] +} ``` +{% endcode %} -## **Menu Sidebar App** - -**Sidebar Menu**: +### Menu Sidebar App Examples -* The Backoffice comes with a menu sidebar app that can be used to create a menu in the sidebar. -* The menu sidebar app will reference a menu that you have registered in the menu with a menu manifest +The menu sidebar app, provided by Umbraco, can be placed in Section Sidebar extensions. It attaches to a menu defined in your manifest via the `meta:menu` property, where this value must match the `alias` value of the menu.

Menu Sidebar App

-To register a new menu sidebar app, add the following to your manifest (notice the added `"kind"` and `"meta"` properties): - -**Manifest** - -```typescript +{% code title="umbraco-package.json" %} +```json { - "type": "sectionSidebarApp", - "kind": "menu", - "alias": "My.SectionSidebarApp.MyMenu", - "name": "My Menu Section Sidebar App", - "meta": { - "label": "My Sidebar Menu", - "menu": "My.Menu" - }, - "conditions": [ - { - "alias": "Umb.Condition.SectionAlias", - "match": "My.Section" - } - ] + "type": "sectionSidebarApp", + "kind": "menu", + "alias": "My.SectionSidebarApp.MyMenu", + "name": "My Menu Section Sidebar App", + "meta": { + "label": "My Sidebar Menu", + "menu": "My.Menu" + }, + "conditions": [{ + "alias": "Umb.Condition.SectionAlias", + "match": "My.Section" + }] } ``` - -**Default Element** - -```typescript -interface UmbMenuSectionSidebarAppElement {} +{% endcode %} + +In the example below, a menu extension is created and bound to the `meta:menu` (My.Menu) property, which matches the menu extension’s `alias`. The _My.Menu_ alias is also used to attach a menu item extension. + +{% code title="umbraco-package.json" %} +```json +[ + { + "type": "menu", + "alias": "My.Menu", + "name": "Section Sidebar Menu" + }, + { + "type": "menuItem", + "alias": "SectionSidebar.MenuItem1", + "name": "Menu Item 1", + "meta": { + "label": "Menu Item 1", + "menus": ["My.Menu"] + } + } +] ``` +{% endcode %} + +For more information, see the documentation for the [menus](../menu.md) extension. + +#### Coordinating subviews with menu items + +Menu sidebar apps can coordinate navigation between subviews in the section extension by referencing +[workspace extensions](../workspaces/workspace.md). Modify the menu item extension to include the `meta:entityType` +property, and assign it the same value as a workspace view extensions' own `meta:entityType` property. + +{% code title="umbraco-package.json" %} +```json +[ + { + "type": "menuItem", + "alias": "SectionSidebar.MenuItem1", + "name": "Menu Item 1", + "meta": { + "label": "Menu Item 1", + "menus": ["My.Menu"], + "entityType": "myCustomWorkspaceView" + } + }, + { + "type": "workspace", + "name": "Workspace 1", + "alias": "SectionSidebar.Workspace1", + "element": "/App_Plugins//my-custom-workspace.js", + "meta": { + "entityType": "myCustomWorkspaceView" + } + } +] +``` +{% endcode %} -**Adding Items to an existing menu** +#### Adding items to an existing menu -This will make it possible to compose a sidebar menu from multiple Apps: +Authors can add their extensions to the sidebar of any Umbraco-provided section (Content, Media, Settings, etc.) by configuring `conditions` with the `SectionAlias` property.

Composed sidebar menu

-You can read more about this in the [Menu](../menu.md) article. +{% code title="umbraco-package.json" %} +```json +{ + "type": "sectionSidebarApp", + "alias": "My.SectionSidebarApp", + "name": "My Section Sidebar App", + "element": "/App_Plugins//sidebar-app.js", + "conditions": [{ + "alias": "Umb.Condition.SectionAlias", + "match": "Umb.Section.Settings" + }] +} +``` +{% endcode %} + +Common Umbraco-provided section aliases: + +| Section Aliases | +|-------------------------| +| Umb.Section.Content | +| Umb.Section.Media | +| Umb.Section.Settings | +| Umb.Section.Packages | +| Umb.Section.Users | +| Umb.Section.Members | +| Umb.Section.Translation | diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md index 3f083edb117..ffcdfe16887 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section-view.md @@ -1,35 +1,41 @@ --- description: >- - Append a secondary view for a Section, use it for additional features or - information. + Add auxiliary views to your own Umbraco packages, or to other areas of the Umbraco backoffice. --- # Section View -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} +Section View extensions are containers for custom Umbraco packages or other backoffice areas, including Content, Media, Settings, Users, Members, or Translations. These extensions can contain other Umbraco extensions, like dashboards or web components, enabling package authors to populate the section with any content or custom interface.

Section View

## Creating a custom Section View -In this section, you can learn how to register and create a custom Section View for the Umbraco backoffice. +Custom Section View extensions are straightforward to create. Extension authors register the Section View extension and +subsequently implement the content or interface they desire to display within the Section View. -### Manifest +### Registering Section View extensions -The manifest file can be created using either JSON or TypeScript. Both methods are shown below. +Extension authors can register Section View extensions using two methods: + +- Declarative registration via manifests or +- Imperative registration using TypeScript and [Backoffice Entry Points](../backoffice-entry-point.md). + +Both methods are shown below. + +#### Registering by manifest {% tabs %} {% tab title="Json" %} -We can create the manifest using json in the `umbraco-package.json`. +Extensions authors can register the Section View extension using a JSON declaration in the `umbraco-package.json` file. +{% code title="umbraco-package.json" %} ```json { "type": "sectionView", "alias": "My.SectionView", "name": "My Section View", - "element": "./my-section.element.js", + "element": "/App_Plugins//my-section.element.js", "meta": { "label": "My View", "icon": "icon-add", @@ -38,11 +44,16 @@ We can create the manifest using json in the `umbraco-package.json`. "conditions": [ { "alias": "Umb.Condition.SectionAlias", - "match": "My.Section", + "match": "My.Section" } ] } ``` +{% endcode %} + +Tip: Use the absolute path, starting from the root of your Umbraco project, in the `element` property for +JSON declarations. TypeScript declarations are capable of employing relative paths. + {% endtab %} {% tab title="TypeScript" %} @@ -50,6 +61,7 @@ The manifest can also be written in TypeScript. For this TypeScript example we used a [Backoffice Entry Point](../backoffice-entry-point.md) extension to register the manifests. +{% code title="my-section.element.ts" %} ```typescript import type { ManifestSectionView } from '@umbraco-cms/backoffice/section'; @@ -73,6 +85,8 @@ const sectionViews: Array = [ } ] ``` +{% endcode %} + {% endtab %} {% endtabs %} @@ -80,8 +94,7 @@ const sectionViews: Array = [ Creating the Section View Element using a Lit Element. -**my-section.element.ts:** - +{% code title="my-section.element.ts" %} ```typescript import { UmbLitElement } from '@umbraco-cms/backoffice/lit-element'; import { css, html, customElement, property } from '@umbraco-cms/backoffice/external/lit'; @@ -115,5 +128,94 @@ declare global { 'my-sectionview-element': MySectionViewElement; } } +``` +{% endcode %} + +## Adding Section Views to your own package + +When developing a Section View extension for their own package, an extension author must create a Section extension to +host the Section View extension. + +Guidelines on creating Section extensions can be found at [this link](./section.md). + +To link a Section View with a Section, set the `match` property in the condition to the same value as the Section's `alias`. In the +provided example, this value is `NetworkServices.Section`. + +{% code title="umbraco-package.json" %} +```json +[ + { + "type": "section", + "alias": "NetworkServices.Section", + "name": "Network Services", + "meta": { + "label": "Network Services", + "pathname": "network-services" + } + }, + { + "type": "sectionView", + "alias": "NetworkServices.Section.Overview", + "name": "Network Services Overview", + "element": "/App_Plugins/NetworkServices/overview-dashboard.js", + "meta": { + "label": "Overview", + "icon": "icon-add", + "pathname": "overview" + }, + "conditions": [ + { + "alias": "Umb.Condition.SectionAlias", + "match": "NetworkServices.Section" + } + ] + } +] +``` +{% endcode %} +## Adding Section Views to somewhere else in the backoffice + +The Umbraco backoffice architecture places a strong emphasis on composing. Authors can extend existing sections, including core ones like Content, Media, and Settings, with Section View extensions. + +After an author has completed their Section View extension, they can control the placement of the extension using +conditions in the manifest definition. + +The `match` property demonstrates how an extension author can incorporate a custom Section View within the Content +section. + +{% code title="umbraco-package.json" %} +```json +{ + "type": "sectionView", + "alias": "My.SectionView", + "name": "My Section View", + "element": "/App_Plugins//my-section.element.js", + "meta": { + "label": "My View", + "icon": "icon-add", + "pathname": "my-view" + }, + "conditions": [ + { + "alias": "Umb.Condition.SectionAlias", + "match": "Umb.Section.Content" + } + ] +} ``` +{% endcode %} + +Common Umbraco-provided section aliases: + +| Section Aliases | +|-------------------------| +| Umb.Section.Content | +| Umb.Section.Media | +| Umb.Section.Settings | +| Umb.Section.Packages | +| Umb.Section.Users | +| Umb.Section.Members | +| Umb.Section.Translation | + +Section View extensions can also appear in Sidebar extensions of Umbraco-provided sections, alongside custom sidebars created by authors. diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md index ea01a688e02..3d1a795e58a 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/sections/section.md @@ -1,18 +1,14 @@ --- -description: A guide to creating a section +description: Introducing Section extensions, a home for custom content and functionality. --- # Sections -{% hint style="warning" %} -This page is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -The Umbraco backoffice consists of Sections. Section is the main division shown in the top navigation. +Umbraco extension authors can place their extension in the top-level navigation of the backoffice using Sections. The +extension will be placed among the default options such as Content, Media, Settings, etc. -For example, when you load the backoffice, you'll see the 'Content' section, 'Settings' section, and so on. - -You can create your own sections to extend Umbraco with room for more features. +Within the section, authors can add menus, section views, workspace views, or any other content or interface they +desire.

Section

@@ -20,11 +16,10 @@ You can create your own sections to extend Umbraco with room for more features. ### **Manifests** -When creating a new section it's recommended to use a [Entry Point](../backoffice-entry-point.md)-extension in your [Umbraco Package Manifest](../../../umbraco-package.md). This is to get better control over all the additional extensions required for the new section. - -Create a section by defining a manifest for it: +Sections can be created by adding a definition in the extension's manifest file. -```typescript +{% code title="umbraco-package.json" %} +```json { "type": "section", "alias": "My.Section", @@ -35,31 +30,46 @@ Create a section by defining a manifest for it: } } ``` +{% endcode %} -Once registered, you will be able to select this action for your User Group Permissions. Once that is permitted, you can view your section. +### **Group permissions** + +To enable custom sections for backoffice users, site administrators must first assign permissions to those users. This +involves configuring the permission for a user group and assigning users to that group. + +To grant access to the custom section, open the Umbraco backoffice, navigate to the **Users** section, and select the +**User groups** menu item. Site administrators can create a new user group or modify an existing one. + +Once the user group is open, click the **Choose** button under the Sections section. Select the custom section from the +slide-out modal to enable access. + +

Enabling new Sections

+ +After assigning permission, users may need to reload the backoffice for the changes to take effect.

Section

-#### **Extend with Sidebar, Dashboards and more** +### **Entry points** -Once a section is registered, it can be extended like any other section. +When creating a new section, create an [Entry Point](../backoffice-entry-point.md) extension in the +[Umbraco Package Manifest](../../../umbraco-package.md) to complement it. Entry Point extensions add initialization and +teardown lifecycle events that may be helpful in coordinating behavior inside the section. -Here is a list of appropriate extensions to append to your section: +## **Extend with Sidebar, Dashboards, and more** -* [Creating a Custom Dashboard](../../../../tutorials/creating-a-custom-dashboard/) -* [Section Sidebar](section-sidebar.md) -* [Section View](section-view.md) +Sections serve as blank canvases within the Umbraco backoffice. Extension authors can integrate other Umbraco extensions +into sections, including [custom dashboards](../../../../tutorials/creating-a-custom-dashboard/), +[sidebars](section-sidebar.md), and [section views](section-view.md). -#### **Manifest with empty element** +Section authors can also skip Umbraco backoffice components and build a fully custom view by creating an empty element. -If you prefer full control over the content of your section you can choose to define an element for the content of your section. +### **Manifest with empty element** {% hint style="warning" %} -This is not recommended as it limits the content of your section to this element. Instead, it is recommended to use a single Dashboard or Section View. +This approach is not recommended because it restricts content to a single element. Instead, use a Dashboard or Section View. {% endhint %} -If you like to have full control, you can define an element like this: - +{% code title="manifests.ts" %} ```typescript const section : UmbExtensionManifest = { type: "section", @@ -72,5 +82,7 @@ const section : UmbExtensionManifest = { } } ``` +{% endcode %} -The element file must have an `element` or `default` export, or specify the element name in the `elementName` field. +The element file must contain an `element`, a `default` export, or specify the element name in the +`elementName` field.