A guide to creating a custom tree in Umbraco
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.
The tree is a hierarchical structure of nodes and is registered in the Backoffice extension registry. A tree can be rendered anywhere in the Backoffice with the help of the umb-tree element.
To Create a Tree in a section of the Umbraco backoffice, you need to take multiple steps:
The backoffice comes with two different tree item kinds out of the box: entity and fileSystem.
Tree Manifest:
We provide a base class for the tree item context. This class provides some default implementations for the context. You can extend this class to overwrite any of the default implementations.
Entity Actions perform an action on a specific item
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.
Entity Actions was previously called Tree Actions.
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.
Items in an Umbraco Tree can have associated Actions. The actions visible to the currently logged in user can be controlled via User Permissions.
You can set a User's permissions for each item in the Umbraco Content tree from the User Section of the Umbraco Backoffice.
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.
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.
Default Element
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.
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.
Example of providing a getHref
method:
Example of providing a execute
method:
If any additional contexts are needed, these can be consumed from the host element:
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.
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.
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.
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. This will allow other developers to discover and avoid using the same permission letter.
Currently, we allow two extension points on the client for user permissions:
Entity User Permissions - Relates to an entity (example document).
Granular User Permission - Relates to a $type server schemaType.
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:
Entity User Permissions will be registered in the extension registry with a manifest with the following type. Example:
Granular permissions will also be registered. It is possible to provide a custom element to build the needed UX for that type of permission:
Current Backoffice Letter | Verb |
---|---|
C
Umb.Document.Create
F
Umb.Document.Read
A
Umb.Document.Update
D
Umb.Document.Delete
I
Umb.Document.CreateBlueprint
N
Umb.Document.Notifications
U
Umb.Document.Publish
R
Umb.Document.Permissions
Z
Umb.Document.Unpublish
O
Umb.Document.Duplicate
M
Umb.Document.Move
S
Umb.Document.Sort
I
Umb.Document.CultureAndHostnames
P
Umb.Document.PublicAccess
K
Umb.Document.Rollback
V
Umb.DocumentRecycleBin.Restore
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.
Entity Bulk Action: Relates to an entity type: document, media, etc. Performs the action on a selection of items.
As part of the Extension Manifest you can attach a class that will be instantiated 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. 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.