HH/SOURCE_USER_BASE_LAYOUT_IMPLEMENTATION.md

Source User Base Layout Implementation

Overview

Created a specialized base layout for Source Users (Call Center Agents, etc.) that provides a focused, streamlined interface since these users only create complaints and inquiries.

---

What Was Created ✅

1. New Base Layout: templates/layouts/source_user_base.html

Purpose: Simplified base layout specifically designed for Source Users who only need to:

• View their dashboard
• Create complaints
• Create inquiries
• View their created complaints
• View their created inquiries

Features:

• ✅ Same Al Hammadi theme and styling as main base
• ✅ Simplified sidebar with focused navigation
• ✅ Mobile-responsive with offcanvas support
• ✅ RTL support for Arabic
• ✅ Same topbar with hospital selector
• ✅ User menu in topbar (change password, logout)
• ✅ All the same CSS variables and design system

2. Updated Template: templates/px_sources/source_user_dashboard.html

Changes:

• Changed extends from layouts/base.html to layouts/source_user_base.html

---

Simplified Sidebar Structure

What Source Users See:

┌─────────────────────────┐
│     PX360          │
├─────────────────────────┤
│ 🏠 Dashboard      │
├─────────────────────────┤
│ ⚠️ Create Complaint│
│ ⚠️ Create Inquiry  │
├─────────────────────────┤
│ 📋 My Complaints  │ [badge: count]
│ 📝 My Inquiries   │ [badge: count]
├─────────────────────────┤
│ 🚪 Logout         │
└─────────────────────────┘

What's Removed (Compared to Full Admin):

No longer visible:

• ❌ Command Center
• ❌ Feedback module
• ❌ Appreciation module
• ❌ Observations
• ❌ PX Actions
• ❌ Patient Journeys
• ❌ Surveys
• ❌ Physicians
• ❌ Staff management
• ❌ Organizations
• ❌ Call Center (interactions)
• ❌ Social Media
• ❌ PX Sources management
• ❌ References
• ❌ Standards
• ❌ Analytics
• ❌ QI Projects
• ❌ Settings (Provisional users, Configuration)
• ❌ Profile settings page

Still visible:

• ✅ Dashboard (Source User focused)
• ✅ Create Complaint
• ✅ Create Inquiry
• ✅ My Complaints
• ✅ My Inquiries
• ✅ Change Password (in topbar menu)
• ✅ Logout

---

Fixes Applied 🔧

URL Name Fixes:

• ✅ Removed non-existent accounts:profile URL references
• ✅ Replaced with accounts:password_change for password management
• ✅ Removed duplicate content at end of file
• ✅ Cleaned up mobile offcanvas navigation

Before:

<!-- Profile Settings -->
<li class="nav-item">
    <a class="nav-link" href="{% url 'accounts:profile' %}">
        <i class="bi bi-person-gear"></i>{% trans "Settings" %}
    </a>
</li>

After:

<!-- Logout -->
<li class="nav-item">
    <a class="nav-link" href="{% url 'accounts:logout' %}">
        <i class="bi bi-box-arrow-right"></i>{% trans "Logout" %}
    </a>
</li>

User menu in topbar now provides:

• Change Password
• Logout

---

Navigation Flow

Source User Workflows:

1. Login → Redirected to Source User Dashboard
   ↓
2. Dashboard → View statistics for their source
   ↓
3. Create Complaint → File new patient complaint
   ↓
4. Create Inquiry → File new patient inquiry
   ↓
5. My Complaints → View all complaints they created
   ↓
6. My Inquiries → View all inquiries they created
   ↓
7. Topbar menu → Change password or logout

---

Backend Integration Requirements

Context Variables Needed

The new source user base layout expects these context variables:

Dashboard View (apps/px_sources/ui_views.py - SourceUserDashboardView)

def get_context_data(self, **kwargs):
    context = super().get_context_data(**kwargs)
    source = self.get_source()  # Get current source user's source
    
    # Count complaints created by this source user
    context['my_complaint_count'] = Complaint.objects.filter(
        source=source,
        created_by=self.request.user
    ).count()
    
    # Count inquiries created by this source user
    context['my_inquiry_count'] = Inquiry.objects.filter(
        source=source,
        created_by=self.request.user
    ).count()
    
    return context

URL Names Used

The sidebar uses these URL names for active state detection:

Navigation	URL Name	View/URL
Dashboard	source_user_dashboard	px_sources:source_user_dashboard
Create Complaint	complaint_create	complaints:complaint_create
Create Inquiry	inquiry_create	complaints:inquiry_create
My Complaints	complaint_list	complaints:complaint_list
My Inquiries	inquiry_list	complaints:inquiry_list
Change Password	password_change	accounts:password_change
Logout	logout	accounts:logout

---

Template Hierarchy

Full Admin Users (PX Admins, Hospital Admins, etc.)

layouts/base.html
├── Full sidebar with all modules
├── All navigation options
└── Full functionality

Source Users

layouts/source_user_base.html
├── Simplified sidebar (6 items only)
├── Focused on complaints/inquiries
└── Data isolation (only see their own data)

---

Benefits

For Source Users:

✅ Focused Interface - Only see what they need ✅ Less Confusion - No irrelevant modules ✅ Faster Navigation - Fewer clicks to get to tasks ✅ Clear Purpose - Dashboard focused on their role ✅ Better Training - Easier to teach new agents ✅ Reduced Errors - Can't accidentally access wrong areas ✅ Simplified Settings - Only password change in topbar menu

