Overview

Simple Guided Tour helps you guide users through your Mendix pages by highlighting UI elements and showing instruction cards step by step.

The widget uses a simple JSON configuration to define each tour step. You can target elements using CSS selectors and display an instruction card aligned relative to the selected container.

The card position can be set to top, right, bottom, or left. If the selected position does not have enough space, the widget automatically places the card in the best available position to ensure a smooth user experience.

The tour can start automatically when the page loads or be controlled using a Boolean attribute. You can also assign a tour name, customize button colors, and trigger actions when the tour is completed or when steps change.

This widget is lightweight, easy to configure, and ideal for user onboarding, feature walkthroughs, and improving usability without complex setup.

Documentation

Simple Guided Tour is used to guide users through important actions on a Mendix page.

Typical use cases include:

• Onboarding new users on first login
• Explaining buttons, forms, and data grids
• Guiding users through complex pages
• Highlighting new or updated features

The widget displays an instruction card aligned to a specific UI element and walks users step by step through the page.

✅ Features and Limitations

Features

• Step-by-step guided tour using JSON configuration
• Target UI elements using CSS class selectors
• Instruction card alignment: top, right, bottom, left
• Automatically selects the best position if space is not available
• Auto-start or manual control using a Boolean attribute
• Custom tour name
• Customizable button color
• Events for tour completion and step change

Limitations

• Target elements must be visible on the page
• Requires correct CSS class names on UI elements
• JSON must be valid (incorrect JSON will not render the tour)

✅ Dependencies

• Mendix Studio Pro (supported LTS versions)
• No external JavaScript or third-party libraries required

✅ Installation

1. Download the widget from the Mendix Marketplace
2. Import it into your Mendix app
3. Build and run the application once
4. The widget will appear in the toolbox under Custom Widgets

✅ Configuration

Step 1: Create Helper Entity

Create an entity (example: StartTourHelper) with the following attributes:

Step 2: Add CSS Classes to UI Elements

Add CSS classes to the widgets you want to highlight:

• Button → newemp
• Edit button → editemp
• Container → customcontainer

Example:

Step 3: Add Widget to Page

1. Place the Simple Guided Tour widget on the page
2. Set datasource to the helper entity
3. Map widget properties:
   • Show Coach Mark → enable
   • Steps JSON → Steps
   • Auto Start → AutoStart
   • Tour Name → TourName

Step 4: Example JSON Configuration

✅ Supported positions: top, right, bottom, left

✅ If space is unavailable, the card is placed automatically in the best position

✅ Known Bugs

• Tour may not start if the target element is hidden or not yet loaded
• Incorrect CSS selector will prevent the step from showing

✅ Frequently Asked Questions (FAQ)

Q: Can I start the tour manually?

Yes. Set AutoStart to false and control it using the enable Boolean attribute.

Q: What happens if position is not provided?

The widget automatically chooses the best available position.

Q: Can I use multiple tours on one page?

Yes, by using different TourName values.

Q: Do I need JavaScript knowledge?

No. Configuration is done using JSON and Mendix attributes.