Introduction: What Is a Portal Table of Contents in Frappe?
A Portal Table of Contents (TOC) in Frappe Framework v15 is a structured navigation system used to organize and display links to portal pages for logged-in users. It provides a clear, hierarchical menu that improves usability and discoverability across portal sections.
The TOC is rendered automatically by Frappe when configured correctly and is commonly used in customer, supplier, or member portals.
When Should You Use a Portal Table of Contents?
You should use a portal TOC when:
- Your portal has multiple related pages
- Users need clear navigation
- Content is grouped by functional areas
- You want consistent navigation without hardcoding links
How Portal Table of Contents Works in Frappe v15
Answer:
Frappe builds the portal table of contents from Page metadata and route hierarchy. Pages are grouped automatically based on their placement and configuration.
The TOC is rendered using the standard portal layout and respects:
- User permissions
- Login requirements
- Website routes
Defining Portal Pages for TOC Inclusion
Portal pages must:
- Be placed inside the /www directory
- Be accessible routes (HTML or Jinja)
- Follow predictable URL patterns
Example structure:
www/
├── orders/
│ ├── index.html
│ ├── details.html
├── invoices/
│ ├── index.html
This structure enables grouped navigation in the TOC.
How Titles Appear in the Portal TOC
Page titles are derived from:
- The title variable in the context
- The HTML <title> tag
- The file or folder name (fallback)
Example (orders/index.py)
def get_context(context):
context.title = "My Orders"
This title will appear in the portal table of contents.
Controlling Access in the Portal TOC
Only pages that the user has permission to access are shown in the TOC.
To restrict access:
def get_context(context):
context.login_required = True
Frappe v15 automatically:
- Hides restricted pages
- Prevents unauthorized navigation
Portal TOC Rendering Behavior
The portal TOC is rendered:
- On portal layout pages
- Automatically when multiple portal pages exist
- Without manual HTML configuration
It adapts dynamically based on:
- Logged-in user
- Available routes
- Permissions
Best Practices for Portal Table of Contents
- Use logical folder grouping
- Keep route names short and readable
- Assign clear, human-friendly titles
- Avoid deeply nested structures
- Use consistent naming across sections
Common Mistakes to Avoid
- Mixing Desk pages with portal pages
- Hardcoding navigation links
- Forgetting login_required on sensitive pages
- Using inconsistent route naming
Real-World Use Case
Customer Portal Navigation
- Orders
- Invoices
- Shipments
- Support Requests
Each section appears automatically in the TOC, improving user experience and reducing support queries.
Troubleshooting Portal TOC Issues
TOC not visible
- Check if multiple portal pages exist
- Verify website layout is used
Page missing from TOC
- Confirm login_required logic
- Validate page route and title
Incorrect title
- Set context.title explicitly
Technical Scope & Compatibility
Framework: Frappe Framework v15
Modules: Website, Portal
Supported: ERPNext v15 portals
Not applicable: Desk navigation, Workspace
Cross-References
Official Docs – Portal TOC
https://docs.frappe.io/framework/user/en/guides/portal-development/table-of-contents
Portal Pages
https://docs.frappe.io/framework/user/en/guides/portal-development/adding-pages
Frappe v15 Source
https://github.com/frappe/frappe/tree/version-15
Industry Relevance
- ERPNext Customer Portals
- Supplier Dashboards
- Membership Systems
- Self-Service Business Portals
Conclusion
The Portal Table of Contents in Frappe Framework v15 provides a clean, permission-aware navigation system for external users. By structuring portal pages correctly and using standard Frappe conventions, businesses can deliver intuitive, scalable portal experiences without custom navigation logic.
When implemented properly, the portal TOC enhances usability, reduces friction, and ensures consistent access across all portal users.
