Creating a Backoffice Tour
In this tutorial, we show how you can create a custom Backoffice Tour in Umbraco CMS.
Introduction
In this tutorial we will show how you can create a backoffice tour, helping users get started with working in the Umbraco backoffice.
A use case could be if you have a custom dashboard then a backoffice tour can be used to show how it works.
Before moving on, we recommend reading the Backoffice Tours documentation as it explains how each of the elements works in the tour.
Video tutorial
Step 1: Create the Backoffice tour files
To create the backoffice tour, the first thing we need is to create its associated files.
These files need to be created in the app_plugins folder. If the app_plugins folder does not already exist in your project the folder needs to be created at the root of your project files.
Navigate to the root of the Umbraco project.
Create an app_plugins folder at the root of your project.
Create a folder with the name of your plugin, in the app_plugins folder.
Create another new folder within that, called backoffice.
Create a folder called tours.
Add a new JSON file to the tours folder.
In the JSON file, we will add the Tour Configuration Object and the Tour Step Object in the following step.
Step 2: Create the Tour Configuration Objects
Once we have added the folders and the JSON file, we can go ahead and create the Tour Configuration Object.
In the JSON file, add the following configuration object:
Once we have added the Configuration Object, it is time to configure it so it fits our backoffice tour.
In this Tour Configuration Object, we are going to change the name, alias, and group:
Change the
name
to "Settings Section Tour"Change the
alias
to "settingsSectionTour"Change the
group
to "Learn about the settings section"Add "settings" to the
requiredSection
.
The name is what is displayed in the help drawer for our tour.
The alias is unique to our tour. It is used to track the progress the users have made while taking the tour.
The group is used to group related tours in the help drawer under a common subject (for example Getting Started).
The requiredSections
is an array of section aliases that a user needs access to, to see the tour. If the user does not have access to all the defined sections, the tour will not be shown in the help drawer.
Once you are done with the steps above, the Tour Configuration should look like this:
Step 3: Find elements for the Tour Step Object
Before we get started with creating our Tour Step Objects, we need to find the CSS selector for the elements that we want to highlight in our tour.
In this tutorial, we want to highlight three areas: Settings in the navigation, the side navigation in the Settings section, and then the Settings dashboard.
A lot of elements in the backoffice have the data-element
attribute, however, we can also use IDs or classes.
To find the first element
, follow the steps below:
Go to the backoffice of your Umbraco project and log in.
Right-click on Settings in the main navigation and inspect the element.
Locate the
data-element
for the top navigation calledsection-settings
.
Note down the
data-element
.
Let's find the element for the second step:
Navigate to the Settings section.
Right-click on the left side and inspect the page.
Find the
<div>
with theid= "navigation"
.
Note down the
id
.
And lastly, we need to find the last element for our tour step:
Right-click on the dashboard on the right.
Locate the
<section>
with theid="contentWrapper"
.
Note down the
id
.
Once we have located the elements we can go ahead and create our Tour Step Object.
Step 4: Create the Tour Step Object
We now need to create the Tour Step Object for our tour. The Tour Step JSON Object contains all the data related to tour steps.
In the steps
object in the Tour Configuration, add the following code snippet:
We need to configure it so that it fits our tour.
Change the
title
to "Accessing the settings section"Change the text in
content
to: "<p>Clicking on Settings will direct you to the settings section in Umbraco</p>"Replace the
data-element
with the first one we found calledsection-settings
Remove the "[data-element='global-user'] .umb-avatar" from the
eventElement
.
Once this is done, this is how our tour steps look:
For this first step, we are not going to change anything else as we want the rest of the settings for this step to be like they are.
Once we start the tour it will highlight the Settings tab in the navigation. It is then possible to click on Settings which will take us to the Settings section.
It's time to create the second step of our tour.
For the sake of this tutorial let's copy the step and insert it below the previous one.
In this step, once we click on Settings in the top menu, it will redirect us to the Settings section. It will highlight the side navigation in the Setting section and display our title and content.
Once the steps have been added we can modify the second step in our tour.
Change the
title
to "This is the Settings Section"Change the
content
to "<p>From here you can create document types, and templates, to mention a few</p>"Replace the
data-element
with the second one we found calledid='navigation'
Change "elementPreventClick" from false to true.
This will ensure that a button saying "next"
will show on the step, as we don't want to click on settings.
We are not going to make any changes to the rest of the steps.
So far, this is how our tour looks:
This is what the second step looks like in the backoffice when we run the tour:
So far so good. We have created two steps. Let's make a third step for our tour.
Like before, let's copy the previous tour step and add it below like so:
Now let's modify the step.
We are going to highlight the Settings dashboard in the Settings section.
Change the
title
to "This is the Settings Dashboard"Change the
content
to: <p>In the settings Dashboard, you will be able to work with your document types, templates, data types, etc.</p>Change the
element
id
to:id='contentwrapper'
We still want to show a "next"
button on the step, so we are not going to change the rest of the step.
Once we run the tour, it will highlight the whole Settings dashboard to the right of the side navigation:
We have now created our backoffice tour, which gives a short overview of the Settings section.
Down below you can see how the final tour step Object is configured:
Now that we have configured the final step of our tour, this is how the code for the tour will look like:
Conclusion
With all the steps completed, we now have a backoffice tour showing the Settings section in the Umbraco backoffice.
You can go ahead and extend the backoffice tour with more steps or create your very own backoffice tours.
Last updated