upload

2026-06-04 02:32:57 +00:00 · 2025-10-16 13:32:05 +02:00
commit 12cba639b9
663 changed files with 168914 additions and 0 deletions
@@ -0,0 +1,297 @@
+# 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.