From c8781a6677f787f258fa1508092385b16ac62650 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Fri, 16 Aug 2024 10:07:21 +0200 Subject: [PATCH 1/4] Remove two articles from SUMMARY --- 14/umbraco-cms/SUMMARY.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/14/umbraco-cms/SUMMARY.md b/14/umbraco-cms/SUMMARY.md index e5476af37d3..f1e33f7c903 100644 --- a/14/umbraco-cms/SUMMARY.md +++ b/14/umbraco-cms/SUMMARY.md @@ -211,7 +211,6 @@ * [.NET Localization](extending/language-files/net-localization.md) * [UI Localization](extending/language-files/ui-localization.md) * [Backoffice Search](extending/backoffice-search.md) -* [Backoffice Tours](extending/backoffice-tours.md) * [Workspaces](extending/workspaces/README.md) * [Workspace Context](extending/workspaces/workspace-context.md) * [Workspace Views](extending/workspaces/workspace-editor-views.md) @@ -418,7 +417,6 @@ * [Creating a Multilingual Site](tutorials/multilanguage-setup.md) * [Add Google Authentication (Users)](tutorials/add-google-authentication.md) * [Add Microsoft Entra ID authentication (Members)](tutorials/add-microsoft-entra-id-authentication.md) -* [Creating a Backoffice Tour](tutorials/creating-a-backoffice-tour.md) * [Creating Custom Database Tables with Entity Framework](tutorials/getting-started-with-entity-framework-core.md) * [The Starter Kit](tutorials/starter-kit/README.md) * [Lessons](tutorials/starter-kit/lessons/README.md) From 49547ff14cc957995ca421c8b2d859350442559e Mon Sep 17 00:00:00 2001 From: sofietoft Date: Fri, 16 Aug 2024 10:08:20 +0200 Subject: [PATCH 2/4] Remove backoffice tour articles --- 14/umbraco-cms/extending/backoffice-tours.md | 232 ---------- .../tutorials/creating-a-backoffice-tour.md | 411 ------------------ 2 files changed, 643 deletions(-) delete mode 100644 14/umbraco-cms/extending/backoffice-tours.md delete mode 100644 14/umbraco-cms/tutorials/creating-a-backoffice-tour.md diff --git a/14/umbraco-cms/extending/backoffice-tours.md b/14/umbraco-cms/extending/backoffice-tours.md deleted file mode 100644 index 2d5071b11fe..00000000000 --- a/14/umbraco-cms/extending/backoffice-tours.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -description: A guide configuring backoffice tours in Umbraco ---- - -# Backoffice Tours - -{% hint style="warning" %} -This article is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -Backoffice Tours are a way to create helpful guides for how to work in the Umbraco backoffice. - -They are managed in a JSON format and stored in files on disk. The filenames should end with the `.json` extension. - -## Tour File Locations - -The tour functionality will load information from multiple locations. - -* **Core tours** - - The tour that ship with Umbraco are embedded into the CMS assemblies. -* **Custom tours** - - Custom tours need to be added as custom plugin/package. The custom json tour file needs to be added in `/App_Plugins//backoffice/tours`. The custom tours can be added independently, or [as part of a plugin/package](packages/creating-a-package.md). - -## The JSON Format - -A tour file contains an array of tour configuration JSON objects. It's possible to have multiple, (un)related tours in one file. - -```json -[ - { - // tour configuration object - }, - { - // tour configuration object - } -] -``` - -## The Tour Configuration Object - -A tour configuration JSON object contains all the data related to a tour. - -Example tour configuration object: - -```json -[ - { - "name": "My Custom Backoffice tour", - "alias": "myCustomBackofficeTour", - "group": "Get things done!!!", - "groupOrder": 1, - "allowDisable": true, - "culture": "en-US", - "contentType": "", - "requiredSections": [ "content", "media" ], - "steps": [] - } -] -``` - -Below is an explanation of each of the properties on the tour configuration object: - -* **name** - - This is the name that is displayed in the help drawer for the tour. - - ![Tour name highlighted](../../../10/umbraco-cms/extending/images/tourname-v8.png) -* **alias** - - The unique alias of your tour. This is used to track the progress a user has made while taking a tour. The progress information is stored in the `TourData` column of the `UmbracoUsers` table in the database. -* **group** - - The group property is used to group related tours in the help drawer under a common subject (for example Getting started). - - ![Tour group highlighted](../../../10/umbraco-cms/extending/images/tourgroup-v8.png) -* **groupOrder** - - This is used to control the order of the groups in the help drawer. This must be an integer value. -* **allowDisable** - - A boolean value that indicates if the "Don't show this tour again" should be shown on the tour steps. If the user clicks this link the tour will no longer be shown in the help drawer. - - ![Tour allow disable link highlighted](../../../10/umbraco-cms/extending/images/tourallowdisable-v8.png) -* **culture** - - You have the option to set a culture, such as nl-NL. This tour will exclusively be displayed to users who have set this culture in their profile. -* **contentType** - - Use this property if you want to limit the tour to a specific content type. To create a tour for content nodes using the Home Page, set the `contentType` property with the alias `homePage`. - - The `contentType` property can also be used to limit the tours to content types that are using a specific composition. This will show the tour on all nodes that are using a specific composition. - - ![Content Type specific tours](<../../../10/umbraco-cms/extending/images/contentTypespecific (1) (1) (1) (1) (1).png>) - - In the image above, two tours are available on the _Welcome_ node: - - 1. "Setup the Welcome page" is available because the tour is limited to the `homePage` content type and - 2. "Setup the Search Engine Optimization (SEO)" is available because the content type uses the `SEO` composition, which is associated with a specific tour. - - When the `contentType` property is set, the tour will **not** show as part of any groups. -* **requiredSections** - - This is an array of section aliases that a user needs to have access to in order to see the tour. If the user does not have access to all the sections the tour will not be shown in the help drawer. For example if a user lacks access to Settings but has access to Content and Media, the tour requiring all three will not be shown. -* **steps** - - This is an array of tour step JSON objects that a user needs to take to complete the tour. - -## The Tour Step Object - -A tour step JSON object contains all the data related to a tour step. - -Example tour step object: - -```json -"steps": [ - { - "title": "A meaningful title", - "content": "

