From a332d79dfcfbe90f760832eafeca58a1edecb1a3 Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Sun, 27 Jul 2025 22:16:56 -0500 Subject: [PATCH 1/5] Refine documentation for Section, Section View, and Section Sidebar extensions. Expanded details on manifest configurations and best practices, clarified user group permissions, and introduced examples for extending with dashboards, menus, and custom elements. --- .../extension-types/sections/README.md | 2 +- .../sections/section-sidebar.md | 176 +++++++++++++----- .../extension-types/sections/section-view.md | 119 ++++++++++-- .../extension-types/sections/section.md | 61 +++--- 4 files changed, 273 insertions(+), 85 deletions(-) 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..d1064c6412b 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 other areas +of the Umbraco backoffice, including the Settings, User, or Member management 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. + From 03d3b7cb10ea6d675185f98202cde5f85c65d03c Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Sun, 27 Jul 2025 22:22:54 -0500 Subject: [PATCH 2/5] Expand documentation to include additional areas for Section View extensions, highlighting Content, Media, and Translations sections. --- .../extension-types/sections/section-view.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) 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 d1064c6412b..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 @@ -5,10 +5,10 @@ description: >- # Section View -Section View extensions serve as containers that can be integrated into custom Umbraco packages or extended other areas -of the Umbraco backoffice, including the Settings, User, or Member management 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 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

