How to add custom help to Umbraco
This article explains how to add customized help to the Umbraco help section and has been tested using Umbraco 7.
It is true that sometimes editors struggle to edit content in Umbraco in the way developers originally envisioned it. It might that they are new to Umbraco, or they don't understand which properties are which piece of actual content in a particularly complex view, or maybe we have some custom sections that need further explaining. Whatever the case, a nice pieces of documentation or help text would be a valuable resource for editors facing our extraordinary backoffice with all its document types, media types, member groups, custom sections, etc.
###The Umbraco Help
In order to better understand the process of adding our custom help content, I will explain first a few key points about the logic involved in building it. If you are not interested, or just need to grab the configuration settings for building it, just feel free to skip this first part of the article.
The template for the Umbraco help section is found at Umbraco/Views/Common/drawer/help/help.html. If we have a look at the file, we can find the markup responsible for rendering a custom help dashboard:
<!-- Show in custom help dashboard -->
<div class="umb-help-section" data-element="help-custom-dashboard" ng-if="vm.customDashboard.length > 0">
<div ng-repeat="tab in vm.customDashboard">
<div ng-repeat="property in tab.properties">
<div>
<h5 ng-if="property.caption">{{property.caption}}</h5>
<div ng-include="property.path"></div>
</div>
</div>
</div>
</div>
This template has an angular controller, found inside the umbraco.controllers.js file, named "Umbraco.Drawers.Help" controller. The lines responsible for getting the custom help are these:
// load custom help dashboard
dashboardResource.getDashboard('user-help').then(function (dashboard) {
vm.customDashboard = dashboard;
});
This will get the configuration for a "user-help" dashboard section and set is as the "customDashboard" that is then rendered in the view. If we dig deeper into the code we can find for ourselves what is going on during the execution of this method and where the source of the requested section is. As a summary, it will return all sections that contain an area named "user-help" and these sections are found (as you might have already guessed) in the Dashboard.config file. This file contains the configuration for the different Umbraco sections, and can be modified to extend the section dashboards in the back office. You can read more about how to set up this config file at https://our.umbraco.com/documentation/Reference/Config/dashboard.
Adding a help section
Basically, we need to add a new section to the /Config/Dashboard.config file within the
<section alias="CustomDashboardHelp">
<areas>
<area>user-help</area>
</areas>
<tab caption="Custom Dashboard Help">
<access>
<grantBySection>customDashboard</grantBySection>
</access>
<control showOnce="false" addPanel="true" panelCaption="Custom Dashboard Help">
/App_Plugins/CustomDashboard/BackOffice/help.html
</control>
</tab>
If you have ever added a custom dashboard to Umbraco, the above code will look familiar to you, and you wil probably understand it without further clarification.
The section element defines a dashboard layout for a group of sections.
The area elements indicate the sections of the Umbraco UI to which apply the configuration. Please note that you must include
<area>user-help</area>
for it to appear in the help section.
Tab elements usually define page tabs inside the dashboard page. In our case, the help section will not display tabs, but we can still use them to create different subsets of help with different permissions and controllers.
The access element sets permission for a particular section. It can also be added under a tab or control node, which allows for a more granular control of permissions. Inside the access node, we can have grant, grantBySection, or deny nodes. The difference between grant and gratBySection is that grant will allow access to a particular user group, while grantBySection will allow access to users who have permissions to a specific section. If you are adding help content that is specific for a custom section, it will make more sense to use grantBySection, so it will only be available to users that are allowed to that section while you can still play with permissions at user group level.
The control node is key in the custom help content. It corresponds to the "property" elements of the help template. The control node has a "panelCaption" attribute that corresponds to "property.caption", and its content is a path to template file that corresponds to "property.path" that will render our custom view.
After we have set up the dahsboard.config file, we need to create the template for the specified path (in our case /App_Plugins/CustomDashboard/BackOffice/help.html).
Here is an example using common Umbraco mark up and classes:
<ul class="umb-help-list">
<li class="umb-help-list-item">
<a class="umb-help-badge" href="#" prevent-default>
<i class="umb-help-badge__icon icon-info"></i>
<div class="umb-help-badge__title">About this section</div>
</a>
</li>
<li class="umb-help-list-item">
<a class="umb-help-badge" href="#" prevent-default>
<i class="umb-help-badge__icon icon-help-alt"></i>
<div class="umb-help-badge__title">Help</div>
</a>
</li>
<li class="umb-help-list-item">
<a class="umb-help-badge" href="#" prevent-default>
<i class="umb-help-badge__icon icon-books"></i>
<div class="umb-help-badge__title">Resources</div>
</a>
</li>
We can organize the content in whichever way we think more convenient, like blocks, tabs, accordions, a custom inner navigation, external resources, etc.
If we follow these steps, we will be able to have our customized help section.
Further thoughts
A customized help section will add great potential to your backoffice, and will make editors love the Umbraco CMS even more, especially if we add custom sections that sometimes need further explaining and even training.
We can extend this functionality and even have "help" users in charge of writing meaningful documentation for the rest of editors. Then we would need to add a angular controller to our custom view, that will get the help content from the right location. In large sites this will greatly improve the editing experience.