Some text explaining the step

", - "type": null, - "element": "[data-element='global-user']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "[data-element='global-user'] .umb-avatar", - "skipStepIfVisible": ".css-element-selector", - "customProperties": null - } - ] -``` - -Below is an explanation of each of the properties on the tour step object. - -* **title** - - This the title shown on the tour step. - - ![Tour step highlighted](../../../10/umbraco-cms/extending/images/steptitle-v8.png) -* **content** - - This text will be shown on the tour step, it can contain HTML markup. - - ![Tour content highlighted](../../../10/umbraco-cms/extending/images/stepcontent-v8.png) -* **type** - - The type of step. Currently, only one type is supported : "intro". This will center the step and show a "Start tour" button. -* **element** - - A CSS selector for the element you wish to highlight. The tour step will position itself near the element. - - A lot of elements in the Umbraco backoffice have a "data-element" attribute. It's recommended to use that, because "id" and "class" are subject to changes, e.g.: - - ```xml - [data-element='section-content'] - ``` - - {% hint style="info" %} - Use the developer tools from your browser to find the id, class and data-attribute. - {% endhint %} - -
- -* **elementPreventClick** - - Setting this to true will prevent JavaScript events from being bound to the highlighted element. A "Next" button will be added to the tour step. - - As an example, it is useful when you would like to highlight a button, but would like to prevent the user clicking it. -* **backdropOpacity** - - A decimal value between 0 and 1 to indicate the transparency of the background overlay. -* **event** - - The JavaScript event that is bound to the highlighted element that should trigger the next tour step for example click, hover, etc. - - If not set or omitted a "Next" button will be added to the tour. -* **view** - - Here you can enter a path to your own custom AngularJS view that will be used to display the tour step. - - This is useful if you would like to validate input from the user during the tour step. -* **eventElement** - - A CSS selector for the element you wish to attach the JavaScript event. Highlighting a larger section of the backoffice while encouraging users to click on a specific element can be useful.. If not set, the selector in the element property will be used. - - The image below shows the entire tree highlighted, but requires the user to click on a specific tree element. - - ![Step eventElement highlighted](../../../10/umbraco-cms/extending/images/step-event-element-v8.png) -* **skipStepIfVisible** - - A CSS selector for an element that, if it is visible, will skip this tour step. - - This is useful for excluding a navigational step if the user is already there. Or skipping a step that would toggle an eventElement to the wrong state. -* **customProperties** - - A JSON object that is passed to the scope of a custom step view, so you can use this data in your view with `$scope.model.currentStep.customProperties`. - -## How to Filter/Disable Tours from being shown - -It is possible to hide/disable tours using a C# composer by adding to the TourFilters collection. - -Here is an example of disabling all the CMS core tours based on the alias. Additionally, we provide examples of filtering tours by JSON filename and disabling tours from specific packages. - -```csharp -using System.Text.RegularExpressions; -using Umbraco.Cms.Core.Composing; -using Umbraco.Cms.Core.DependencyInjection; -using Umbraco.Cms.Core.Tour; - -namespace Umbraco.Docs.Samples.Web.BackofficeTours; - -public class BackofficeComposer : IComposer -{ - public void Compose(IUmbracoBuilder builder) - { - // Filter out all the CMS core tours by alias with a Regex that start with the umbIntro alias - builder.TourFilters() - .AddFilter(new BackOfficeTourFilter(pluginName: null, tourFileName: null, tourAlias: new Regex("^umbIntro", RegexOptions.IgnoreCase))); - - // Filter any tours in the file that is custom-tours.json - // Found in App_Plugins/MyCustomBackofficeTour/backoffice/tours/ - builder.TourFilters() - .AddFilterByFile("custom-tours"); //Without extension - - // Filter out one or more tour JSON files from a specific plugin/package - // Found in App_Plugins/MyCustomBackofficeTour/backoffice/tours/custom-tours.json - builder.TourFilters() - .AddFilterByPlugin("MyCustomBackofficeTour"); - } -} -``` diff --git a/14/umbraco-cms/tutorials/creating-a-backoffice-tour.md b/14/umbraco-cms/tutorials/creating-a-backoffice-tour.md deleted file mode 100644 index 8ef088b6971..00000000000 --- a/14/umbraco-cms/tutorials/creating-a-backoffice-tour.md +++ /dev/null @@ -1,411 +0,0 @@ ---- -description: >- - In this tutorial, we show how you can create a custom Backoffice Tour in - Umbraco CMS. ---- - -# Creating a Backoffice Tour - -{% hint style="warning" %} -This article is a work in progress and may undergo further revisions, updates, or amendments. The information contained herein is subject to change without notice. -{% endhint %} - -## 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](creating-a-custom-dashboard/) then a backoffice tour can be used to show how it works. - -Before moving on, we recommend reading the [Backoffice Tours](../extending/backoffice-tours.md) 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. - -1. Navigate to the root of the Umbraco project. -2. Create an **app\_plugins** folder at the root of your project. -3. Create a folder with the name of your plugin, in the app\_plugins folder. -4. Create another new folder within that, called **backoffice**. -5. Create a folder called **tours.** -6. Add a new **JSON** file to the tours folder. - -![Umbraco Backoffice tour folder structure](<../.gitbook/assets/image (6).png>) - -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: - -```json -[ - { - "name": "My Custom Backoffice tour", - "alias": "myCustomBackofficeTour", - "group": "Get things done!!!", - "groupOrder": 1, - "allowDisable": true, - "culture": "en-US", - "contentType": "", - "requiredSections": [ "content", "media" ], - "steps": [] - } -] -``` - -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: - -1. Change the `name` to "**Settings Section Tour**_**"**_ -2. Change the `alias` to "**settingsSectionTour**_**"**_ -3. Change the `group` to "**Learn about the settings section**_**"**_ -4. 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: - -```json -[ - { - "name": "Settings section Tour", - "alias": "settingsSectionTour", - "group": "Learn about the settings section", - "groupOrder": 1, - "allowDisable": true, - "culture": "en-US", - "contentType": "", - "requiredSections": [ "content", "media", "settings" ], - "steps": [] - } -] -``` - -## 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: - -1. Log in to the backoffice of your Umbraco project. -2. Right-click on Settings in the main navigation and inspect the element. - -

Inspecting the Settings navigation in the backoffice

- -3. Locate the `data-element` for the top navigation called `section-settings`. - -

Finding the data-element for the first tour step

- -4. Note down the `data-element`. - -Let's find the element for the second step: - -1. Navigate to the Settings section. -2. Right-click on the left side and inspect the page. -3. Find the `
` with the `id= "navigation"`. - -

Finding the id for the second tour step

- -4. Note down the `id`. - -And lastly, we need to find the last element for our tour step: - -1. Right-click on the dashboard on the right. -2. Locate the `
` with the `id="contentWrapper"`. - -

Finding the id for the third tour step

- -4. 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: - -```json -"steps": [ - { - "title": "A meaningful title", - "content": "

Some text explaining the step

", - "type": null, - "element": "[data-element='global-user']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "[data-element='global-user'] .umb-avatar", - "customProperties": null - } - ] -``` - -We need to configure it so that it fits our tour. - -1. Change the `title` to _**"**_**Accessing the settings section**_**"**_ -2. Change the text in `content` to: _**"**_**\

Clicking on Settings will direct you to the settings section in Umbraco\

**_**"**_ -3. Replace the `data-element` with the first one we found called `section-settings` -4. Remove the **"\[data-element='global-user'] .umb-avatar"** from the `eventElement`. - -Once this is done, this is how our tour steps look: - -```json -"steps": [ - { - "title": "Accessing the settings section", - "content": "

Clicking on Settings will direct you to the settings section in Umbraco

", - "type": null, - "element": "[data-element='section-settings']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - } - ] -``` - -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. - -

How the first tour step looks like when running the backoffice tour.

- -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. - -```json -"steps": [ - { - ... - }, - { - "title": "Accessing the settings section", - "content": "

Clicking on Settings will direct you to the settings section in Umbraco

", - "type": null, - "element": "[data-element='section-settings']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - } - ] -``` - -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. - -1. Change the `title` to **"This is the Settings Section"** -2. Change the `content` to **"\

From here you can create document types, and templates, to mention a few**_**\

"**_ -3. Replace the `data-element` with the second one we found called `id='navigation'` -4. 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: - -```json -"steps": [ - { - "title": "Accessing the settings section", - "content": "

Clicking on Settings will direct you to the settings section in Umbraco

", - "type": null, - "element": "[data-element='section-settings']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - }, - { - "title": "This is the Settings Section", - "content": "

In the side navigation, you can create and manage document types, templates, data types just to name a few.

", - "type": null, - "element": "[id='navigation']", - "elementPreventClick": true, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - } - ] -``` - -This is what the second step looks like in the backoffice when we run the tour: - -

How the second tour step looks like when running the backoffice 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: - -```json -"steps": [ - { - ... - }, - { - ... - }, - { - "title": "This is the Settings Section", - "content": "

In the side navigation, you can create and manage document types, templates, data types just to name a few.

", - "type": null, - "element": "[id='navigation']", - "elementPreventClick": true, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - } - ] -``` - -Now let's modify the step. - -We are going to highlight the Settings dashboard in the Settings section. - -1. Change the `title` to _**"This is the Settings Dashboard"**_ -2. Change the `content` to: **\

In the settings Dashboard, you will be able to work with your document types, templates, data types, etc**_**.**_**\

** -3. 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: - -

How the third tour step looks like when running the backoffice tour.

- -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: - -```json -"steps": [ - { - "title": "Accessing the settings section", - "content": "

Clicking on Settings will direct you to the settings section in Umbraco

", - "type": null, - "element": "[data-element='section-settings']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - }, - { - "title": "This is the Settings Section", - "content": "In the side navigation, you can create and manage document types, templates, data types just to name a few.

", - "type": null, - "element": "[id='navigation']", - "elementPreventClick": true, - "backdropOpacity": 0.6, - "event": "", - "view": null, - "eventElement": "", - "customProperties": null - }, - { - "title": "This is the Settings Dashboard", - "content": "

In the settings Dashboard, you will be able to work with your document types, templates, data types, etc.

", - "type": null, - "element": "[id='contentwrapper']", - "elementPreventClick": true, - "backdropOpacity": 0.6, - "event": "", - "view": null, - "eventElement": "", - "customProperties": null - } - ] -``` - -Now that we have configured the final step of our tour, this is how the code for the tour will look like: - -```json -[ - { - "name": "Settings section Tour", - "alias": "settingsSectionTour", - "group": "Learn about the settings section", - "groupOrder": 1, - "allowDisable": true, - "culture": "en-US", - "contentType": "", - "requiredSections": [ "content", "media", "settings" ], - "steps": [ - { - "title": "Accessing the settings section", - "content": "

Clicking on Settings will direct you to the settings section in Umbraco

", - "type": null, - "element": "[data-element='section-settings']", - "elementPreventClick": false, - "backdropOpacity": 0.6, - "event": "click", - "view": null, - "eventElement": "", - "customProperties": null - }, - { - "title": "This is the Settings Section", - "content": "In the side navigation, you can create and manage document types, templates, data types just to name a few.

", - "type": null, - "element": "[id='navigation']", - "elementPreventClick": true, - "backdropOpacity": 0.6, - "event": "", - "view": null, - "eventElement": "", - "customProperties": null - }, - { - "title": "This is the Settings Dashboard", - "content": "

In the settings Dashboard, you will be able to work with your document types, templates, data types, etc.

", - "type": null, - "element": "[id='contentwrapper']", - "elementPreventClick": true, - "backdropOpacity": 0.6, - "event": "", - "view": null, - "eventElement": "", - "customProperties": null - } - ] - } -] -``` - -## 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. From a1a875a14c9a1eb86259c62453f7d451d69a15e8 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Fri, 16 Aug 2024 10:09:12 +0200 Subject: [PATCH 3/4] Remove refs to the deleted articles --- 14/umbraco-cms/extending/customize-the-editing-experience.md | 1 - 1 file changed, 1 deletion(-) diff --git a/14/umbraco-cms/extending/customize-the-editing-experience.md b/14/umbraco-cms/extending/customize-the-editing-experience.md index a8af3be7b63..3c78de29b98 100644 --- a/14/umbraco-cms/extending/customize-the-editing-experience.md +++ b/14/umbraco-cms/extending/customize-the-editing-experience.md @@ -14,7 +14,6 @@ In this section, you will find all the resources you need to build an intuitive ## Other ways to extend the Umbraco CMS backoffice -* [Backoffice Tours](backoffice-tours.md) * [Backoffice Search](backoffice-search.md) * [Workspace](workspaces/README.md) * [Language files and localization](language-files/README.md) From aac5d6ea6d5393bbd5f0ed5b65a3f9dc1716a8b7 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Fri, 16 Aug 2024 10:12:26 +0200 Subject: [PATCH 4/4] Add redirects --- 14/umbraco-cms/.gitbook.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/14/umbraco-cms/.gitbook.yaml b/14/umbraco-cms/.gitbook.yaml index ecf9c36ba63..c4ad8685f15 100644 --- a/14/umbraco-cms/.gitbook.yaml +++ b/14/umbraco-cms/.gitbook.yaml @@ -100,3 +100,5 @@ redirects: reference/routing/umbraco-api-controllers/authorization: reference/routing/umbraco-api-controllers/README.md reference/routing/umbraco-api-controllers/routing: reference/routing/umbraco-api-controllers/README.md extending/property-editors/package-manifest: extending/package-manifest.md + extending/backoffice-tours: extending/README.md + tutorials/creating-a-backoffice-tour: tutorials/overview.md