MyClub/DOCS/NAVIGATION_SYSTEM.md

# Navigation Management System

## Overview
Comprehensive navigation management system with admin controls, dropdown menus, social media integration, and full customization capabilities.

## Features

### 1. **Dynamic Navigation Management**
- Create, edit, delete, and reorder navigation items
- Support for multiple navigation types:
  - **Page**: Links to predefined system pages (Home, About, Calendar, etc.)
  - **Internal**: Custom internal URLs
  - **External**: Links to external websites
  - **Dropdown**: Parent items with child menu items (nested navigation)
- Visibility controls (show/hide items)
- Custom ordering with up/down buttons
- Target controls (_self or _blank for external links)

### 2. **Social Media Integration**
- Dedicated social media links management
- Supported platforms:
  - Facebook
  - Instagram
  - YouTube
  - Twitter
  - TikTok
  - LinkedIn
  - Discord
  - Twitch
- Automatic icon rendering
- Display in top bar of navigation
- Reorderable and toggleable visibility

### 3. **Admin Interface**
- Located at `/admin/navigace`
- Tab-based interface:
  - Navigation Items tab
  - Social Links tab
- Features:
  - Add new items with modal form
  - Edit existing items
  - Delete items with confirmation
  - Reorder with visual up/down buttons
  - Real-time preview of visibility status

## Database Schema

### `navigation_items` Table
```sql
- id (SERIAL PRIMARY KEY)
- label (VARCHAR) - Display name
- url (TEXT) - Custom URL (optional)
- icon (VARCHAR) - Icon name (optional)
- type (VARCHAR) - internal/external/dropdown/page
- page_type (VARCHAR) - Reference to system page
- page_id (INTEGER) - Optional content ID reference
- visible (BOOLEAN) - Show/hide control
- display_order (INTEGER) - Sort order
- parent_id (INTEGER) - For dropdown children
- target (VARCHAR) - _self/_blank
- css_class (VARCHAR) - Custom styling
- requires_auth (BOOLEAN) - Authentication required
- requires_admin (BOOLEAN) - Admin access required
```

### `social_links` Table
```sql
- id (SERIAL PRIMARY KEY)
- platform (VARCHAR) - facebook/instagram/youtube/etc.
- url (TEXT) - Social media profile URL
- display_order (INTEGER) - Sort order
- visible (BOOLEAN) - Show/hide control
- icon (VARCHAR) - Custom icon override
```

## API Endpoints

### Public Endpoints
- `GET /api/v1/navigation` - Get all visible navigation items
- `GET /api/v1/social-links` - Get all visible social links

### Admin Endpoints (require authentication + admin role)

#### Navigation Management
- `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

#### Social Links Management
- `GET /api/v1/admin/social-links` - Get all social links (including hidden)
- `POST /api/v1/admin/social-links` - Create new social link
- `PUT /api/v1/admin/social-links/:id` - Update social link
- `DELETE /api/v1/admin/social-links/:id` - Delete social link
- `POST /api/v1/admin/social-links/reorder` - Reorder multiple links

## File Structure

### Backend
```
database/migrations/
  - 20251010154600_create_navigation_system.up.sql
  - 20251010154600_create_navigation_system.down.sql

internal/models/
  - navigation.go (NavigationItem, SocialLink models)

internal/controllers/
  - navigation_controller.go (All CRUD operations)

internal/routes/
  - routes.go (Added navigation routes)
```

### Frontend
```
frontend/src/
  services/
    - navigation.ts (API client functions)
  
  pages/admin/
    - NavigationAdminPage.tsx (Admin UI)
  
  components/
    - Navbar.tsx (Updated to support dynamic navigation)
```

## Usage

### Running Migrations
```bash
# Apply migration
make migrate-up

