# Homepage Widget Management System - Implementation Plan

## Overview
A complete widget-based homepage management system that replaces the static hardcoded welcome page with a flexible, drag-and-drop configurable interface. Admins can add, remove, reorder, and customize widgets without touching code.

## Architecture

### 1. Database Structure

#### `homepage_widgets` Table
```sql
id (PK)
widget_type (enum: hero, stats, features, blog_posts, forum_topics, cta, adsense, custom_html)
title (nullable)
content (JSON - stores widget-specific configuration)
is_active (boolean)
sort_order (integer)
width (enum: full, half)
position (string - for future layout flexibility)
created_at
updated_at
```

#### Widget Content JSON Examples:
- **hero**: { title, subtitle, badge_text, show_cta, guest_only }
- **stats**: { show_topics, show_posts, show_users }
- **features**: { show_modules, items_limit }
- **blog_posts**: { category_filter, items_limit }
- **forum_topics**: { category_filter, items_limit }
- **cta**: { title, description, button_text, button_url }
- **adsense**: { location, show_placeholder }
- **custom_html**: { html_content, sanitized }

### 2. Model Structure

#### HomepageWidget Model
- Attributes: widget_type, title, content (casted to array), is_active, sort_order, width, position
- Scopes: active(), ordered(), byType()
- Methods: getWidgetView(), renderWidget(), getDefaultConfig()
- Caching: Cache homepage_widgets for 1 hour

### 3. Admin Panel Routes & Views

#### Routes (`/admin/homepage`)
- `GET /admin/homepage` - List all widgets (with drag-and-drop)
- `GET /admin/homepage/create` - Show widget creation form
- `POST /admin/homepage` - Store new widget
- `GET /admin/homepage/{id}/edit` - Edit widget
- `PUT /admin/homepage/{id}` - Update widget
- `DELETE /admin/homepage/{id}` - Delete widget
- `POST /admin/homepage/{id}/toggle` - Toggle active/inactive
- `POST /admin/homepage/reorder` - AJAX reorder (drag-and-drop)

#### Views
1. **index.blade.php** - Widget list with drag-and-drop, quick toggles
2. **create.blade.php** - Multi-step form for widget creation
3. **edit.blade.php** - Widget configuration form
4. **partials/_widget-form.blade.php** - Reusable form components
5. **partials/_widget-type-config.blade.php** - Dynamic config based on type

### 4. Module Management Cleanup

#### Changes to Module Model & System
- Keep: `is_active`, `is_maintenance`, basic info
- Remove: `display_on_home` field (migration to remove column)
- Update ModuleController: Remove toggleDisplayOnHome() method
- Update module management view: Remove "Ana Sayfa" toggle

#### Migration
```php
Schema::table('modules', function (Blueprint $table) {
    $table->dropColumn('display_on_home');
});
```

### 5. Widget Rendering System

#### Widget Components Directory
```
resources/views/widgets/
├── hero.blade.php
├── stats.blade.php
├── features.blade.php
├── blog_posts.blade.php
├── forum_topics.blade.php
├── cta.blade.php
├── adsense.blade.php
└── custom_html.blade.php
```

#### Welcome Page Integration
- Load widgets via `HomepageWidget::active()->ordered()->get()`
- Cache homepage widgets
- Render using `@include("widgets.{$widget->widget_type}")`

### 6. Features

#### Admin Interface
- **Widget Listing**: Table with all widgets, quick toggles
- **Drag-and-Drop**: Reorder widgets without page reload (AJAX)
- **Quick Actions**: Toggle active/inactive, edit, delete
- **Widget Creation**: Guided form with type-specific fields
- **Preview**: Show widget in modal before saving

#### Widget Types
1. **Hero** - Main banner with title, subtitle, CTA buttons
2. **Stats** - Display forum topics, blog posts, user count
3. **Features** - Show active modules as cards
4. **Blog Posts** - Display recent/filtered blog posts
5. **Forum Topics** - Display recent/filtered forum topics
6. **CTA** - Call-to-action section with button
7. **AdSense** - Ad placement zones
8. **Custom HTML** - Admin-defined HTML (sanitized)

#### Configuration Per Widget
- Active/Inactive toggle
- Sort order (drag-drop)
- Width: Full or Half (for future multi-column layouts)
- Widget-specific settings (categories, limits, etc.)

### 7. Admin Sidebar Menu Updates

```
System Management
├── 📦 Modules (updated)
├── 🏠 Homepage Widgets (NEW)
└── ⚙️ Settings (existing)
```

### 8. Caching Strategy

- Cache key: `homepage_widgets_active`
- TTL: 3600 seconds (1 hour)
- Clear on: widget create, update, delete, toggle
- Clear all cache when needed via Settings page

### 9. Implementation Order

1. Create migration for `homepage_widgets` table
2. Create `HomepageWidget` model with relationships and scopes
3. Create `HomepageWidgetController` with all CRUD methods
4. Create admin views (index, create, edit)
5. Add drag-and-drop JS functionality
6. Create widget blade components
7. Update Module migration (remove display_on_home)
8. Update Module model and ModuleController
9. Update admin/modules/index.blade.php view
10. Add new routes to web.php
11. Update admin layout sidebar
12. Update welcome.blade.php to use widgets
13. Create seeder with default widgets
14. Run migrations and seed
15. Clear all caches

## Benefits

✅ **No Code Changes Needed** - Admin can manage homepage without touching code
✅ **Flexible Layout** - Add/remove/reorder widgets easily
✅ **Scalable** - Easy to add new widget types
✅ **Performance** - Cached widget queries
✅ **User-Friendly** - Intuitive admin interface with drag-and-drop
✅ **Module Separation** - Clean separation between modules and homepage layout
✅ **Future-Proof** - Extensible for multi-column layouts, responsive widgets

## Data Migration Strategy

Since `display_on_home` is being removed from modules:
- Existing modules with `display_on_home = true` should be migrated to featured in widgets
- A migration helper can identify these and suggest creation of "Features" widget
- Or auto-create features widget from active modules on first run

## Timeline Considerations

- Database migration is non-breaking (adding new table)
- Removing `display_on_home` from modules is a breaking change
- Both changes should be deployed together
- Old welcome.blade.php code can be kept as fallback with try-catch