For System:

✅ Role-Based UI - Different layouts for different roles ✅ Security by Design - Users only see appropriate sections ✅ Maintainable - Separate layouts easier to maintain ✅ Scalable - Easy to add more specialized layouts ✅ Consistent Theme - Same Al Hammadi branding

---

Testing Checklist

UI Testing:

• Verify sidebar shows only 6 navigation items
• Verify Dashboard link is active on source user dashboard
• Verify Create Complaint link works
• Verify Create Inquiry link works
• Verify My Complaints badge shows correct count
• Verify My Inquiries badge shows correct count
• Verify Logout works
• Verify Change Password in topbar menu works
• Verify mobile responsive with offcanvas
• Verify RTL support for Arabic

Data Isolation Testing:

• Verify My Complaints shows ONLY complaints created by this source user
• Verify My Inquiries shows ONLY inquiries created by this source user
• Verify badges show correct counts
• Verify no access to other users' data

URL Testing:

• All sidebar links resolve correctly
• No NoReverseMatch errors
• User menu in topbar works correctly
• Mobile offcanvas navigation works

---

Other Templates to Update

These templates should also use source_user_base.html:

Complaint/Inquiry Creation Forms:

<!-- templates/complaints/complaint_form.html -->
<!-- templates/complaints/inquiry_form.html -->
{% extends "layouts/source_user_base.html" %}

Source User Forms:

<!-- templates/px_sources/source_user_form.html -->
<!-- templates/px_sources/source_user_confirm_delete.html -->
{% extends "layouts/source_user_base.html" %}

---

Future Enhancements

Potential Improvements:

1. Source-Specific Branding

   • Show source name/color in sidebar
   • Customize branding per source type

2. Quick Actions Enhancement

   • Add "Create Complaint" button directly in sidebar
   • Add "Create Inquiry" button directly in sidebar

3. Performance Dashboard

   • Add statistics for source user's performance
   • Show average response time
   • Show complaint resolution rate

4. Training Mode

   • Add tooltips to guide new users
   • Add walkthrough for first-time users

5. Keyboard Shortcuts

   • Add shortcuts for common actions
   • C = Create Complaint
   • I = Create Inquiry

---

Comparison: Full vs Source User Base

Feature	Full Admin Base	Source User Base
Sidebar Items	30+ items	6 items
Navigation Depth	Multi-level	Single-level
Admin Settings	Yes	No
Profile Page	Yes	No (only password change in topbar)
Hospital Selector	Dropdown	Dropdown
User Menu	Topbar	Topbar (password + logout)
Mobile Offcanvas	Yes	Yes
RTL Support	Yes	Yes
Theme	Al Hammadi	Al Hammadi
Responsive	Yes	Yes

---

File Structure

templates/
├── layouts/
│   ├── base.html                    # Full admin base layout
│   ├── source_user_base.html        # NEW: Source user base layout
│   └── partials/
│       ├── sidebar.html             # Full sidebar
│       ├── topbar.html             # Shared topbar
│       ├── breadcrumbs.html        # Shared breadcrumbs
│       └── flash_messages.html    # Shared flash messages
└── px_sources/
    └── source_user_dashboard.html   # UPDATED: Now uses source_user_base.html

---

Security Considerations

Data Isolation:

• ✅ Source users see sidebar with ONLY their relevant navigation
• ✅ Cannot access admin-only areas (settings, analytics, etc.)
• ✅ Cannot see other users' complaints/inquiries
• ✅ Limited to create/view own data only

Role-Based Access:

• ✅ Simplified UI reinforces role boundaries
• ✅ Reduces accidental access to restricted areas
• ✅ Clear separation between admin and operational users

---

Implementation Notes

Why Separate Base Layout?

1. Clear Role Separation - Different layouts for different roles
2. Maintainability - Changes to admin UI don't affect source users
3. Performance - Simpler sidebar = faster rendering
4. User Experience - Focused interface = better productivity
5. Security - UI reinforces backend permissions

Reusability:

Shared Components:

• ✅ layouts/partials/topbar.html - Same topbar used
• ✅ layouts/partials/breadcrumbs.html - Shared breadcrumbs
• ✅ layouts/partials/flash_messages.html - Shared messages
• ✅ CSS variables - Same design system
• ✅ Theme - Same Al Hammadi branding

Unique Components:

• ✅ Sidebar - Different navigation for different roles

---

Troubleshooting

Common Issues:

NoReverseMatch Error:

• ✅ Fixed: Removed accounts:profile URL references
• ✅ Solution: Use accounts:password_change for password management

Missing Context Variables:

• Issue: Badges showing 0 or not updating
• Solution: Ensure my_complaint_count and my_inquiry_count are in context

Styling Issues:

• Issue: Sidebar doesn't match full admin
• Solution: Ensure CSS variables are properly defined

---

Implementation Date: January 12, 2026 Status: ✅ Complete - Base layout created, dashboard updated, URL issues fixed

Completed:

1. ✅ Created specialized base layout for source users
2. ✅ Updated source user dashboard to use new base
3. ✅ Fixed URL name issues (removed profile, kept password_change)
4. ✅ Cleaned up duplicate content
5. ✅ Documentation created

Next Steps:

1. Test source user dashboard in browser
2. Update other source user templates to use new base
3. Add context variables in backend views
4. User acceptance testing with actual source users