Introduction: What Is Portal Ordering in Frappe?
Portal ordering in Frappe Framework v15 defines how portal pages are arranged, listed, and navigated within the Website module.
This ordering directly impacts user experience, navigation flow, and content discoverability for portal users such as customers, suppliers, or members.
Frappe determines portal page order using file structure, routing rules, and naming conventions, not database-driven menus.
Technical Scope & Prerequisites
Applies To
- Frappe Framework v15
- Website Module
- Portal Pages (/www routes)
Prerequisites
- Bench-based Frappe site
- Website module enabled
- Basic understanding of routes and Jinja templates
How Does Frappe Determine Portal Page Order?
Answer:
Frappe orders portal pages primarily based on URL routing hierarchy and folder structure, not manual sorting.
The system evaluates:
- Route depth
- Folder hierarchy
- File naming
- Explicit navigation definitions (if any)
There is no drag-and-drop ordering for portal pages in v15.
Portal Ordering Based on Folder Structure
How Folder Hierarchy Affects Ordering
Portal pages inside the /www directory follow a top-down structure.
Example:
www/
├── index.html
├── orders/
│ ├── index.html
│ ├── open-orders.html
│ └── completed-orders.html
Resulting routes:
/
/orders
/orders/open-orders
/orders/completed-orders
Key Rule:
Parent routes always appear logically before child routes.
How File Naming Influences Portal Order
Frappe uses alphabetical ordering when rendering multiple pages within the same route context.
Example:
www/reports/
├── 01-summary.html
├── 02-invoices.html
└── 03-payments.html
This ensures predictable and controlled ordering.
Best Practice:
Use numeric or descriptive prefixes when order matters.
How Index Pages Control Portal Navigation
Answer:
index.html acts as the default landing page for a route.
Example:
/www/orders/index.html → /orders
This allows you to:
- Create structured navigation hubs
- Group related portal pages logically
- Guide users step-by-step
Ordering Portal Pages in Custom Navigation Menus
While Frappe does not auto-generate menus, you can explicitly control order using portal menu definitions.
Using portal_menu_items (hooks.py)
portal_menu_items = [
{"title": "Orders", "route": "/orders"},
{"title": "Invoices", "route": "/invoices"},
{"title": "Payments", "route": "/payments"}
]
Order in the list = order in the portal menu
This is the only supported method for manual ordering in v15.
Best Practices for Portal Page Ordering
- Use folder hierarchy for logical grouping
- Prefix files numerically if sequence matters
- Always include an index.html for parent routes
- Keep routes shallow and predictable
- Avoid deeply nested folders unless required
Common Portal Ordering Mistakes
- Expecting drag-and-drop ordering
- Relying on DocType sorting
- Mixing unrelated pages in the same folder
- Using unclear or inconsistent file names
Advanced Topic: Ordering vs Permissions
Important Clarification:
Ordering does not override permissions.
Even if a page appears first:
- Users must still have permission
- Portal roles still apply
- Unauthorized users cannot access restricted pages
Real-World Use Case
Customer Portal Example
/customer
├── index.html → Dashboard
├── orders.html → Orders list
├── invoices.html → Invoices
└── profile.html → Account settings
This structure:
- Improves usability
- Reduces support tickets
- Guides customers naturally
Troubleshooting Portal Ordering Issues
Page appears in wrong order
- Check file name sorting
- Verify folder hierarchy
Route not loading
- Ensure index.html exists
- Match file name with route
Menu order incorrect
- Recheck portal_menu_items sequence
Cross-References
Portal Development Overview
https://docs.frappe.io/framework/user/en/guides/portal-development
Frappe v15 Source
https://github.com/frappe/frappe/tree/version-15
Industry Relevance
- ERPNext Customer Portals
- Supplier Self-Service Portals
- Membership & Subscription Platforms
- Educational Portals
Conclusion
In Frappe Framework v15, portal ordering is intentionally simple, predictable, and file-driven.
By using folder structure, naming conventions, and explicit menu hooks, developers can create clean, intuitive portal navigation without complexity.
