easystream-main/TEMPLATE_BUILDER_GUIDE.md

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:

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:

<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:

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:

{
  "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:

<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

$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

{* 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:

GET /templatebuilder_ajax.php?action=get_components
GET /templatebuilder_ajax.php?action=get_components&category=video_grid

Create Template:

POST /templatebuilder_ajax.php
{
    "action": "create_template",
    "template_name": "My Template",
    "template_type": "homepage",
    "template_structure": "{...}"
}

Update Template:

POST /templatebuilder_ajax.php
{
    "action": "update_template",
    "template_id": 123,
    "template_structure": "{...}",
    "change_note": "Updated hero section"
}

Get Template:

GET /templatebuilder_ajax.php?action=get_template&template_id=123

Preview Template:

GET /templatebuilder_ajax.php?action=preview&template_id=123

Template Structure Format

Templates are stored as 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:

.component-custom {
    /* Your styles */
    padding: {{padding}}px;
    color: {{text_color}};
}

Variables are replaced during rendering.

Custom JavaScript

Advanced components can include 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