add documentation to the tour component
This commit is contained in:
Mads Rasmussen
@@ -1,3 +1,187 @@
|
||||
/**
|
||||
@ngdoc directive
|
||||
@name umbraco.directives.directive:umbTour
|
||||
@restrict E
|
||||
@scope
|
||||
|
||||
@description
|
||||
<b>Added in Umbraco 7.8</b>. 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 <a href="https://our.umbraco.org/projects/starter-kits/the-starter-kit/">The Starter Kit</a> in Umbraco 7.8
|
||||
|
||||
<h1><b>Extending the help drawer with custom tours</b></h1>
|
||||
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 <i>App_Plugins/{MyPackage}/backoffice/tours/{my-tour}.json</i> and it will automatically be
|
||||
picked up by Umbraco and shown in the Help-drawer.
|
||||
|
||||
<h3><b>The tour object</b></h3>
|
||||
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.
|
||||
<pre>
|
||||
// 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
|
||||
}
|
||||
</pre>
|
||||
<pre>
|
||||
// A tour step object
|
||||
{
|
||||
"title": "Title",
|
||||
"content": "<p>Step content</p>",
|
||||
"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
|
||||
}
|
||||
</pre>
|
||||
|
||||
<h1><b>Adding tours to other parts of the Umbraco backoffice</b></h1>
|
||||
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.
|
||||
|
||||
<h1><b>Using the tour service</b></h1>
|
||||
<h3>Markup example - show custom tour</h3>
|
||||
<pre>
|
||||
<div ng-controller="My.TourController as vm">
|
||||
|
||||
<div>{{vm.tour.name}}</div>
|
||||
<button type="button" ng-click="vm.startTour()">Start tour</button>
|
||||
|
||||
<!-- This button will be clicked in the tour -->
|
||||
<button data-element="my-tour-button" type="button">Click me</button>
|
||||
|
||||
</div>
|
||||
</pre>
|
||||
|
||||
<h3>Controller example - show custom tour</h3>
|
||||
<pre>
|
||||
(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);
|
||||
|
||||
})();
|
||||
</pre>
|
||||
|
||||
<h1><b>Custom step views</b></h1>
|
||||
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.
|
||||
|
||||
<h3>Markup example - custom step view</h3>
|
||||
<pre>
|
||||
<div ng-controller="My.TourStep as vm">
|
||||
|
||||
<umb-tour-step on-close="model.endTour()">
|
||||
|
||||
<umb-tour-step-header
|
||||
title="model.currentStep.title">
|
||||
</umb-tour-step-header>
|
||||
|
||||
<umb-tour-step-content
|
||||
content="model.currentStep.content">
|
||||
|
||||
<!-- Add any custom content here -->
|
||||
|
||||
</umb-tour-step-content>
|
||||
|
||||
<umb-tour-step-footer class="flex justify-between items-center">
|
||||
|
||||
<umb-tour-step-counter
|
||||
current-step="model.currentStepIndex + 1"
|
||||
total-steps="model.steps.length">
|
||||
</umb-tour-step-counter>
|
||||
|
||||
<div>
|
||||
<umb-button
|
||||
size="xs"
|
||||
button-style="success"
|
||||
type="button"
|
||||
action="vm.initNextStep()"
|
||||
label="Next">
|
||||
</umb-button>
|
||||
</div>
|
||||
|
||||
</umb-tour-step-footer>
|
||||
|
||||
</umb-tour-step>
|
||||
|
||||
</div>
|
||||
</pre>
|
||||
|
||||
<h3>Controller example - custom step view</h3>
|
||||
<pre>
|
||||
(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);
|
||||
|
||||
})();
|
||||
</pre>
|
||||
|
||||
|
||||
<h3>Related services</h3>
|
||||
<ul>
|
||||
<li>{@link umbraco.services.tourService tourService}</li>
|
||||
</ul>
|
||||
|
||||
@param {string} model (<code>binding</code>): Tour object
|
||||
|
||||
**/
|
||||
|
||||
(function () {
|
||||
'use strict';
|
||||
|
||||
|
||||
Reference in New Issue
Block a user