Form Tours in Frappe Framework v15

What Are Form Tours in Frappe?

Form Tours in Frappe Framework v15 are guided, step-by-step UI walkthroughs that help users understand how to use a specific DocType form. They highlight fields, buttons, and actions directly on the form, improving onboarding, usability, and feature discoverability in ERPNext.
Form Tours are implemented using the Tour DocType and are rendered within the Frappe Desk.

Why Use Form Tours in ERPNext?

Form Tours reduce training effort and improve user adoption by explaining workflows contextually, exactly where users perform actions.

Key Benefits

• Faster user onboarding
• Reduced support and training costs
• Improved form usability
• Better feature adoption

Who Should Use Form Tours?

Target Audience

• ERPNext Developers
• Frappe Framework Developers
• ERP Implementation Consultants
• Product & UX Teams

Technical Prerequisites

• Frappe Framework v15
• Understanding of DocTypes and Forms
• Desk access with customization permissions

How Do Form Tours Work in Frappe v15?

Form Tours are defined using the Tour DocType, where each tour contains multiple steps. Each step targets a specific UI element on a form using selectors such as field names or buttons.

Core Components

• Tour DocType
• Tour Steps (Child Table)
• UI Selectors (fieldname, button, CSS selector)

Module: Desk

Verified Source (v15): frappe/public/js/frappe/ui/tour.js

How to Create a Form Tour in Frappe v15?

Step 1: Create a New Tour

1. Go to Awesome Bar → Tour
2. Click New
3. Enter a Tour Name
4. Set the Reference DocType (e.g., Sales Invoice)
5. Enable Is Standard if applicable

Step 2: Add Tour Steps

Each step explains one UI element or action.

Common Step Fields

• Title – Heading for the step
• Description – Instruction shown to the user
• UI Element – Target element (field or button)
• Position – Tooltip placement

Steps are executed sequentially when the tour starts.

How Are UI Elements Identified in Form Tours?

Frappe v15 supports targeting UI elements using:

• Field names (DocType fields)
• Primary and custom buttons
• Specific form sections

This ensures tours remain stable even when layouts change.

How to Start a Form Tour?

Form Tours are triggered automatically when configured, or manually using the Help → Tours menu in the Desk. They are context-aware and only appear when the referenced DocType form is opened.

Real-World ERPNext Use Cases

Industry Relevance

• Sales: Guiding users through Sales Invoice creation
• Manufacturing: Explaining BOM or Work Order forms
• HR: Employee onboarding forms
• Finance: Journal Entry walkthroughs

Form Tours are especially useful for complex business workflows.

Best Practices for Designing Effective Form Tours

• Keep steps short and focused
• Explain why an action matters, not just what
• Avoid too many steps in one tour
• Update tours when form fields change
• Use clear, user-friendly language

Common Issues and Troubleshooting

Tour Step Not Highlighting Correctly

• Verify the fieldname or button exists
• Ensure the form is fully loaded
• Avoid custom CSS selectors unless necessary

Tour Not Showing

• Confirm the DocType matches
• Ensure the tour is enabled
• Check user permissions

Advanced Usage Considerations

Form Tours vs Workspace Tours

Use Form Tours for task-level onboarding.

Integration Patterns

Form Tours integrate seamlessly with:

• Custom DocTypes
• ERPNext Standard Forms
• Custom Apps
• Desk Customization

They complement client scripts and help documentation.

Official References

Form Tours Documentation (v15):

https://docs.frappe.io/framework/user/en/form-tours

Frappe GitHub (v15):

https://github.com/frappe/frappe/tree/version-15