Overview

React Tour adds a guided tour to a Mendix page. The tour dims the page, highlights one element at a time and shows a small popover with your text next to it. Users move through the steps with the arrow buttons, the navigation dots or the keyboard (Left, Right and Esc).

You write the steps as JSON text in a String attribute. Each step has a CSS selector for the element to highlight and the text to show, for example [{"selector": ".custombutton1", "content": "This is my custom button 1"}].

The tour opens when the Start Tour attribute is true. When the user closes it, the widget sets Start Tour back to false, so you can open the tour again from a button, microflow or nanoflow.

All settings are attributes, so you can change them at runtime:

- accent colour

- number badge

- close button

- navigation dots

- arrow buttons

- keyboard navigation

- closing by clicking the mask

- focus lock

- the step to start at

Use it for onboarding new users, explaining a new feature after a release, or guiding users through a complex form.

Documentation

Typical usage scenario

Use React Tour to guide users through a page step by step. The tour dims the page, highlights one element at a time and shows your text next to it.

Where it helps:

- An onboarding tour for new users on their first page

- Explaining a new feature after a release

- A "Help" button that walks users through a complex form

- Training or demo mode in an app

You write the steps as JSON in a String attribute and open the tour by setting a Boolean attribute to true. So you can start it from a button, microflow or nanoflow, and open it again later.

Features and limitations

Features:

- Highlight any element that has a CSS class, or matches another CSS selector

- Steps as a JSON array; extra reactour step fields such as position, style and stepInteraction are supported

- Start the tour by setting a Boolean attribute to true. The tour can be opened again after it's closed, because the widget sets the attribute back to false.

- Number badge, close button, arrow buttons, navigation dots and dot numbers can each be turned on or off

- Keyboard navigation (Left, Right, Esc), which can be turned off

- Accent colour for the badge and the current dot

- Start at any step (Start At, counted from 0)

- Empty or invalid Steps JSON doesn't break the page; an error is written to the browser console

- Works in the Mendix 10 React client

Limitations:

- All settings are attributes; you can't type static values in the widget properties.

- The step text is plain text. You can't use HTML or Mendix widgets inside the popover.

- Step options that need JavaScript functions (such as action) can't be used, because steps are JSON.

- Target elements must be on the page when the tour opens, not in a closed tab, a hidden container or another page.

- Start Tour is only set back to false when the attribute is editable.

Dependencies

- Mendix Studio Pro 10.24.17 or a later 10.24 version

Installation

1. Download the widget from the Marketplace, or mendix.Reacttour.mpk from the GitHub release Version2.1.0.

2. Copy it into the widgets folder of your app and press F4 (App > Synchronize App Directory) in Studio Pro.

3. The widget appears in the Toolbox as Reacttour.

Upgrading from 1.0.0:

1. Replace the old mendix.Reacttour.mpk in the widgets folder and press F4.

2. If Studio Pro reports that the widget definition has changed, right-click the error and choose Update all widgets.

3. Important: in 1.0.0, Close With Mask, Show Buttons, Show Close Button, Show Navigation, Show Navigation Number and Show Number were always on. In 2.1.0 they follow their attribute. Set these attributes to true to keep the old look.

4. If the running app still shows the old widget, stop it, choose App > Clean Deployment Directory, and run it again.

Configuration

1. Give each element you want to highlight a class in Studio Pro (Properties > Appearance > Class), for example tour-new-order.

2. Create an entity with a String attribute (unlimited length) for the steps and a Boolean attribute for Start Tour.

3. Set the steps JSON in the data source microflow or nanoflow, for example:

[{"selector": ".tour-new-order", "content": "Click here to add a new order"}]

4. Add a data view with this entity and place the Reacttour widget inside it. Select the Steps and Start Tour attributes.

5. Optionally, select attributes for the other settings:

- Accent Color (String, default #007aff)

- Close With Mask, Disable Dot Navigation, Disable Keyboard Navigation and Disable Focus Lock

- Show Buttons, Show Close Button, Show Navigation, Show Navigation Number and Show Number

- Start At (Integer, counted from 0)

Settings without an attribute use their default.

6. Set Start Tour to true to open the tour, for example from a button with a Change object action, or in the data source.

Known bugs

No known bugs.

Report issues at https://github.com/bharathidas/Reactour/issues

Frequently Asked Questions

The tour doesn't open. What should I check?

Start Tour must be true, and Steps must be a valid JSON array. Check the browser console; the widget writes an error when Steps isn't valid JSON.

How do I open the tour again after the user closed it?

Set Start Tour to true again. The widget sets it back to false when the tour closes; the attribute must be editable.

After upgrading from 1.0.0, the close button or the dots are gone. Why?

In 1.0.0 these settings were always on. In 2.1.0 they follow the attribute. Set the attribute to true.

Can I start the tour at a later step?

Yes. Select an Integer attribute for Start At: 0 is the first step, 1 the second, and so on.