ruclib-tour-guide

A component for creating a tour guide that provides information and guidance about a specific feature or functionality to the user.

Installation guide

To use the Tour Guide component, you can install the entire RUC library or just this specific component.

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Tour Guide component

npm install @ruc-lib/tour-guide

📦 Version Compatibility

Please ensure you install the correct version of @ruc-lib/tour-guide based on your Angular version.

| Angular Version | Compatible @ruc-lib/tour-guide Version | |--------------------|---------------------------------------------| | 15.x.x | npm install @ruc-lib/tour-guide@^3.0.0 | | 16.x.x | npm install @ruc-lib/tour-guide@^3.0.0 |

Usage

1. Import the Component

In your Angular component file (e.g., app.component.ts), import the RuclibTourGuideComponent:

import { Component } from '@angular/core';

// For Complete Library
import { RuclibTourGuideComponent } from '@uxpractice/ruc-lib/tour-guide';

// For Individual Package
import { RuclibTourGuideComponent } from '@ruc-lib/tour-guide';

@Component({
  selector: 'app-root',
  imports: [RuclibTourGuideComponent],
  templateUrl: './app.component.html',
})
export class AppComponent {
  // Component code here
}

2. Use the Component

In your component's template, use the <uxp-ruclib-tour-guide> selector and pass the configuration object to the rucInputData input and the data array to the dataSource input.

<uxp-ruclib-tour-guide 
    [rucInputData]="tourGuideConfig"
    [customTheme]="customTheme" 
    (rucEvent)="passEvent($event)" 
    [dataSource]="tourGuideData">
</uxp-ruclib-tour-guide>

API Reference

Component Inputs

| Input | Type | Description | |----------------|--------------------|---------------------------------------------------| | rucInputData | TourGuideConfig | The main configuration object for the tour guide. | | customTheme | string | An optional CSS class for custom theming. | | dataSource | TourGuideData | Data for the tour guide. |

Component Outputs

| Output | Type | Description | |-----------|-----------|---------------------------------------------------| | rucEvent| any | Emits events related to tour guide actions (e.g., 'skip', 'next', 'finish'). |

TourGuideConfig

This is the main configuration object for the Tour Guide component.

| Property | Type | Description | |--------------------------|---------------------------------------------------------------------|-----------------------------------------------------------------------| | type | 'simple' \| 'advance' | Type of tour guide (e.g., 'simple', 'advance'). | | showSkipButton | boolean | To toggle the visibility of the skip button. | | buttonsFontSize | string | Configure the font size of buttons. | | titleFontSize | string | Configure the font size of the title. | | contentFontSize | string | Configure the font size of the main content. | | buttonsAlignment | 'start' \| 'center' \| 'end' \| 'space-between' \| 'space-around' | Change the alignment of buttons. | | stepCountAlignment | 'start' | 'center' | 'end' | Change the alignment of step count. | | stepCountStartText | string | Text to display at the start of the step count (e.g., 'Step'). | | stepCountMiddleText | string | Text to display in the middle of the step count (e.g., 'of'). | | skipButtonText | string | Text for the skip button. | | prevButtonText | string | Text for the previous button. | | nextButtonText | string | Text for the next button. | | finishButtonText | string | Text for the finish button. | | highlightBorderColor | string | Color of the highlight border around the guided element. | | highlightBorderWidth | string | Width of the highlight border around the guided element. | | defaultPopupWidth | string | Default width of the tour guide popup. |

TourGuideData

This array of objects defines the content for each step of the tour guide.

| Property | Type | Description | |------------|-------------------------------------------------------------|-----------------------------------------------------------------------| | title | string | Title of the tour guide step. | | content | string | Main content/description for the tour guide step. | | selector | string (Only for 'advance' type) | CSS selector for the element to highlight in 'advance' mode. | | position | 'top' \| 'bottom' \| 'left' \| 'right' \| 'auto' | Position of the popup relative to the highlighted element. | | shape | '' \| 'rounded' \| 'rectangle' \| 'circle' | Shape of the description popup. | | width | string | Custom width for the popup of the current step. |

Example Configuration

Here's an example of how to configure the Tour Guide component in your component's TypeScript file.

import { Component } from '@angular/core';

// For Complete Library
import { TourGuideConfig, TourGuideData } from '@uxpractice/ruc-lib/tour-guide';

// For Individual package
import { TourGuideConfig, TourGuideData } from '@ruc-lib/tour-guide';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
    tourGuideConfig: TourGuideConfig = {
    type: 'advance',
    showSkipButton: true,
    buttonsFontSize: '14px',
    titleFontSize: '18px',
    contentFontSize: '14px',
    buttonsAlignment: 'end',
    stepCountAlignment: 'center',
    stepCountStartText: 'Step',
    stepCountMiddleText: 'of',
    skipButtonText: 'Skip Tour',
    prevButtonText: 'Previous',
    nextButtonText: 'Next',
    finishButtonText: 'Finish',
    highlightBorderColor: '#007bff',
    highlightBorderWidth: '3px',
    defaultPopupWidth: '300px'
  };

  tourGuideData: TourGuideData[] = [
    {
      title: 'Welcome to Our App!',
      content: 'This tour will guide you through the main features.',
      selector: '', // No specific selector for the first step
      position: 'auto',
      shape: 'rounded',
      width: '350px'
    },
    {
      title: 'Navigation Bar',
      content: 'This is where you can navigate to different sections of the application.',
      selector: '#navbar', // Replace with your actual selector
      position: 'bottom',
      shape: 'rectangle',
      width: '300px'
    },
    {
      title: 'User Profile',
      content: 'Click here to view and manage your profile settings.',
      selector: '#user-profile-icon', // Replace with your actual selector
      position: 'left',
      shape: 'circle',
      width: '280px'
    },
    {
      title: 'Main Content Area',
      content: 'All your important data and features are displayed here.',
      selector: '#main-content', // Replace with your actual selector
      position: 'top',
      shape: 'rounded',
      width: '400px'
    },
    {
      title: 'Notifications',
      content: 'Stay updated with the latest notifications.',
      selector: '#notifications-bell', // Replace with your actual selector
      position: 'right',
      shape: 'rectangle',
      width: '250px'
    }
  ];

  passEvent(event: any) {
    console.log('Tour Guide Event:', event);
  }
}

⚠️ IMPORTANT: Custom Theme Usage in Angular Material

When implementing custom themes, such as:

.custom-theme-1 {
  @include angular-material-theme($custom-theme);
}

// You must also include the typography mixin to ensure text styles are applied correctly as shown below:
.custom-theme-1 {
  @include angular-material-theme($custom-theme);
  @include mat.typography-level($theme-custom-typography-name, body-1);
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Tour Guide component. If you have any feedback or suggestions, please let us know!