Community Doc Team: Sections, Section Views and Section Sidebar Apps

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

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.
 
 <figure><img src="../../../../.gitbook/assets/section-sidebar.svg" alt=""><figcaption><p>Section Sidebar</p></figcaption></figure>
 
-## Section Sidebar Apps <a href="#section-sidebar-apps" id="section-sidebar-apps"></a>
+## 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.
 
 <figure><img src="../../../../.gitbook/assets/section-sidebar-apps.svg" alt=""><figcaption><p>Section Sidebar Apps</p></figcaption></figure>
 
-**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/<package_name>/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.
 
 <figure><img src="../../../../.gitbook/assets/section-menu-sidebar-app.svg" alt=""><figcaption><p>Menu Sidebar App</p></figcaption></figure>
 
-**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/<package_name>/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.
 
 <figure><img src="../../../../.gitbook/assets/section-sidebar-composed-apps.svg" alt=""><figcaption><p>Composed sidebar menu</p></figcaption></figure>
 
-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/<package_name>/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 |

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.
 
 <figure><img src="../../../../.gitbook/assets/section-views.svg" alt=""><figcaption><p>Section View</p></figcaption></figure>
 
 ## 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/<package_name>/my-section.element.js",
 	"meta": {
 		"label": "My View",
 		"icon": "icon-add",
@@ -38,11 +43,15 @@
 	"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 @@
         '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/<package_name>/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.