MyClub/DOCS/ENHANCED_NAVIGATION_SYSTEM.md

Enhanced Navigation Management System

Overview

The navigation system has been completely rebuilt with advanced features for managing complex, hierarchical navigation structures. It now supports unlimited levels of dropdown menus, custom pages, and dynamic navigation from database.

Key Features

🎨 Admin Interface

• Card-based layout with visual hierarchy
• Expandable/collapsible navigation items
• Drag-and-drop reordering (up/down buttons)
• Visual indicators for item type, visibility, and children count
• Nested item management - add sub-items to dropdown menus
• Real-time preview of navigation structure

🔧 Navigation Types

1. Page - Links to existing pages (Blog, Calendar, etc.)
2. Internal - Custom internal URLs (/custom-page)
3. External - Links to external websites
4. Dropdown - Container for sub-navigation items

🌳 Hierarchical Structure

• Parent-child relationships - Unlimited nesting
• Dropdown menus - Hover to reveal sub-items
• Visual indentation in admin panel
• Automatic URL resolution for page types

📱 Frontend Integration

• Dynamic loading from API
• Automatic fallback to hardcoded navigation if API fails
• Mobile-responsive - Different layouts for mobile/desktop
• Hover menus on desktop, expandable lists on mobile

Usage Guide

Accessing the Admin Panel

Navigate to /admin → Navigace to manage navigation items.

Creating Navigation Items

1. Add a Standard Page Link

Label: Články
Type: Page
Page: blog (/blog)
Visible: Yes

2. Add a Custom Internal Link

Label: Naše Historie
Type: Internal
URL: /nase-historie
Visible: Yes

3. Add an External Link

Label: Facebook Page
Type: External
URL: https://facebook.com/yourpage
Target: New Window (_blank)
Visible: Yes

4. Create a Dropdown Menu

Label: Týmy
Type: Dropdown
Visible: Yes

Then click "Přidat podpoložku" to add child items:

Parent: Týmy
Label: A-tým
Type: Page
Page: players (/hraci)

Reordering Items

Use the up/down arrow buttons on each card to change the order. Changes are saved immediately.

Managing Visibility

Toggle the Viditelné (Visible) switch to hide items without deleting them. Hidden items appear grayed out in the admin panel.

Navigation Item Properties

Property	Description	Required
Label	Display name in navigation	Yes
Type	Page, Internal, External, or Dropdown	Yes
Page Type	Pre-defined page to link to (for Page type)	Conditional
URL	Custom URL (for Internal/External types)	Conditional
Target	Open in same or new window (for External)	No
Visible	Show/hide in navigation	Yes
Parent ID	Parent item for nested navigation	No
Description	Admin notes (stored in css_class field)	No

Technical Architecture

Database Schema

navigation_items (
    id SERIAL PRIMARY KEY,
    label VARCHAR(255) NOT NULL,
    url TEXT,
    type VARCHAR(50) NOT NULL, -- 'internal', 'external', 'dropdown', 'page'
    page_type VARCHAR(100), -- 'home', 'blog', 'calendar', etc.
    visible BOOLEAN DEFAULT true,
    display_order INTEGER DEFAULT 0,
    parent_id INTEGER REFERENCES navigation_items(id),
    target VARCHAR(20) DEFAULT '_self',
    css_class VARCHAR(255), -- Used for admin description
    ...
)

API Endpoints

Public Endpoints

• GET /api/v1/navigation - Get visible navigation items with children
• GET /api/v1/social-links - Get visible social media links

Admin Endpoints

• GET /api/v1/admin/navigation - Get all navigation items (including hidden)
• POST /api/v1/admin/navigation - Create new navigation item
• PUT /api/v1/admin/navigation/:id - Update navigation item
• DELETE /api/v1/admin/navigation/:id - Delete navigation item
• POST /api/v1/admin/navigation/reorder - Reorder multiple items

Frontend Components

NavigationAdminPage

• Location: frontend/src/pages/admin/NavigationAdminPage.tsx
• Features: Card-based management interface with expand/collapse
• Dependencies: Chakra UI, React Icons

Navbar

• Location: frontend/src/components/Navbar.tsx
• Features: Dynamic navigation loading, hover dropdowns, mobile responsive
• Fallback: Hardcoded navigation if API fails

NavItemCard

• Component for displaying individual navigation items in admin
• Supports nested rendering with indentation
• Shows badges for type, visibility, and child count

Page Type URLs

Default mapping of page types to URLs:

Page Type	URL	Description
home	/	Homepage
about	/o-klubu	About page
calendar	/kalendar	Event calendar
matches	/zapasy	Match schedule
activities	/aktivity	Club activities
players	/hraci	Player roster
tables	/tabulky	League tables
blog	/blog	Articles/News
videos	/videa	Video gallery
gallery	/galerie	Photo gallery
sponsors	/sponzori	Sponsors page
contact	/kontakt	Contact page
search	/hledat	Search page

Migration Guide

From Hardcoded to Dynamic Navigation

The system automatically creates default navigation items on first migration. To customize:

1. Log in as admin and navigate to Navigation management
2. Review default items - they match your current hardcoded nav
3. Reorder, hide, or modify items as needed
4. Add custom items for new pages or external links
5. Create dropdowns for categorized navigation

Backward Compatibility

If navigation API fails or returns empty:

• Navbar falls back to hardcoded navigation
• No visual disruption to users
• Admin panel shows loading state

Settings Integration

Custom navigation from settings.custom_nav is still supported as fallback. To migrate to database navigation:

1. Create equivalent items in Navigation admin
2. Test thoroughly
3. Remove custom_nav from settings

Best Practices

🎯 Navigation Structure

• Keep it simple - Max 7-9 top-level items
• Group related pages - Use dropdowns for categories
• Logical ordering - Most important pages first
• Descriptive labels - Clear, concise names

🔒 Performance

• Navigation is cached on frontend after first load
• Changes require page refresh to take effect
• API response includes all children in single request

♿ Accessibility

• Proper ARIA labels on all buttons
• Keyboard navigation support
• Screen reader friendly text and structure

📱 Mobile Considerations

• Dropdowns expand as nested lists on mobile
• Touch-friendly buttons and spacing
• Collapsed by default to save space

Troubleshooting

Navigation not updating

• Check API connectivity
• Verify admin permissions
• Clear browser cache and refresh

Dropdown not working

• Ensure parent item type is "dropdown"
• Check child items are properly linked (parent_id)
• Verify children are visible

Items out of order

• Use up/down buttons to reorder
• display_order is automatically managed
• Refresh page after reordering

Missing pages

• Check visibility toggle
• Verify user permissions (requires_auth, requires_admin)
• Confirm page_type matches existing route

Future Enhancements

Potential improvements for future versions:

• Drag-and-drop reordering with library like dnd-kit
• Icon picker for custom icons on nav items
• Permissions - Show different nav to logged-in users
• A/B testing - Multiple navigation configurations
• Analytics - Track which nav items are clicked
• Bulk operations - Import/export navigation config
• Preview mode - See navigation changes before publishing

Support

For issues or questions:

• Check this documentation first
• Review code comments in NavigationAdminPage.tsx
• Check browser console for API errors
• Verify database migrations are up to date

---

Version: 1.0
Last Updated: October 2025
Status: Production Ready ✅