A guide to creating a custom tree in Umbraco
This section describes how to work with and create trees with Umbraco APIs.
To Create a Tree in a section of the Umbraco backoffice, you need to take several steps:
Create a TreeController
class in C#. A new controller which inherits from the abstract Umbraco.Cms.Web.BackOffice.Trees.TreeController
*` class and provides an implementation for two abstract methods:
GetTreeNodes (returns a TreeNodeCollection
) - Responsible for rendering the content of the tree structure;
GetMenuForNode (returns a MenuItemCollection
) - Responsible for returning the menu structure to use for a particular node within a tree.
You will need to add a constructor as TreeController
requires this. See full code snippet in the "Implementing the Tree" section below.
The Tree
attribute used to decorate the TreeController
has multiple properties.
SectionAlias
- Alias of the section in which the tree appears
TreeAlias
- Alias of the tree
TreeTitle
- The title of the tree
TreeGroup
- The tree group, the tree belongs to
SortOrder
- Sort order of the tree
For example:
The example above would register a custom tree with a title 'Favourite Things Name' in the Settings section of Umbraco, inside a custom group called 'Favourites'.
Tree Groups enable you to group trees in a section. You provide the alias of the Tree Group name, you wish to add your tree to - see Constants.Trees.Groups for a list of existing group alias. An example of tree groups in the backoffice would be the Settings tree group and the Templating tree group in the Settings section.
If you add your own alias, you'll need to add a translation key. This can be done by adding a language file to a lang
folder with your application folder in App_Plugins
: App_Plugins/favouriteThings/lang/en-us.xml
. This will avoid the alias appearing as the header in [square brackets].
The language file should contain the following XML:
The first node in the tree is referred to as the Root Node. You can customise the Root Node by overriding the abstract CreateRootNode
method. You can assign a custom icon to the Root Node. You can also specify a custom URL route path in the backoffice to use with your custom tree. The method can be useful if your section has a single node (single page app).
See Also: How to create your own custom section
The actions on items in an Umbraco Tree will trigger a request to load an AngularJS view, with a name corresponding to the name of the action, from a subfolder of the views folder matching the name of the 'customTreeAlias'.
Clicking on one of the 'Favourite Things' in the custom tree example will load an edit.html
view from the folder: /views/favouriteThingsAlias/edit.html
. The 'Delete' menu item would also load a view from: /views/favouriteThingsAlias/delete.html
When creating a custom tree as part of a Umbraco package, it is recommended to change the location of the default folder. It should be changed to the App_Plugins
folder. You achieve this by decorating your MVC TreeController
with the PluginController
attribute.
The edit view in the example would now be loaded from the location: /App_Plugins/favouriteThings/backoffice/favouriteThingsAlias/edit.html
You can instruct the Umbraco backoffice to load additional JavaScript resources (eg. angularJS controllers) to use in conjunction with your 'tree action views' by adding a package.manifest
file in the same folder location as your views.
For example...
...this manifest would load files for two controllers to work with the edit and delete views and a general resource file, perhaps containing code to retrieve, create, edit and delete 'favourite things' from some external non-Umbraco API.
Our Tree Action View would then be wired to the loaded controller using the ng-controller
attribute. The delete view would perhaps the delete view look a little bit like this:
see Tree Actions for a list of tree ActionMenuItems and IActions
It is possible to create 'trees' consisting of only a single node - perhaps to provide an area to control some settings or a placeholder for a single page backoffice app. See the LogViewer in the settings section for a good example. (or as in the case of the 'settings/content templates' tree, it's possible to have a custom view for the root node as an 'introduction' page to the tree).
In both scenarios you need to override the CreateRootNode
method for the custom tree.
You can override the CreateRootNode
method to set the 'RoutePath' to where the single page application will live (or introduction page). Setting HasChildren
to false
will result in a Single Node Tree.
The RoutePath should be in the format of: section/treeAlias/method. As our example controller uses the PluginController
attribute, clicking the root node would now request /App_Plugins/favouriteThing/backoffice/favouritistThingsAlias/overview.html
. If you are not using the PluginController
attribute, then the request would be to /umbraco/views/favouritistThingsAlias/overview.html
.
It's possible to make your single node tree app stretch across the full screen of the backoffice (no navigation tree) - see Packages section for an example. To achieve this add an additional attribute IsSingleNodeTree
, in the Tree attribute for the custom controller.
All tree notications are defined in the namespace Umbraco.Cms.Core.Notifications
.
For more information about registering and using notifications see Notifications
The RootNodeRenderingNotification
is published whenever a tree's root node is created.
Members:
TreeNode Node
FormCollection QueryString
string TreeAlias
Usage:
The TreeNodesRenderingNotification
is published whenever a list of child nodes are created.
Members:
TreeNodeCollection Nodes
FormCollection QueryString
string TreeAlias
Usage:
The MenuRenderingNotification
is raised whenever a menu is generated for a tree node.
Members:
MenuItemCollection Menu
string NodeId
FormCollection QueryString
string TreeAlias
Usage:
A guide to creating a custom tree action in Umbraco
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 based on a User's permission set on a particular item.
For example, on a custom dashboard you might add a quick 'Create a Blog Post' button for an editor, but only if that editor has permissions to create a blog post. You could create some sort of API endpoint, to call from your AngularJS controller, that in turn uses the UserService to return the current user's permissions. Then you can see whether they have the required permission to 'create' within the site's blog section.
Each tree action in Umbraco implements the IAction interface, and each Action has a corresponding 'Letter', and a boolean value describing whether permissions can be assigned for an action.
When you pull back the AssignedPermissions for a user on a particular item, it is these letters that indicate which actions the User is permitted to perform in the context of the tree item.
Here is a list of the tree actions and associated user permission codes shipped by Umbraco CMS and add-on projects (such as Umbraco Deploy), as well as those used by some community packages.
If building a package or adding custom tree actions to your solution, it's important to pick a permission letter that doesn't clash with one of these.
If you have created a package using a custom tree action, please consider providing an update to this documentation page via a PR to the documentation repository, such that other developers can discover and avoid using the same permission letter.
Note: up until Umbraco Deploy 9.2.0, the letter "N" was used for the "Queue For Transfer" action. In 9.2.1 it was changed to be "T", to avoid clashing with the letter selected for the Umbraco CMS "Notify" action, introduced in CMS version 8.18.
Type | Alias | Letter | Can Be Permission Assigned |
---|---|---|---|
Umbraco.Cms.Core.Actions.ActionAssignDomain
assignDomain
I
True
Umbraco.Cms.Core.Actions.ActionBrowse
browse
F
True
Umbraco.Cms.Core.Actions.ActionCopy
copy
O
True
Umbraco.Cms.Core.Actions.ActionCreateBlueprintFromContent
createblueprint
ï
True
Umbraco.Cms.Core.Actions.ActionDelete
delete
D
True
Umbraco.Cms.Core.Actions.ActionMove
move
M
True
Umbraco.Cms.Core.Actions.ActionNew
create
C
True
Umbraco.Cms.Core.Actions.ActionNotify
notify
N
True
Umbraco.Cms.Core.Actions.ActionProtect
protect
P
True
Umbraco.Cms.Core.Actions.ActionPublish
publish
U
True
Umbraco.Cms.Core.Actions.ActionRestore
restore
V
False
Umbraco.Cms.Core.Actions.ActionRights
rights
R
True
Umbraco.Cms.Core.Actions.ActionRollback
rollback
K
True
Umbraco.Cms.Core.Actions.ActionSort
sort
S
True
Umbraco.Cms.Core.Actions.ActionToPublish
sendtopublish
H
True
Umbraco.Cms.Core.Actions.ActionUnpublish
unpublish
Z
True
Umbraco.Cms.Core.Actions.ActionUpdate
update
A
True
Umbraco.Deploy.UI.Actions.ActionDeployRestore
deployRestore
Q
True
Umbraco.Deploy.UI.Actions.ActionDeployTreeRestore
deployTreeRestore
Ψ
True
Umbraco.Deploy.UI.Actions.ActionPartialRestore
deployPartialRestore
Ø
True
Umbraco.Deploy.UI.Actions.ActionQueueForTransfer
deployQueueForTransfer
T
True
Umbraco.Deploy.UI.Actions.Export
deployExport
П
True
Umbraco.Deploy.UI.Actions.Import
deployImport
Џ
True
Jumoo.TranslationManager.Core.Actions.ActionTranslate
translate
5
True
Jumoo.TranslationManager.Core.Actions.ActionManageTranslation
manageTranslations
Ť
True
uSync.Publisher.Actions.PushToServer
pushContent
>
True
uSync.Publisher.Actions.PullFromServer
pullContent
<
True
uSync.Publisher.Action.PushButton
pushContentButton
^
True
Our.Umbraco.LinkedPages.LinkedAction
linkPages
l
True