diff --git a/src/Umbraco.Web.UI.Client/src/common/directives/components/application/umbtour.directive.js b/src/Umbraco.Web.UI.Client/src/common/directives/components/application/umbtour.directive.js index f97a1d1886..edc3a0a560 100644 --- a/src/Umbraco.Web.UI.Client/src/common/directives/components/application/umbtour.directive.js +++ b/src/Umbraco.Web.UI.Client/src/common/directives/components/application/umbtour.directive.js @@ -1,3 +1,187 @@ +/** +@ngdoc directive +@name umbraco.directives.directive:umbTour +@restrict E +@scope + +@description +Added in Umbraco 7.8. The tour component is a global component and is already added to the umbraco markup. +In the Umbraco UI the tours live in the "Help drawer" which opens when you click the Help-icon in the bottom left corner of Umbraco. +You can easily add you own tours to the Help-drawer or show and start tours from +anywhere in the Umbraco backoffice. To see a real world example of a custom tour implementation, install The Starter Kit in Umbraco 7.8 + +

Extending the help drawer with custom tours

+The easiet way to add new tours to Umbraco is through the Help-drawer. All it requires is a my-tour.json file. +Place the file in App_Plugins/{MyPackage}/backoffice/tours/{my-tour}.json and it will automatically be +picked up by Umbraco and shown in the Help-drawer. + +

The tour object

+The tour object consist of two parts - The overall tour configuration and a list of tour steps. We have split up the tour object for a better overview. +
+// The tour config object
+{
+    "name": "My Custom Tour", // (required)
+    "alias": "myCustomTour", // A unique tour alias (required)
+    "group": "My Custom Group" // Used to group tours in the help drawer
+    "groupOrder": 200 // Control the order of tour groups
+    "allowDisable": // Adds a "Don't" show this tour again"-button to the intro step
+    "steps": [] // tour steps - see next example
+}
+
+
+// A tour step object
+{
+    "title": "Title",
+    "content": "

Step content

", + "type": "intro" // makes the step an introduction step, + "element": "[data-element='my-table-row']", // the highlighted element + "event": "click" // forces the user to click the UI to go to next step + "eventElement": "[data-element='my-table-row'] [data-element='my-tour-button']" // specify an element to click inside a highlighted element + "elementPreventClick": false // prevents user interaction in the highlighted element + "backdropOpacity": 0.4 // the backdrop opacity + "view": "" // add a custom view + "customProperties" : {} // add any custom properties needed for the custom view +} +
+ +

Adding tours to other parts of the Umbraco backoffice

+It is also possible to add a list of custom tours to other parts of the Umbraco backoffice, +as an example on a Dashboard in a Custom section. You can then use the {@link umbraco.services.tourService tourService} to start and stop tours but you don't have to register them as part of the tour service. + +

Using the tour service

+

Markup example - show custom tour

+
+    
+ +
{{vm.tour.name}}
+ + + + + +
+
+ +

Controller example - show custom tour

+
+    (function () {
+        "use strict";
+
+        function TourController(tourService) {
+
+            var vm = this;
+
+            vm.tour = {
+                "name": "My Custom Tour",
+                "alias": "myCustomTour",
+                "steps": [
+                    {
+                        "title": "Welcome to My Custom Tour",
+                        "content": "",
+                        "type": "intro"
+                    },
+                    {
+                        "element": "[data-element='my-tour-button']",
+                        "title": "Click the button",
+                        "content": "Click the button",
+                        "event": "click"
+                    }
+                ]
+            };
+
+            vm.startTour = startTour;
+
+            function startTour() {
+                tourService.startTour(vm.tour);
+            }
+
+        }
+
+        angular.module("umbraco").controller("My.TourController", TourController);
+
+    })();
+
+ +

Custom step views

+In some cases you will need a custom view for one of your tour steps. +This could be for validation or for running any other custom logic for that step. +We have added a couple of helper components to make it easier to get the step scaffolding to look like a regular tour step. +In the following example you see how to run some custom logic before a step goes to the next step. + +

Markup example - custom step view

+
+    
+ + + + + + + + + + + + + + + + + +
+ + +
+ +
+ +
+ +
+
+ +

Controller example - custom step view

+
+    (function () {
+        "use strict";
+
+        function StepController() {
+
+            var vm = this;
+            
+            vm.initNextStep = initNextStep;
+
+            function initNextStep() {
+                // run logic here before going to the next step
+                $scope.model.nextStep();
+            }
+
+        }
+
+        angular.module("umbraco").controller("My.TourStep", StepController);
+
+    })();
+
+ + +

Related services

+ + +@param {string} model (binding): Tour object + +**/ + (function () { 'use strict'; diff --git a/src/Umbraco.Web.UI.Client/src/common/services/tour.service.js b/src/Umbraco.Web.UI.Client/src/common/services/tour.service.js index 315405cf44..a1cb579433 100644 --- a/src/Umbraco.Web.UI.Client/src/common/services/tour.service.js +++ b/src/Umbraco.Web.UI.Client/src/common/services/tour.service.js @@ -30,80 +30,6 @@ }); } - /** - * @ngdoc method - * @name umbraco.services.tourService#registerTour - * @methodOf umbraco.services.tourService - * - * @description - * Registers a tour in the service - * @param {Object} tour The tour you want to register in the service - * @param {String} tour.name The tour name - * @param {String} tour.alias The tour alias - * @param {Array} tour.steps Array of tour steps - * @param {String} tour.step.title Step title - * @param {DomElement} tour.step.content Step content (pass in any HTML markup) - * @param {DomElement} tour.step.element Highlight a DOM-element - * @param {Boolean} tour.step.elementPreventClick Adds invisible layer on top of highligted element to prevent all clicks and interaction with it - * @param {Number} tour.step.backdropOpacity Sets the backdrop opacity (default 0.4) - */ - function registerTour(newTour) { - validateTour(newTour); - validateTourRegistration(newTour); - tours.push(newTour); - eventsService.emit("appState.tour.updatedTours", tours); - } - - /** - * @ngdoc method - * @name umbraco.services.tourService#registerTours - * @methodOf umbraco.services.tourService - * - * @description - * Registers an array of tours in the service - * @param {Array} tours The tours to register in the service - */ - function registerTours(newTours) { - angular.forEach(newTours, function(newTour){ - validateTour(newTour); - validateTourRegistration(newTour); - tours.push(newTour); - }); - eventsService.emit("appState.tour.updatedTours", tours); - } - - /** - * @ngdoc method - * @name umbraco.services.tourService#unregisterTour - * @methodOf umbraco.services.tourService - * - * @description - * Unregisters a tour in the service - * @param {String} tourAlias The tour alias of the tour you want to unregister - */ - function unregisterTour(tourAlias) { - tours = tours.filter(function( obj ) { - return obj.alias !== tourAlias; - }); - eventsService.emit("appState.tour.updatedTours", tours); - } - - /** - * @ngdoc method - * @name umbraco.services.tourService#unregisterTourGroup - * @methodOf umbraco.services.tourService - * - * @description - * Unregisters a tour in the service - * @param {String} tourGroupName The name of the tour group you want to unregister - */ - function unregisterTourGroup(tourGroup) { - tours = tours.filter(function( obj ) { - return obj.group !== tourGroup; - }); - eventsService.emit("appState.tour.updatedTours", tours); - } - /** * Method to return all of the tours as a new instance */ @@ -334,10 +260,6 @@ var service = { registerAllTours: registerAllTours, - registerTour: registerTour, - registerTours: registerTours, - unregisterTour: unregisterTour, - unregisterTourGroup: unregisterTourGroup, startTour: startTour, endTour: endTour, disableTour: disableTour,