TourGuideJS

Description

TourGuideJS is a component for OutSystems applications that integrates the TourGuideJS library to offer guided tours on the application's frontend. It allows you to easily create an introductory walkthrough for new users, guiding them through key interface elements.

Features

• Automatic display of guided tours on OutSystems screens.

• Manual initialization of tours via a public action.

• Dynamic configuration of tour steps through input parameters.

• Saves the completion status in Local Storage to avoid repeating tours for the same user.

Inputs of the TourGuide Block

• TourName (Text) (Required): Unique identifier for the tour (used for Local Storage control).

• WidgetIdList (List of Structures) (Required): List of items defining the elements to be highlighted in the tour. Each item must contain:

  • Content (Text) (Required): Text displayed to the user.

  • WidgetId (Text) (Required): Identifier of the widget to highlight.

  • Title (Text) (Optional): Step title.

StartTour Action

The component also provides a public action called StartTour, which allows manual initialization of the tour.

Input Parameters:

• TourName (Text) (Required): Unique identifier for the tour.

• WidgetIdList (List of Structures) (Required): List of tour steps.

Notes about StartTour:

• Useful when the tour should be triggered by user action (e.g., pressing a "Start Tour" button).

• Completion status is still saved automatically in Local Storage.

Outputs

• No direct outputs. The tour is launched automatically or manually, and Local Storage controls whether it reappears.

Dependencies

• JavaScript library: TourGuideJS (automatically loaded by the component).

• Local Storage in the browser.

Example of Use

Automatic Display

1. Add the TourGuide block to the desired screen.

2. Configure the inputs:

   • TourName: Example InitialPageTour

   • WidgetIdList: See the example below.

Manual Initialization

1. Call the StartTour action from your screen flow or event.

2. Pass the TourName and WidgetIdList.

Example of WidgetIdList

Each item represents one step:

• Item 1:

  • Content: "Welcome to the system!"

  • WidgetId: "btnStart"

  • Title: "Getting Started"

• Item 2:

  • Content: "Here you can find your reports."

  • WidgetId: "lblReports"

  • Title: (optional, can be left blank)

• Item 3:

  • Content: "Click here to create a new item."

  • WidgetId: "btnNew"

  • Title: "Create Item"

Tip: Ensure the widgets have the Name property properly set so that the WidgetId is available.

Notes

• Use only one tour per page to avoid conflicts.

• TourName must be unique to prevent overwriting tour completion data.

• If you change a tour (adding or removing steps), users might need to clear Local Storage to see the updates.

• Always check that the Widget IDs are correctly set.

Additional Information

• For full configuration options and advanced use, visit the official TourGuideJS Documentation.

• TourGuideJS is open source and distributed under the MIT License.