You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: libs/angular/tour/README.md
+3-202Lines changed: 3 additions & 202 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -18,211 +18,12 @@ This package will follow a semver-like format, `major.minor.patch`, in which:
18
18
-`minor`: Introduces new features and (potential) breaking changes
19
19
-`patch`: Introduces bugfixes and minor non-breaking changes
20
20
21
-
For more information about the build process, authors, contributions and issues, we refer to the [ngx-tools](https://github.com/studiohyperdrive/ngx-tools) repository.
21
+
For more information about the build process, authors, contributions and issues, we refer to the [hyperdrive-opensource](https://github.com/studiohyperdrive/hyperdrive-opensource) repository.
22
22
23
23
## Concept
24
24
25
25
With the tour approach of `ngx-tour`, we aim to create a very light-weight bare bones approach to the help tours. The package requires the user to provide their own styling and components for the steps shown during the tour, ensuring a maximized customizability.
26
26
27
-
## Implementation
27
+
## Documentation
28
28
29
-
The implementation of the package consists of a three individual parts, being the `NgxTourService`, the `NgxTourItemDirective` and the `NgxTourStepComponent` abstract class.
30
-
31
-
### Setup
32
-
33
-
`ngx-tour` uses the Angular CDK so it does require an initial setup in order for it to be used properly throughout the application. The following styles need to be imported at root level in order to function correctly.
34
-
35
-
```scss
36
-
@import'@angular/cdk/overlay-prebuilt.css';
37
-
```
38
-
39
-
Throughout the tour, we want to visualize individual steps to the user, usually including a way to navigate between the steps of the tour.
40
-
41
-
In order to do that, we need to provide a default component that is an implementation of the `NgxTourStepComponent` abstract. We do this by using the `provideNgxTourConfiguration` util in our main app providers array.
The core of the tour is the `NgxTourService`, which is a singleton service that handles all tour related methods and observables.
51
-
52
-
We define a tour by providing an array of tour steps to the tour service and running the `startTour` method. At it's core, a tour step only has two required properties, being `title` and `content`.
By default, this step will be rendered in the middle of the screen. Of course, in real world applications, we want to render the step next to a highlighted element. We can do this using by adding the `tourItem` tag of the `NgxTourItemDirective` to an element, and provide the tag to the step. By doing so, the tour will locate the item, and attach the step to it.
59
-
60
-
```html
61
-
<ptourItem="helloWorld">Hello world!</p>
62
-
```
63
-
64
-
```ts
65
-
this.tourService
66
-
.startTour([
67
-
{
68
-
title: 'Hello',
69
-
content: 'World',
70
-
tourItem: 'helloWorld',
71
-
},
72
-
])
73
-
.subscribe();
74
-
```
75
-
76
-
Now whenever the tour navigates, it will try to find the provided element and attach the step to this element. We can provide where we want to render this step by passing a `position`, which can be `above`, `left`, `right` or `below`. By default, this is `below`.
77
-
78
-
When highlighting a step, the service automatically provides a cutout in the backdrop around the element to highlight it. By default, this cutout has a margin of 5px, but this can be overwritten by using the `cutoutMargin` property.
79
-
80
-
```ts
81
-
this.tourService
82
-
.startTour([
83
-
{
84
-
title: 'Hello',
85
-
content: 'World',
86
-
tourItem: 'helloWorld',
87
-
position: 'top',
88
-
cutoutMargin: 10,
89
-
},
90
-
])
91
-
.subscribe();
92
-
```
93
-
94
-
Sometimes, elements in the UI require some time before they're visible, for instance because we're waiting for a loading spinner. We can add an optional amount of time we wish to wait before the tour skips the current steps and moves on to the next step. This can be provided by the `delay` property. By default, the tour service will wait 100 ms before moving on to the next step.
95
-
96
-
```ts
97
-
this.tourService
98
-
.startTour([
99
-
{
100
-
title: 'Hello',
101
-
content: 'World',
102
-
tourItem: 'helloWorld',
103
-
delay: 2000,
104
-
},
105
-
])
106
-
.subscribe();
107
-
```
108
-
109
-
`ngx-tour` also allows for actions to be run throughout the tour. For each step, we have the ability to run provided functions before, when and after an element is visible. We can do this by providing a `beforeVisible`, `onVisible` and `afterVisible` method respectively. This can be useful for use cases where we want to route during the tour.
110
-
111
-
```ts
112
-
this.tourService
113
-
.startTour([
114
-
{
115
-
title: 'Hello',
116
-
content: 'World',
117
-
tourItem: 'helloWorld',
118
-
beforeVisible: () => {
119
-
this.router.navigate(['second-page']);
120
-
},
121
-
onVisible: (step, index) => {
122
-
returnthis.analyticsService.sentEvent({ stepReached: index });
123
-
},
124
-
afterVisible: () => {
125
-
this.router.navigate(['third-page']);
126
-
},
127
-
},
128
-
])
129
-
.subscribe();
130
-
```
131
-
132
-
Individual steps in the tour can be further customized with several properties, `component`, `disableBackdrop`, `data` and `stepClass`.
133
-
134
-
First of, we can override the default component with a custom one using the `component` property. This is useful in use-cases where we want to have a step look completely different from the default step, like for instance an introduction step.
135
-
136
-
Using `disableBackdrop` and `stepClass` we can have even more visual control over the step, by either disabling the backdrop or attaching a custom class to the step using the properties respectively.
137
-
138
-
Finally, we can pass extra data to a step by using the `data` property. This allows for full customizability beyond the default title and content properties.
139
-
140
-
```ts
141
-
this.tourService
142
-
.startTour([
143
-
{
144
-
title: 'Hello',
145
-
content: 'World',
146
-
stepClass: 'this-is-my-custom-class',
147
-
component: SpecialIntroductionStepComponent,
148
-
disableBackdrop: true,
149
-
data: { userName: 'Mark' },
150
-
},
151
-
])
152
-
.subscribe();
153
-
```
154
-
155
-
Next to the tour, we can also provide a closing function and a startIndex to the `startTour` method. This can be used to route back to the start page whenever a user has gone through a tour or can allow us to start a tour at a specific index.
156
-
157
-
```ts
158
-
this.tourService.startTour(
159
-
[...],
160
-
(step, index) => {
161
-
returnthis.analyticsService.tourStoppedAt(index);
162
-
},
163
-
2
164
-
).subscribe()
165
-
```
166
-
167
-
Finally, the `NgxTourService` also provides a set of Observables we can listen to. Using `tourStarted$` and `tourEnded$` respectively, we can listen to the start and/or end of the tour.
168
-
169
-
Using `currentStep$`, `currentIndex$`, `previousStep$` and `currentTour$`, we can listen to the states of the current step, the previous step and the currently displayed tour.
170
-
171
-
### NgxTourItemDirective
172
-
173
-
The `NgxTourItemDirective` is used to highlight elements during the tour. Simply using the `tourItem` tag will match the provided input with the corresponding step.
174
-
175
-
When an item is highlighted, the item also gets the `ngx-tour-item-active` class.
176
-
177
-
### NgxTourStepComponent
178
-
179
-
The `NgxTourStepComponent` presents us with 7 Inputs and one Output we need to handle the tours.
180
-
181
-
By default, the two most important Inputs are `title` and `content`, which correspond with the two data properties we passed in the step. Additionally, the amount of steps in the tour and the current index of the step can be visualized using `amountOfSteps` and `currentIndex`. To maximize customisability, we can also pass a `data` property to the component. This data can be anything, and can be used to enrich a step.
182
-
183
-
For accessibility reasons it is important that there is an element in the tour-step that has the tag `#stepTitle`. By doing so, the package will automatically set the correct `aria-labbeledby` properties.
184
-
185
-
The `position` and `stepClass` inputs are used to automatically set classes to the tour step, but can still be used freely. By default, the tour step component always gets the `ngx-tour-step` class, depending on its position it will also have a corresponding `ngx-tour-step-position-left|right|below|above` class. The step class will be set automatically as well.
186
-
187
-
In order to navigate through the tour and close it when needed, the component has an Output called `handleInteraction` that takes three possible states, being `next`, `back` and `close`. Each of these interactions will continue the tour, go back in the tour or close the tour respectively.
188
-
189
-
### useMockDataDuringTour
190
-
191
-
During a tour, we might want to show different data in our views, to ensure that everything fits just right for the tour. We can use the `useMockDataDuringTour` operator to do so! Provide mock data to the operator, and depending on whether the tour is active, the correct data will be shown.
This operator only works within an injection context, and therefor cannot be used in methods or outside of the constructor.
202
-
203
-
## Known issues
204
-
205
-
### Navigation
206
-
207
-
When the tour requires routing between multiple pages, we suggest including an `onClose` function that routes back to the original page when the tour closes. This ensures that the tour will go back to the initial page, regardless of where the user decides to close the tour.
208
-
209
-
It should be noted though, that this can sometimes cause issues with the changeDetection, of which we currently don't have an in-package solution. The current fix is to run the change detection manually after the routing, which can be done in the `onClose` function.
210
-
211
-
```ts
212
-
this.tourService.startTour(
213
-
[...],
214
-
() => {
215
-
returnfrom(this.router.navigate([''])).pipe(
216
-
tap(() => {
217
-
this.cdRef.detectChanges();
218
-
})
219
-
);
220
-
}
221
-
)
222
-
```
223
-
224
-
### Auto scroll
225
-
226
-
The `NgxTourService` will always try to make sure the active element is visible. For this, we use the [scrollIntoView()](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView) method. It is possible that this will fail in case the previous element is not found.
227
-
228
-
A solution would be to implement a custom scrolling method to scroll the viewport until the desired element is centered.
29
+
To find more information regarding this package, we refer to [our documentation platform](https://open-source.studiohyperdrive.be/docs/angular/tour/introduction).
0 commit comments