cloud-hosting-platform/site-builder
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a71b58c2c7a69b1ff8f27ef9497e3a27df758f91
site-builder/VIDEO_BACKGROUND_GUIDE.md
Josh Knapp a71b58c2c7 Initial commit: Site Builder with PHP API backend 
Visual drag-and-drop website builder using GrapesJS with:
- Multi-page editor with live preview
- File-based asset storage via PHP API (no localStorage base64)
- Template library, Docker support, and Playwright test suite

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 19:25:42 +00:00

10 KiB
Raw Blame History

Video Background - Complete User Guide

✅ Fixed Issues

  1. Multiple input fields - Now there's only ONE place to enter the video URL
  2. Confusing UI - Inner layers are now non-selectable
  3. HTML Editor - NEW! Edit any element's HTML directly

How to Add Video Background (Step-by-Step)

Step 1: Add the Block

  1. Look at the left sidebar → Blocks panel
  2. Scroll to Layout category
  3. Find "Section (Video BG)" block
  4. Click it once → it adds to the canvas

Step 2: Select the Section

  1. Click on the section you just added
  2. You should see a blue outline around the entire section
  3. Don't click on the text inside - click the section background

Step 3: Open Settings Panel

  1. Look at the right sidebar
  2. If you see "Styles" tab, click the "Settings" tab next to it
  3. OR look for a tab that says "Traits" or "Settings"

Step 4: Enter Video URL (THE ONLY PLACE!)

  1. In the Settings panel, you'll see "Video URL" field

  2. This is the ONLY place you need to enter the URL

  3. Paste your YouTube URL, examples:

    • https://www.youtube.com/watch?v=OC7sNfNuTNU
    • https://youtu.be/dQw4w9WgXcQ
    • https://vimeo.com/12345678
    • https://example.com/video.mp4

  4. Press Enter or click outside the field

Step 5: Watch It Load

  1. Wait 1-2 seconds
  2. The placeholder text should disappear
  3. Your video appears in the background!
  4. If it's a YouTube/Vimeo video, click the play button to start it

⚠️ Important: Only ONE Input Field!

Where to enter the URL:

  • ✅ Main section element → Settings panel → "Video URL" field