From 92ee1fe6c2247c1e7c777de825d3592da4f78c0b Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Tue, 19 Aug 2025 17:53:28 -0500 Subject: [PATCH 3/5] Rewriting entity actions article --- .../extension-types/entity-actions.md | 183 ++++++++++-------- 1 file changed, 106 insertions(+), 77 deletions(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md b/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md index b91de56a43c..4696abcc410 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md @@ -1,55 +1,57 @@ --- -description: Entity Actions perform an action on a specific item +description: Entity Actions give extension authors the ability to add custom actions to a fly-out menu. --- # Entity Actions -{% 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 %} - {% hint style="info" %} Entity Actions was previously called Tree Actions. {% endhint %} -Entity Actions is a feature that provides a generic place for secondary or additional functionality for an entity type. An entity type can be a media, document and so on. +Entity Actions is an extension type that provides a fly-out context menu for secondary or additional functionality to +an entity (document, media, etc...). -Items in an Umbraco Tree can have associated Actions. The actions visible to the currently logged in user can be controlled via User Permissions. +Extension authors can define and associate custom actions for entities in a [tree extension](tree.md), workspace or +collection view. Access to these actions can be controlled via user permissions. Site administrators can control which +actions a user has permissions to access, for each item in the content tree, in the Users Section of the backoffice. -You can set a User's permissions for each item in the Umbraco Content tree from the User Section of the Umbraco Backoffice. +## Display Modes -If you are developing a custom section or a custom Dashboard, you might want to display some different options. This depends on a User's permission set on a particular item. +Entity Actions extensions can be displayed in a variety of formats. -## Entity Actions in the UI +### Sidebar Context Menu -
+The sidebar context mode provides a second-level context menu that flies out from the content tree. Backoffice users +will typically find default items such as sorting, moving, deleting, and publishing workflow actions here. -

Sidebar Context Menu

+graphic representation of the sidebar context menu - +### Workspace Entity Menu -

Workspace Entity Action Menu

+The workspace entity mode provides a drop-down menu that flies out from the upper decking of a workspace. -
+Workspace Entity Action Menu -
+### Collection Menu -

Collection

+The collection mode provides a drop-down menu that appears above a collection view. - +Collection -

Pickers

+### Picker Menu -
+The picker mode provides a menu in a sidebar modal. -### Sidebar Context Menu +Pickers -Sidebar Context Menu is an entity action that can be performed on a menu item. For example in the content section you can perform some extra actions on the content such as sorting, moving, etc. +## Registering an Entity Action -

Default Entity Action in the Content Section

+To register an entity action, extension authors will need to declare the entity action in the manifest file, and then +extend the `UmbEntityActionBase` class to program the action's behavior. -## Registering an Entity Action +### Declare the Entity Action +{% code title="entity-action/manifest.ts" lineNumbers="true" %} ```typescript import { extensionRegistry } from '@umbraco-cms/extension-registry'; import { MyEntityAction } from './entity-action'; @@ -70,20 +72,26 @@ const manifest = { extensionRegistry.register(manifest); ``` +{% endcode %} + +### The Entity Action Class -**Default Element** +Umbraco provides a few generic actions that can be used across silos, such as copy, move, trash, etc. Umbraco may +include additional generic actions in the future. -```typescript -interface UmbEntityActionElement {} -``` +Entity Action extension authors will need to supply a class to the extension definition using the `api` property in the +manifest file. This class will be instantiated as part of the action and will be passed a reference to the entity that +invoked it. -### The Entity Action Class +The entity action class will provide one of the following methods: +* `getHref` - returns a url that will be used for navigation +* `execute` - programs custom imperative behaviors that can work with various contexts and service apis -As part of the Extension Manifest you can attach a class that will be instanciated as part of the action. It will have access to the host element, a repository with the given alias and the unique (key etc) of the entity. +If both methods are provided in the entity action class, the `getHref` method will be preferred. -The class either provides a getHref method, or an execute method. If the getHref method is provided, the action will use the link. Otherwise the `execute` method will be used. When the action is clicked the `execute` method on the api class will be run. When the action is completed, an event on the host element will be dispatched to notify any surrounding elements. +When the action is completed, an event on the host element will be dispatched to notify any surrounding elements. -Example of providing a `getHref` method: +Example of providing an `getHref` method: ```typescript import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; @@ -101,7 +109,7 @@ export class MyEntityAction extends UmbEntityActionBase { } ``` -Example of providing a `execute` method: +Example of providing an `execute` method: ```typescript import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; @@ -119,7 +127,7 @@ export class MyEntityAction extends UmbEntityActionBase { } ``` -If any additional contexts are needed, these can be consumed from the host element: +If additional contexts are needed, they can be consumed from the host element via the `constructor` method. ```typescript import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; @@ -139,32 +147,18 @@ export class MyEntityAction extends UmbEntityActionBase { } ``` -We currently have a couple of generic actions that can be used across silos, so we don't have to write the same logic again. These actions include copy, move, trash, delete, etc. We can add more as we discover the needs. - ## User Permission Codes -Here is a list of the entity actions and associated user permission codes shipped by Umbraco CMS and add-on projects, such as Umbraco Deploy. This list also includes codes used by some community packages. +Entity Action extension authors can define custom user permission codes to control access to their actions, in addition +to the standard Umbraco user permission codes. Custom permission codes need to be unique and should not clash with +existing permission codes. -If you are building a package or adding custom entity actions to your solution, it's important to pick a permission letter. Ensure that it doesn't clash with one of these. +Each permission has a set of verbs that will be checked against on both the client and server. -If you have created a package using a custom entity action, please consider providing an update to this documentation page. You can do this via a PR to the [documentation repository](https://github.com/umbraco/UmbracoDocs). This will allow other developers to discover and avoid using the same permission letter. +### Standard Umbraco Permission Letters -Currently, we allow two extension points on the client for user permissions: - -* **Entity User Permissions** - Relates to an entity (example document). - -

Entity User Permissions UI

- -* **Granular User Permission** - Relates to a $type server schemaType. - -

Granular User Permission UI

- -Each permission comes with a set of verbs, that will be checked against client and server-side. - -The Core currently ships with entity user permission for documents. The permissions are as follows: - -| Current Backoffice Letter | Verb | -| ------------------------- | -------------------------------- | +| Current Backoffice letter | Verb | +|---------------------------|----------------------------------| | C | Umb.Document.Create | | F | Umb.Document.Read | | A | Umb.Document.Update | @@ -182,35 +176,70 @@ The Core currently ships with entity user permission for documents. The permissi | K | Umb.Document.Rollback | | V | Umb.DocumentRecycleBin.Restore | -**Entity User Permissions** will be registered in the extension registry with a manifest with the following type. Example: +### Custom Permission Letters -```typescript +Extension authors who have created a package with a custom entity action, are encouraged to update this document by +submitting a pull request via a PR to the [documentation repository](https://github.com/umbraco/UmbracoDocs). This will allow other developers to discover +and avoid using the same permission letter. + +| Custom Backoffice letter | Verb | +|--------------------------|--------------------------------| +| ⌘ | *Placeholder* | + +## Extension Point Types + +Umbraco provides two extension points for user permissions: entity user permissions and granular user permissions. + +### Entity User Permissions + +Entity user permissions are assigned to a document, media, member, etc., and are registered using the +`entityUserPermission` type in the extension's manifest. + +#### Sample Manifest + +```json { - "type": "entityUserPermission", - "alias": "Umb.UserPermission.Document.Rollback", - "name": "Document Rollback User Permission", - "meta": { - "entityType": "document", - "verbs": ["Umb.Document.Rollback"], - "labelKey": "actions_rollback", - "descriptionKey": "actionDescriptions_rollback", - "group": "administration", + type: "entityUserPermission", + alias: "Umb.UserPermission.Document.Rollback", + name: "Document Rollback User Permission", + meta: { + entityType: "document", + verbs: ["Umb.Document.Rollback"], + labelKey: "actions_rollback", + descriptionKey: "actionDescriptions_rollback", + group: "administration", }, }, ``` -**Granular permissions** will also be registered. It is possible to provide a custom element to build the needed UX for that type of permission: +#### Management Interface + +

Entity User Permissions UI

+ +### Granular User Permission + +Granular user permissions are assigned to a $type server schemaType and are also registered in the extension's manifest +using the `userGranularPermission` type. + +It is possible to provide a custom element to build the needed UX for that type of permission: ???? + +#### Sample Manifest ```typescript { - "type": "userGranularPermission", - "alias": "Umb.UserGranularPermission.Document", - "name": "Document Granular User Permission", - "element": "element.js", - "meta": { - "schemaType": "DocumentPermissionPresentationModel", - "label": "Documents", - "description": "Assign permissions to specific documents", - }, - }, + type: "userGranularPermission", + alias: "Umb.UserGranularPermission.Document", + name: "Document Granular User Permission", + element: "element.js", + meta: { + schemaType: "DocumentPermissionPresentationModel", + label: "Documents", + description: "Assign permissions to specific documents" + } +} ``` + +#### Management Interface + +

Granular User Permission UI

+ From a7fa151827a2aed7174761bbba66683dcaf5398a Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Mon, 6 Oct 2025 20:17:18 -0500 Subject: [PATCH 4/5] Update terminology in entity actions documentation --- .../extending-overview/extension-types/entity-actions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md b/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md index 4696abcc410..7f48df584a8 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md @@ -5,7 +5,7 @@ description: Entity Actions give extension authors the ability to add custom act # Entity Actions {% hint style="info" %} -Entity Actions was previously called Tree Actions. +**Entity Actions** was previously known as **Tree Actions.** {% endhint %} Entity Actions is an extension type that provides a fly-out context menu for secondary or additional functionality to From a3982e3cabb4a567c0981e05eed17997b6160e9a Mon Sep 17 00:00:00 2001 From: Ben Szymanski Date: Tue, 21 Oct 2025 15:33:39 -0500 Subject: [PATCH 5/5] Clarification in text, working and updated code examples. --- .../extension-types/entity-actions.md | 110 +++++++++--------- 1 file changed, 58 insertions(+), 52 deletions(-) diff --git a/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md b/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md index 7f48df584a8..8b2cfa448f0 100644 --- a/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md +++ b/16/umbraco-cms/customizing/extending-overview/extension-types/entity-actions.md @@ -8,12 +8,9 @@ description: Entity Actions give extension authors the ability to add custom act **Entity Actions** was previously known as **Tree Actions.** {% endhint %} -Entity Actions is an extension type that provides a fly-out context menu for secondary or additional functionality to -an entity (document, media, etc...). +Entity Actions is an extension type that provides a fly-out context menu for secondary or additional functionality to an entity (document, media, etc...). -Extension authors can define and associate custom actions for entities in a [tree extension](tree.md), workspace or -collection view. Access to these actions can be controlled via user permissions. Site administrators can control which -actions a user has permissions to access, for each item in the content tree, in the Users Section of the backoffice. +Extension authors can define and associate custom actions for entities in a [tree extension](tree.md), workspace or collection view. Access to these actions can be controlled via user permissions. Site administrators can control which actions a user has permissions to access, for each item in the content tree, in the Users Section of the backoffice. ## Display Modes @@ -21,8 +18,7 @@ Entity Actions extensions can be displayed in a variety of formats. ### Sidebar Context Menu -The sidebar context mode provides a second-level context menu that flies out from the content tree. Backoffice users -will typically find default items such as sorting, moving, deleting, and publishing workflow actions here. +The sidebar context mode provides a second-level context menu that flies out from the content tree. Backoffice users will typically find default items such as sorting, moving, deleting, and publishing workflow actions here. graphic representation of the sidebar context menu @@ -46,8 +42,7 @@ The picker mode provides a menu in a sidebar modal. ## Registering an Entity Action -To register an entity action, extension authors will need to declare the entity action in the manifest file, and then -extend the `UmbEntityActionBase` class to program the action's behavior. +To register an entity action, extension authors will need to declare the entity action in the manifest file, and then extend the `UmbEntityActionBase` class to program the action's behavior. ### Declare the Entity Action @@ -66,7 +61,6 @@ const manifest = { meta: { icon: 'icon-add', label: 'My Entity Action', - repositoryAlias: 'My.Repository', }, }; @@ -74,14 +68,11 @@ extensionRegistry.register(manifest); ``` {% endcode %} -### The Entity Action Class +## The Entity Action Class -Umbraco provides a few generic actions that can be used across silos, such as copy, move, trash, etc. Umbraco may -include additional generic actions in the future. +Umbraco provides a few generic actions that can be used across silos, such as copy, move, trash, etc. Umbraco may include additional generic actions in the future. -Entity Action extension authors will need to supply a class to the extension definition using the `api` property in the -manifest file. This class will be instantiated as part of the action and will be passed a reference to the entity that -invoked it. +Entity Action extensions will need to supply a class to the extension definition using the `api` property in the manifest file. This class will be instantiated as part of the action and will be passed a reference to the entity that invoked it. The entity action class will provide one of the following methods: * `getHref` - returns a url that will be used for navigation @@ -91,59 +82,74 @@ If both methods are provided in the entity action class, the `getHref` method wi When the action is completed, an event on the host element will be dispatched to notify any surrounding elements. -Example of providing an `getHref` method: +### The `getHref()` Method + +Entity action extensions are provided `this.args` by the `UmbEntityActionBase` superclass. The `this.args` contains a property, `unique` that allows developers to identity which element the user selected. + +The `getHref()` method must return a string value, and the result will be rendered into the DOM as an anchor/link. ```typescript -import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; -import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api'; -import type { MyRepository } from './my-repository'; - -export class MyEntityAction extends UmbEntityActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) { - super(host, repositoryAlias, unique); - } - - async getHref() { - return 'my-link/path-to-something'; - } +import {UmbEntityActionBase} from '@umbraco-cms/backoffice/entity-action'; + +export class MyEntityAction extends UmbEntityActionBase { + async getHref() { + return `my-link/path-to-something/${this.args.unique}`; + } } ``` -Example of providing an `execute` method: +### The `execute()` Method + +The `execute()` method is flexible and allows extension authors to perform nearly any task on an entity. Extension authors can perform network requests using `fetch()`, or access a repository. + +{% hint style="info" %} +The [Executing Requests](../../foundation/fetching-data) article provides an overview of the various methods for fetching data from Umbraco, including `tryExecute()` requests. +{% endhint %} ```typescript -import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; -import { UmbControllerHostElement } from '@umbraco-cms/backoffice/controller-api'; -import type { MyRepository } from './my-repository'; - -export class MyEntityAction extends UmbEntityActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) { - super(host, repositoryAlias, unique); - } - - async execute() { - await this.repository.myAction(this.unique); - } +import { + UmbEntityActionBase, +} from "@umbraco-cms/backoffice/entity-action"; + +export class EnableXgridAction extends UmbEntityActionBase { + async execute() { + // perform a network request + // fetch(`/server-resource/${this.args.unique}`) + + // or fetch repository + //const repository = ... + + console.log(this.args.unique); + } } ``` +### Overriding the UmbEntityActionBase Constructor + If additional contexts are needed, they can be consumed from the host element via the `constructor` method. ```typescript -import { UmbEntityActionBase } from '@umbraco-cms/backoffice/entity-action'; +import { + UmbEntityActionBase, + UmbEntityActionArgs, +} from "@umbraco-cms/backoffice/entity-action"; +import { UmbControllerHostElement } from "@umbraco-cms/backoffice/controller-api"; import { UmbContextConsumerController } from '@umbraco-cms/controller'; import { UMB_MODAL_SERVICE_CONTEXT } from '@umbraco-cms/modal'; -import { MyRepository } from './my-repository'; -export class MyEntityAction extends UmbEntityActionBase { - constructor(host: UmbControllerHostElement, repositoryAlias: string, unique: string) { - super(host, repositoryAlias, unique); +export class LinkToServerServicesAction extends UmbEntityActionBase { + constructor( + host: UmbControllerHostElement, + args: UmbEntityActionArgs, + ) { + super(host, args); - new UmbContextConsumerController(this.host, UMB_MODAL_SERVICE_CONTEXT, (instance) => { - this.#modalService = instance; - }); - } - ... + new UmbContextConsumerController(this.host, UMB_MODAL_SERVICE_CONTEXT, (instance) => { + this.#modalService = instance; + }); + } + + // ... } ```