[Tutorial] Building a Tour Guide for your Angular product.

Most of us would have hired a tour guide while traveling to new cities to guide us to visit the city's popular tourist spots. A tour guide will always lead them to the right places and walk through the popular tourist destinations. A Tour Guide for a product works similarly.

Tour guidance is triggered as the user explores a new product or an application. It allows users to learn at their own pace. This uses methods such as tooltips, overlays, models, and alerts hinting optimal use of an interface within the context of everyday use.

Guided tour component uses SCSS and typescript. This allows us to use selectors to step users through workflows and introduce them to our application. It also provides a customizable theme and many other features.

Using the ngx-guided-tour npm module we can make a tour guide for our product that would easily guide our users through our product features or other functionalities which we are providing. This would help the users to learn the product in a better way and have a good understanding.

In this tutorial, let’s learn how to build ngx-guided-tour for an Angular based product.

Steps for creating an ngx-guided-tour :

• Create an Angular project and install the npm module for guided tour component:

npm install ngx-guided-tour --save

• Import modules to app.module.ts as given below for GuidedTour Module and Services

import {GuidedTourModule, GuidedTourService} from 'ngx-guided-tour';
@NgModule({
imports: [
GuidedTourModule,
...
],
providers: [
GuidedTourService,
...
],

• Add ngx-guided-tour component tag to your app.component.html.

<ngx-guided-tour></ngx-guided-tour>

• Define your GuidedTour interface in the app.component.ts. In this, you give the tour component an identifier and steps for the tour guide to follow.

interface GuidedTour {
/** Identifier for tour */
tourId: string;
/** Use orb to start tour */
useOrb?: boolean;
/** Steps for the tour */
steps: TourStep[];
/** Function will be called when tour is skipped */
skipCallback?: (stepSkippedOn: number) => void;
/** Function will be called when tour is completed */
completeCallback?: () => void;
/** Minimum size of screen in pixels before the tour is run, if the tour is resized below this value the user will be told to resize */
minimumScreenSize?: number;
/** Dialog shown if the window width is smaller than the defined minimum screen size. */
resizeDialog?: {
/** Resize dialog title text */
title?: string;
/** Resize dialog text */
content: string;
}
}

Guided Tour Interface :

1. tourId — unique Identifier string
2. useOrb (optional) — Use orb to start the tour. The tour will start when the user hovers over the orb. The orb is based on the positioning of the first step.
3. steps — List of TourSteps that the tour steps through.
4. skipCallback (optional) — Function called when the tour is skipped. Passes the index of the step that was skipped on.
5. completeCallback (optional) — Function is called when the tour is completed (done is pressed).
6. minimumScreenSize (optional) — Will enforce a minimum size before the tour will start (in pixels). If the window is resized below this size during a tour a message will inform the user to expand their browser.
7. preventBackdropFromAdvancing (optional) — Prevents the tour from advancing by clicking the backdrop. This should only be set if you are completely sure your tour is displaying correctly on all screen sizes otherwise a user can get stuck.

• The next step is to define your TourStep interface. This is a step where you provide the GuidedTour component with selectors and content for which you want to show in your Guide Tour.

interface TourStep {
/** Selector for element that will be highlighted */
selector?: string;
/** Tour title text */
title?: string;
/** Tour step text */
content: string;
/** Where the tour step will appear next to the selected element */
orientation?: Orientation | OrientationConfiguration[];
/** Action that happens when the step is opened */
action?: () => void;
/** Action that happens when the step is closed */
closeAction?: () => void;
/** Skips this step, this is so you do not have create multiple tour configurations based on user settings/permissions */
skipStep?: boolean;
/** Adds some padding for things like sticky headers when scrolling to an element */
scrollAdjustment?: number;
/** Adds default padding around tour highlighting. Does not need to be true for highlightPadding to work */
useHighlightPadding?: boolean;
/** Adds padding around tour highlighting in pixels, this overwrites the default for this step. Is not dependent on useHighlightPadding being true */
highlightPadding?: number;
}

TourStep Interface :

1. selector (optional) — If no selector is present then the tour will show a step in the middle of the page. If a selector is set but not found, it will skip the step.
2. title (optional) — Title that shows on the top of the step.
3. content — Content of the tourstep. Uses inner HTML so tags will work.
4. orientation (optional) — Defaults to top. Accepts bottom, bottomLeft,
5. bottomRight, center, left, right, top, topLeft, and topRight. It can be taken from the guided-tour.constants.ts file. This also supports an array of OrientationConfiguration. When an array of OrientationConfiguration is passed to it, it will use the smallest maximum size the screen can fit into. This is useful for tablet or mobile flexing. It will also change when the user resizes the screen.
6. action (optional) — Function called at the beginning of the step. This is executed before the tour step is rendered allowing for content to appear.
7. closeAction (optional) — Function called after the step is ended.
8. scrollAdjustment (optional) — Number used to adjust where to scroll to on a step and when to scroll.
9. useHighlightPadding (optional) — Adds some extra padding around the highlight for elements that may need just a little more on the highlight.

• The next step is defining Orientation configuration which will be used for giving in which direction should the Tour Guide appear.

interface OrientationConfiguration {
/** Where the tour step will appear next to the selected element */
orientationDirection: Orientation,
/** When this orientation configuration starts in pixels */
maximumSize?: number
}

• Then use the GuidedTourService to start your tour by calling GuidedTourService.startTour. If a selector is not found, the step will be skipped.

ngx-guided-tour component inputs :

1. topOfPageAdjustment (optional) — Used to adjust values to determine scroll. This is a blanket value to adjust for things like navbars.
2. tourStepWidth (optional) — Sets the width of tour steps.
3. minimalTourStepWidth (optional) — The minimal width of tour steps.
4. skipText (optional) — The text of the skip button.
5. nextText (optional) — The text of the next button.
6. doneText (optional) — The text of the done button (button on the last step).
7. closeText (optional) — The text of the close button (shown on the resize popup).
8. backText (optional) — The text of the back button.
9. progressIndicatorLocation (optional) — The location of the progress indicator (e.g. “1/5”). It can be placed inside the next button (default), at the top of the tour block or hidden. If set to ProgressIndicatorLocation.TopOfTourBlock the indicator will be shown on all steps. If it’s shown inside the next button, it will be hidden in the last step.
10. progressIndicator (optional) — A ng-template to customize the progress indicator (e.g. “1/5”). The following context is provided:
    - currentStepNumber: The number of the current step (starting with 1)
    - totalSteps: The total number of steps.

• Import guided-tour-base-theme.scss to your main style import page. If you want to create your own theme add it after your defined constants. The supported style variables are given below.

@import '../node_modules/ngx-guided-tour/scss/guided-tour-base-theme.scss';

Style variables :

These SASS variables have default values, but they can be set to customize the tour elements. Define them before importing guided-tour-base-theme.scss.

• $tour-skip-link-color : Skip button color.
• $tour-text-color: Color of the text that is in the tour step box.
• $tour-next-text-color : Next button text color.
• $tour-zindex : Base z-index for the tour.
• $tour-orb-color: Color of the orb to start a tour.
• $tour-next-button-color : Next button color.
• $tour-next-button-hover : Next button hover color.
• $tour-back-button-color : Back button color.
• $tour-shadow-color: Shadow backdrop that is used for the tour.
• $tour-step-color: Background color for the tour step box.

That’s all, once we are done with all the above, our tour guide will be all set. I am also sharing a few images of the tour guide implemented in our product BlockSurvey. I hope, this gives you a great feel about the tour-guide and will help you to get started.

Implementation of Guided-Tour in BlockSurvey :

BlockSurvey provides a way to embed surveys/polls/forms using widgets to any external webpage.

BlockSurvey | Privacy-focused surveys, polls & forms

Screenshots of the Guided Tour implemented in BlockSurvey :

Dashboard of BlockSurvey with Tour Guide Feature.

ngx-guided-tour for BlockSurvey

Also, feel free to explore and experience the guided tours by signing in to the product.

Summary :

Using the ngx-guided-tour npm module we can easily build a tour guide for our product that would guide users through our product features or other functionalities which we are providing. This allows users to learn at their own pace and have a good understanding of the product.

Thanks for reading the tutorial. Requesting you to share your thoughts in the comments below! Let’s build effective tour-guides !!

References :

• Ngx-Guided-Tour.
• Tour-Guide Demo.

About Blocksurvey

BlockSurvey is a privacy-focused platform to create surveys, polls, & forms with complete confidentiality. Through BlockSurvey, all your data is encrypted end to end and only you can see it. You own your data. It’s your digital right. There are zero trackers and we keep you as anonymous to the data collectors. Our platform utilizes Blockstack and helps in maintaining privacy and anonymity, resulting in effective surveys and polls. Try out by creating your surveys and polls with us.