# Or manually with goose
goose -dir database/migrations postgres "your-connection-string" up
```

### Accessing Admin Panel
1. Navigate to `/admin/navigace`
2. Use the tabbed interface to manage:
   - **Navigation Items**: Main menu structure
   - **Social Links**: Social media icons

### Adding Navigation Items

#### Page Type (System Pages)
1. Click "Přidat položku"
2. Enter label (e.g., "Home", "About")
3. Select Type: "Stránka (vyberte existující)"
4. Choose from predefined pages
5. Set visibility and save

#### External Link
1. Click "Přidat položku"
2. Enter label
3. Select Type: "Externí odkaz"
4. Enter full URL (e.g., `https://example.com`)
5. Choose target (_self or _blank)
6. Save

#### Dropdown Menu
1. Create parent item with Type: "Dropdown"
2. Create child items with parent_id reference
3. Children will appear as dropdown on hover

### Adding Social Links
1. Switch to "Sociální sítě" tab
2. Click "Přidat sociální síť"
3. Select platform from dropdown
4. Enter profile URL
5. Set visibility and save

## Frontend Integration

### Using Navigation API
```typescript
import { getNavigationItems, getSocialLinks } from '../services/navigation';

// Fetch navigation
const navItems = await getNavigationItems();

// Fetch social links
const socialLinks = await getSocialLinks();
```

### Navbar Component
The existing `Navbar.tsx` component already supports:
- Dropdown menus (hover to expand)
- External link indicators
- Social media icons in top bar
- Responsive mobile menu
- Active route highlighting

## Predefined Page Types
- `home` → `/`
- `about` → `/o-klubu`
- `calendar` → `/kalendar`
- `matches` → `/zapasy`
- `activities` → `/aktivity`
- `players` → `/hraci`
- `tables` → `/tabulky`
- `blog` → `/blog`
- `videos` → `/videa`
- `gallery` → `/galerie`
- `sponsors` → `/sponzori`
- `contact` → `/kontakt`
- `search` → `/hledat`

## Default Navigation Items
The migration automatically creates default navigation items on first run:
- Domů (Home)
- O klubu (About)
- Kalendář (Calendar)
- Zápasy (Matches)
- Aktivity (Activities)
- Hráči (Players)
- Tabulky (Tables)
- Články (Blog)
- Videa (Videos)
- Fotogalerie (Gallery)
- Sponzoři (Sponsors)
- Kontakt (Contact)

## Best Practices

### Ordering
- Use display_order for consistent sorting
- Lower numbers appear first
- Use up/down buttons in admin for easy reordering

### Dropdown Menus
- Keep dropdown depth to 1 level (parent → children only)
- Limit children to 5-8 items for best UX
- Use clear, descriptive labels

### Social Links
- Order by priority/most used first
- Keep visible count to 3-5 for clean UI
- Use official platform URLs

### External Links
- Always use https:// for security
- Set target="_blank" for external sites
- Consider adding icon or indicator

## Styling & Customization

### CSS Classes
Add custom `css_class` to navigation items for special styling:
```css
.nav-highlighted {
  background: var(--club-primary);
  color: white;
}
```

### Icons
Supported React Icons (FaIconName format):
- Navigation: FaHome, FaCalendar, FaUsers, etc.
- Social: FaFacebook, FaInstagram, FaYoutube, etc.

## Troubleshooting

### Navigation Not Updating
1. Check browser console for API errors
2. Verify admin authentication
3. Clear browser cache
4. Check network tab for failed requests

### Social Icons Not Showing
1. Verify platform name matches supported list
2. Check URL format (must start with https://)
3. Ensure visibility is set to true
4. Check icon import in Navbar component

### Dropdown Not Working
1. Ensure parent item type is "dropdown"
2. Verify children have correct parent_id
3. Check both parent and children are visible
4. Test hover delay timing

## Future Enhancements
- [ ] Drag-and-drop reordering (requires react-beautiful-dnd package)
- [ ] Multi-level nested dropdowns
- [ ] Icon picker UI
- [ ] Bulk operations (delete, hide/show)
- [ ] Navigation templates/presets
- [ ] A/B testing for navigation layouts
- [ ] Analytics integration (track clicks)
- [ ] Role-based navigation (different menus for different user types)
- [ ] Mega menus with rich content
- [ ] Breadcrumb generation from navigation structure

## Support
For issues or questions, refer to the main project documentation or contact the development team.