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 b3c2aa0ce97..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 availabe 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 3b008c02fe2..db9e3da5dee 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,75 +1,157 @@ +--- +description: >- + Leverage Section Sidebar extensions to add deeper navigation and coordination of Section Views, and additional + Section-wide 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 deeper navigation and coordination of subviews, like +[Section View extensions](./section-view.md), as well as add additional Section-wide functionality, by declaring a +Section Sidebar extension. + +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-provided extension types, such as menus and trees, or create entirely custom sidebar apps through the use of +web components.

Section Sidebar Apps

-**Manifest** +### Custom Sidebar App Example -```typescript -{ - "type": "sectionSidebarApp", - "alias": "My.SectionSidebarApp", - "name": "My Section Sidebar App", - "meta": { - "sections": ["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. We recommend specifying the full path, +starting from the Umbraco project root. -**Default Element** +Sidebar Section extension authors may specify placement of the Section Sidebar app using +[extension conditions](../condition.md). -```typescript -interface UmbSectionSidebarAppElement {} +```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" + }] +} ``` -## **Menu Sidebar App** +### Menu Sidebar App Examples -**Sidebar Menu**: - -* The Backoffice comes with a menu sidebar app that can be used to create a menu in the sidebar. -* To register a new menu sidebar app, add the following to your manifest -* The menu sidebar app will reference a menu that you have registered in the menu with a menu manifest +The menu sidebar app is provided by the Umbraco backoffice and can be placed into Section Sidebar extensions. This +sidebar app will attach itself to a menu defined elsewhere in your manifest through the `meta:menu` property, where +this value must match the `alias` value of the menu.

Menu Sidebar App

-**Manifest** - -```typescript +```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** +In the example below, we continue by creating a menu extension and binding the `meta:menu` (My.Menu) property to the +menu extensions' `alias` property. The *My.Menu* alias is also used to attach a menu item extension to the menu +extension. + +```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"] + } + } +] +``` -```typescript -interface UmbMenuSectionSidebarAppElement {} +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. + +```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" + } + } +] ``` -**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: +Section Sidebar extension authors can place their extensions in the sidebar of any Umbraco-provided section, such as +Content, Media, Settings, etc., by configuring the `conditions` property with the appropriate `SectionAlias` condition.

Composed sidebar menu

-You can read more about this in the [Menu](../menu.md) article. +```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" + }] +} +``` + +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 39be2284a63..811ed6d1035 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,40 @@ --- 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 serve as containers that can be integrated into custom Umbraco packages or extended to other +areas of the Umbraco backoffice, including the Content, Media, Settings, User, Member, or Translations sections. These +extensions can contain other Umbraco extensions, such as dashboards or web components, enabling package authors to +populate the section with virtually any content or custom interface they envision.

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 have the option of registering custom 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. ```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 +43,15 @@ We can create the manifest using json in the `umbraco-package.json`. "conditions": [ { "alias": "Umb.Condition.SectionAlias", - "match": "My.Section", + "match": "My.Section" } ] } ``` + +Tip: We recommend using 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" %} @@ -115,5 +124,93 @@ declare global { 'my-sectionview-element': MySectionViewElement; } } +``` + +## 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 associate the Section View extension with the Section extension, authors must set the `match` property of the Section +Extension’s condition definition to the same value as the `alias` property of their desired Section extension. In the +provided example, this value is `NetworkServices.Section`. + +```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" + } + ] + } +] +``` + +## Adding Section Views to somewhere else in the backoffice + +The Umbraco backoffice architecture places a strong emphasis on composing. Extension authors can extend existing +sections, including those built by Umbraco and included in the core (such as Content, Media, and Settings), using +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. + +```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" + } + ] +} ``` + +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 be made available within the Sidebar extensions in Umbraco-provided sections, along +with a custom sidebar composed by the extension author. 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..16e7533a6ba 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,9 @@ 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 +```json { "type": "section", "alias": "My.Section", @@ -36,30 +30,43 @@ Create a section by defining a manifest for it: } ``` -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. + +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, it is recommended to create am [Entry Point](../backoffice-entry-point.md)-extension in the +[Umbraco Package Manifest](../../../umbraco-package.md) to complement. 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 eschew Umbraco-provided backoffice components and construct a fully customized view for full +control by creating a custom/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 as it restricts the content of your section to this element. Instead, it is advisable +to use a single Dashboard or Section View. {% endhint %} -If you like to have full control, you can define an element like this: - ```typescript const section : UmbExtensionManifest = { type: "section", @@ -73,4 +80,6 @@ const section : UmbExtensionManifest = { } ``` -The element file must have an `element` or `default` export, or specify the element name in the `elementName` field. +The element file must contain either an `element` or `default` export, or explicitly specify the element name in the +`elementName` field. +