DO NOT look for:

  • ❌ Inner wrapper elements (these are now hidden)
  • ❌ Multiple Video URL fields (there's only one now)
  • ❌ Advanced traits (not needed)

If you see multiple Video URL fields:

  • You're probably selecting the wrong element
  • Click on the outer section (the blue border should wrap the whole thing)

Video URL Formats Supported

YouTube

https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://www.youtube.com/embed/VIDEO_ID

Vimeo

https://vimeo.com/VIDEO_ID
https://player.vimeo.com/video/VIDEO_ID

Direct Video Files

https://example.com/video.mp4
https://example.com/video.webm
https://example.com/video.ogg

Troubleshooting

"I don't see the Video URL field"

Solution 1: Make sure you selected the section itself

  1. Click directly on the dark section background
  2. NOT on the white text inside
  3. Look for blue outline around the WHOLE section

Solution 2: Switch to Settings tab

  1. Right sidebar should show tabs: Styles | Settings
  2. Click Settings tab
  3. Video URL field should appear there

Solution 3: Check Layers panel

  1. Left sidebar → click "Layers" tab
  2. Find the section element (should say <section>)
  3. Click it there to select it
  4. Now check Settings panel again

"Video doesn't load after entering URL"

Check these:

  1. Did you press Enter after pasting the URL?
  2. Is the URL valid? (test it in a new browser tab)
  3. Wait 2-3 seconds - sometimes takes time to load
  4. Check browser console for errors (F12)

"I see multiple Video URL fields"

This shouldn't happen anymore! But if you do:

  1. Only use the FIRST one you see
  2. Make sure you're on the latest version (refresh the page)
  3. If still seeing duplicates, report it as a bug

"Video shows Error 153"

This error means the video owner doesn't allow autoplay embedding.

What we fixed:

  • Removed autoplay=1 parameter from embed URLs
  • Videos now require manual play button click
  • This is YouTube's policy, not a bug

Workaround:

  • Just click the play button on the video
  • It will play and loop normally after that

NEW FEATURE: HTML Editor

You can now edit the HTML of ANY element directly!

How to Use HTML Editor

  1. Select any element on the canvas
  2. Scroll down in the Settings panel
  3. Find "Edit HTML" section
  4. You'll see a code editor with the element's HTML
  5. Edit the HTML as needed
  6. Click "Apply Changes" button
  7. OR click "Cancel" to revert

Example: Add Custom Attributes

<!-- Before -->
<h1>My Heading</h1>

<!-- After editing -->
<h1 id="main-title" data-custom="value">My Heading</h1>

Use Cases

  • Add custom id or class attributes
  • Modify inner content
  • Add data attributes
  • Change element structure
  • Quick fixes without recreating elements

⚠️ Warning

  • Invalid HTML will show an error
  • Changes replace the entire element
  • Use carefully - can break styling if not careful

Visual Guide: Where to Find Everything

┌─────────────────────────────────────────────────┐
│  Left Sidebar                                   │
├─────────────────────────────────────────────────┤
│  Blocks Tab:                                    │
│    Layout Category                              │
│      → Section (Video BG) ← CLICK THIS          │
├─────────────────────────────────────────────────┤
│  Layers Tab:                                    │
│    → section[data-video-section]                │
│       ├─ bg-video-wrapper (hidden from users)   │
│       ├─ overlay                                │
│       └─ content                                │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│  Canvas (Center)                                │
├─────────────────────────────────────────────────┤
│                                                 │
│    ┌─────────────────────────────────────┐     │
│    │ ▶ Video Background Section         │     │
│    │                                     │     │
│    │  [Dark overlay with placeholder]   │     │
│    │                                     │     │
│    │  Click this section, then add URL  │     │
│    │  in Settings panel →               │     │
│    └─────────────────────────────────────┘     │
│                                                 │
└─────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────┐
│  Right Sidebar                                  │
├─────────────────────────────────────────────────┤
│  [Styles] [Settings] ← CLICK SETTINGS           │
├─────────────────────────────────────────────────┤
│  Video URL                                      │
│  ┌───────────────────────────────────────┐     │
│  │ https://youtube.com/watch?v=...       │     │
│  └───────────────────────────────────────┘     │
│  ↑ ONLY PLACE TO ENTER URL!                    │
├─────────────────────────────────────────────────┤
│  Edit HTML                                      │
│  ┌───────────────────────────────────────┐     │
│  │ <section data-video-section...>       │     │
│  │   ...HTML code...                     │     │
│  │ </section>                            │     │
│  └───────────────────────────────────────┘     │
│  [Apply Changes] [Cancel]                      │
└─────────────────────────────────────────────────┘

Quick Start Checklist

  • Add "Section (Video BG)" block to canvas
  • Click on the section to select it
  • Switch to Settings tab (right sidebar)
  • Find "Video URL" field (should be first/only video input)
  • Paste your YouTube/Vimeo/.mp4 URL
  • Press Enter
  • Wait 2 seconds for video to load
  • Click play button if needed
  • Video is now your background! ✅

Tips & Best Practices

Performance

  • Use .mp4 files for best performance
  • YouTube/Vimeo embed can be slower
  • Videos should be < 20MB for fast loading
  • Consider using poster image as fallback

Design

  • Keep overlay dark enough to read text
  • Test text contrast (white text on dark overlay works best)
  • Don't make overlay too dark (defeats purpose of video)
  • Typical overlay: rgba(0,0,0,0.6) (60% black)

Accessibility

  • Add meaningful content over video (not just decorative)
  • Ensure text is readable with video playing
  • Provide alternative content for users with slow connections
  • Consider adding "Pause Video" button for users

SEO

  • Video backgrounds don't help SEO (search engines ignore them)
  • Focus on your text content for SEO
  • Use descriptive headings and paragraphs over the video
  • Don't rely solely on video to communicate key info

Need more help? Check the other documentation:

  • FIXES_2026-02-22.md - All fixes applied today
  • HEADING_LEVEL_FEATURE.md - How to use H1-H6 selector
  • WINDOWS_EXPORT_FIX.md - Copy HTML export feature
  • MANUAL_TEST_RESULTS.md - Testing checklist

Enjoy your video backgrounds! 🎥✨

Reference in New Issue View Git Blame Copy Permalink