feat: Add complete Docker deployment with web-based setup wizard

Major additions: - Web-based setup wizard (setup.php, setup_wizard.php, setup-wizard.js) - Production Docker configuration (docker-compose.prod.yml, .env.production) - Database initialization SQL files (deploy/init_settings.sql) - Template builder system with drag-and-drop UI - Advanced features (OAuth, CDN, enhanced analytics, monetization) - Comprehensive documentation (deployment guides, quick start, feature docs) - Design system with accessibility and responsive layout - Deployment automation scripts (deploy.ps1, generate-secrets.ps1) Setup wizard allows customization of: - Platform name and branding - Domain configuration - Membership tiers and pricing - Admin credentials - Feature toggles Database includes 270+ tables for complete video streaming platform with advanced features for analytics, moderation, template building, and monetization. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-10-26 01:42:31 -07:00
parent 0b7e2d0a5b
commit d22b3e1c0d
90 changed files with 22329 additions and 268 deletions
--- a/TEMPLATE_BUILDER_GUIDE.md
+++ b/TEMPLATE_BUILDER_GUIDE.md
@@ -0,0 +1,569 @@
+# EasyStream Template Builder Guide
+
+## Overview
+
+The Template Builder is a powerful drag-and-drop interface that allows users to create custom page layouts for their EasyStream installation. Users can visually design templates using pre-built components without writing any code.
+
+## Features
+
+✨ **Drag and Drop Interface** - Intuitive visual builder
+🎨 **Pre-built Components** - Video grids, heroes, text blocks, and more
+📱 **Responsive Preview** - Test on desktop, tablet, and mobile
+💾 **Auto-save** - Never lose your work
+📝 **Version History** - Track changes over time
+🎯 **Custom Settings** - Configure each component's appearance
+🔄 **Template Management** - Create, edit, duplicate, and delete templates
+👁️ **Live Preview** - See your changes in real-time
+
+## Installation
+
+### 1. Database Setup
+
+Run the SQL migration to create required tables:
+
+```bash
+mysql -u your_user -p your_database < __install/add_template_builder.sql
+```
+
+This creates the following tables:
+- `db_templatebuilder_templates` - Stores user templates
+- `db_templatebuilder_components` - Component library
+- `db_templatebuilder_assignments` - Page assignments
+- `db_templatebuilder_versions` - Version history
+- `db_templatebuilder_user_prefs` - User preferences
+
+### 2. File Structure
+
+The template builder consists of:
+
+```
+f_core/f_classes/
+└── class.templatebuilder.php          # Backend logic
+
+f_templates/tpl_frontend/tpl_builder/
+└── tpl_builder_main.tpl               # Builder UI
+
+f_templates/tpl_backend/
+└── tpl_template_manager.tpl           # Template list view
+
+f_scripts/fe/css/builder/
+└── builder.css                        # Builder styles
+
+f_scripts/fe/js/builder/
+├── builder-core.js                    # Main application
+├── builder-components.js              # Component logic (future)
+└── builder-ui.js                      # UI helpers (future)
+
+f_modules/m_frontend/
+└── templatebuilder_ajax.php           # AJAX handler
+
+f_modules/m_backend/
+└── template_manager.php               # Management interface
+```
+
+### 3. Include in Navigation
+
+Add a link to the template manager in your user account navigation:
+
+```smarty
+<a href="/f_modules/m_backend/template_manager.php">
+    <i class="icon-layout"></i> My Templates
+</a>
+```
+
+## User Guide
+
+### Creating a New Template
+
+1. Navigate to **My Templates** in your account
+2. Click **Create New Template**
+3. You'll be taken to the builder interface
+
+### Builder Interface
+
+The builder consists of three main areas:
+
+#### Left Sidebar - Component Library
+- **Search**: Find components quickly
+- **Categories**: Filter by component type
+- **Component List**: Drag components to canvas
+
+#### Center Canvas - Preview Area
+- **Toolbar**: Zoom, grid, and view options
+- **Device Preview**: Switch between desktop/tablet/mobile
+- **Canvas**: Drag and drop components here
+
+#### Right Sidebar - Properties Panel
+- **Page Settings**: Template-wide settings
+- **Component Settings**: Configure selected components
+- **Section Settings**: Adjust section layout
+
+### Adding Components
+
+1. Find a component in the left sidebar
+2. Drag it onto the canvas
+3. Drop it where you want it
+4. Configure its settings in the right sidebar
+
+### Component Types
+
+#### Video Grid (4 Columns)
+Displays videos in a responsive grid layout.
+
+**Settings:**
+- Columns (1-6)
+- Gap between items
+- Padding
+
+#### Hero Banner
+Large banner with background image and call-to-action.
+
+**Settings:**
+- Background image
+- Title and subtitle
+- Button text and link
+- Overlay opacity
+- Height
+
+#### Video Horizontal List
+Scrollable horizontal list of videos.
+
+**Settings:**
+- Section title
+- Gap between items
+- Padding
+
+#### Sidebar Widget
+Customizable sidebar container.
+
+**Settings:**
+- Widget title
+- Background color
+- Padding and border radius
+
+#### Text Block
+Rich text content with heading.
+
+**Settings:**
+- Heading text and size
+- Content
+- Text alignment
+- Colors and spacing
+
+#### Image Block
+Image with optional caption.
+
+**Settings:**
+- Image URL
+- Alt text
+- Caption
+- Alignment
+- Max width
+
+#### Custom HTML
+Advanced users can add custom HTML/Smarty code.
+
+**Settings:**
+- HTML content
+- Padding
+
+### Sections
+
+Components are organized into **sections**. Each section can have:
+
+- **Multiple columns** (1-4)
+- **Custom gap** between columns
+- **Background color**
+- **Padding** (top, right, bottom, left)
+
+### Editing Components
+
+1. Click on a component in the canvas
+2. The right sidebar shows its settings
+3. Modify any setting
+4. Changes apply immediately
+
+### Moving Components
+
+- **Drag and drop** within sections
+- Use **section controls** to move sections up/down
+- **Duplicate** components or sections
+- **Delete** unwanted elements
+
+### Responsive Design
+
+Click the device icons in the header to preview:
+
+- 🖥️ **Desktop** (full width)
+- 📱 **Tablet** (768px)
+- 📱 **Mobile** (375px)
+
+### Saving Templates
+
+- **Auto-save**: Automatically saves every 3 seconds
+- **Manual save**: Click "Save" button
+- **Versioning**: Each save creates a version history entry
+
+### Publishing Templates
+
+1. Click **Publish** when ready
+2. Sets the template as active
+3. Template becomes available for use
+
+## Developer Guide
+
+### Creating Custom Components
+
+Add components to the database:
+
+```sql
+INSERT INTO `db_templatebuilder_components`
+(`component_name`, `component_slug`, `component_category`, `component_html`,
+ `component_css`, `component_settings_schema`, `is_system`, `description`)
+VALUES
+('My Component', 'my_component', 'custom',
+'<div class="my-component">{{content}}</div>',
+'.my-component { padding: {{padding}}px; }',
+'{"content": {"type": "textarea", "default": "Hello"}, "padding": {"type": "number", "default": 20}}',
+1,
+'Custom component description');
+```
+
+### Component Settings Schema
+
+The `component_settings_schema` is a JSON object defining configurable settings:
+
+```json
+{
+  "setting_name": {
+    "type": "number|text|textarea|color|boolean|select|image|code",
+    "default": "default_value",
+    "min": 0,
+    "max": 100,
+    "step": 5,
+    "options": ["option1", "option2"]
+  }
+}
+```
+
+**Supported Types:**
+- `number` - Numeric input with optional min/max/step
+- `text` - Single line text
+- `textarea` - Multi-line text
+- `color` - Color picker
+- `boolean` - Checkbox
+- `select` - Dropdown with options
+- `image` - Image URL input
+- `code` - Code editor
+
+### Template Variables
+
+Component HTML can use placeholders:
+
+```html
+<div class="hero" style="background: {{background_color}};">
+    <h1>{{title}}</h1>
+    {if {{show_button}}}
+        <a href="{{button_link}}">{{button_text}}</a>
+    {/if}
+</div>
+```
+
+Placeholders are replaced with:
+1. Component settings values
+2. Global data passed to renderer
+
+### Rendering Templates
+
+#### PHP
+
+```php
+$templateBuilder = new VTemplateBuilder();
+
+// Render by ID
+$html = $templateBuilder->renderTemplate(123);
+
+// Render by slug
+$html = $templateBuilder->renderTemplate('my-template-slug');
+
+// Render with data
+$html = $templateBuilder->renderTemplate(123, [
+    'video_items' => $videos,
+    'user_name' => $userName
+]);
+
+echo $html;
+```
+
+#### Smarty Template
+
+```smarty
+{* Include template builder output *}
+<div class="template-container">
+    {$template_html}
+</div>
+```
+
+### AJAX API
+
+All AJAX requests go to `/f_modules/m_frontend/templatebuilder_ajax.php`
+
+**Get Components:**
+```javascript
+GET /templatebuilder_ajax.php?action=get_components
+GET /templatebuilder_ajax.php?action=get_components&category=video_grid
+```
+
+**Create Template:**
+```javascript
+POST /templatebuilder_ajax.php
+{
+    "action": "create_template",
+    "template_name": "My Template",
+    "template_type": "homepage",
+    "template_structure": "{...}"
+}
+```
+
+**Update Template:**
+```javascript
+POST /templatebuilder_ajax.php
+{
+    "action": "update_template",
+    "template_id": 123,
+    "template_structure": "{...}",
+    "change_note": "Updated hero section"
+}
+```
+
+**Get Template:**
+```javascript
+GET /templatebuilder_ajax.php?action=get_template&template_id=123
+```
+
+**Preview Template:**
+```javascript
+GET /templatebuilder_ajax.php?action=preview&template_id=123
+```
+
+### Template Structure Format
+
+Templates are stored as JSON:
+
+```json
+{
+  "sections": [
+    {
+      "id": "section-1",
+      "columns": 1,
+      "gap": 20,
+      "styles": {
+        "background_color": "#f5f5f5",
+        "padding": "40px 20px"
+      },
+      "blocks": [
+        {
+          "id": "block-1",
+          "component": "hero_banner",
+          "settings": {
+            "title": "Welcome",
+            "subtitle": "To my site",
+            "height": 400,
+            "overlay_opacity": 0.5
+          }
+        }
+      ]
+    }
+  ],
+  "layout_type": "flex",
+  "max_width": 1200
+}
+```
+
+### Extending the Builder
+
+#### Add New Component Category
+
+1. Update SQL insert in `add_template_builder.sql`
+2. Add category button in `tpl_builder_main.tpl`
+3. Add icon mapping in `builder-core.js` `getCategoryIcon()`
+
+#### Custom CSS for Components
+
+Add component-specific CSS in the component definition:
+
+```css
+.component-custom {
+    /* Your styles */
+    padding: {{padding}}px;
+    color: {{text_color}};
+}
+```
+
+Variables are replaced during rendering.
+
+#### Custom JavaScript
+
+Advanced components can include JavaScript:
+
+```javascript
+// In component's custom_js field
+document.querySelectorAll('.my-component').forEach(el => {
+    el.addEventListener('click', () => {
+        console.log('Clicked!');
+    });
+});
+```
+
+### Security Considerations
+
+1. **Input Validation**: All user input is sanitized via `VDatabase::sanitizeInput()`
+2. **Ownership Verification**: Users can only edit their own templates
+3. **HTML Sanitization**: Custom HTML should be sanitized before rendering
+4. **XSS Prevention**: Use Smarty's `|escape` modifier for user content
+5. **SQL Injection**: All queries use prepared statements via VDatabase
+
+### Performance Optimization
+
+1. **Caching**: Rendered templates can be cached
+2. **Lazy Loading**: Load components on demand
+3. **Minification**: Minify CSS/JS before production
+4. **Database Indexes**: Indexes already added for performance
+5. **JSON Validation**: Validate structure before saving
+
+## Keyboard Shortcuts
+
+- **Ctrl/Cmd + S** - Save template
+- **Ctrl/Cmd + Z** - Undo
+- **Ctrl/Cmd + Shift + Z** - Redo
+- **Delete** - Delete selected element
+- **Esc** - Deselect element
+
+## Troubleshooting
+
+### Components Not Loading
+
+Check:
+1. Database has component records
+2. AJAX endpoint is accessible
+3. JavaScript console for errors
+
+### Template Not Saving
+
+Check:
+1. User is logged in
+2. Template name is provided
+3. JSON structure is valid
+4. Database connection is active
+
+### Preview Not Working
+
+Check:
+1. Template is saved first
+2. Template ID is correct
+3. Rendering logic has no errors
+
+### Styles Not Applying
+
+Check:
+1. CSS files are loaded
+2. Builder CSS path is correct
+3. Theme compatibility
+
+## Best Practices
+
+### For Users
+
+1. **Name templates clearly** - Use descriptive names
+2. **Save regularly** - Use auto-save but manually save major changes
+3. **Test responsiveness** - Check all device sizes
+4. **Use sections wisely** - Group related content
+5. **Keep it simple** - Don't overcomplicate layouts
+
+### For Developers
+
+1. **Component reusability** - Create flexible components
+2. **Settings validation** - Validate all settings in schema
+3. **Documentation** - Document custom components
+4. **Testing** - Test templates on different browsers
+5. **Version control** - Use version history for major changes
+
+## API Reference
+
+### VTemplateBuilder Class
+
+#### Methods
+
+**`createTemplate($data)`**
+- Creates new template
+- Returns: `['success' => bool, 'template_id' => int, 'slug' => string]`
+
+**`updateTemplate($template_id, $data, $change_note = null)`**
+- Updates existing template
+- Returns: `['success' => bool]`
+
+**`deleteTemplate($template_id)`**
+- Deletes template
+- Returns: `['success' => bool]`
+
+**`getTemplate($template_id, $check_ownership = true)`**
+- Gets template by ID
+- Returns: `array|null`
+
+**`getTemplateBySlug($slug)`**
+- Gets template by slug
+- Returns: `array|null`
+
+**`getUserTemplates($filters = [])`**
+- Gets all user templates
+- Returns: `array`
+
+**`renderTemplate($template_identifier, $data = [])`**
+- Renders template HTML
+- Returns: `string`
+
+**`getComponents($category = null)`**
+- Gets available components
+- Returns: `array`
+
+**`duplicateTemplate($template_id, $new_name = null)`**
+- Duplicates template
+- Returns: `['success' => bool, 'template_id' => int]`
+
+## Support
+
+For issues or questions:
+
+1. Check this documentation
+2. Review code comments
+3. Check database logs via `VLogger`
+4. Inspect browser console
+5. Review version history for changes
+
+## Future Enhancements
+
+Potential improvements:
+
+- [ ] Template marketplace/sharing
+- [ ] More component types
+- [ ] Advanced grid system
+- [ ] Animation options
+- [ ] A/B testing support
+- [ ] Template import/export
+- [ ] Collaboration features
+- [ ] Mobile app builder
+- [ ] Component library expansion
+- [ ] AI-powered suggestions
+
+## Credits
+
+Built for EasyStream by the EasyStream team.
+
+## License
+
+Same license as EasyStream platform.
+
+---
+
+**Last Updated:** 2025-01-22
+**Version:** 1.0.0