site-builder/WHP_INTEGRATION.md

Site Builder - WHP Integration Guide

Overview

This site builder integrates with WHP (Web Hosting Panel) to provide users with a visual site building interface. Users can create HTML pages using a drag-and-drop editor and save them directly to their web hosting account.

Architecture

Components

1. Frontend (GrapesJS)

   • Location: /home/jknapp/code/site-builder/
   • Visual drag-and-drop editor
   • Real-time preview
   • Device responsive design tools

2. Backend API

   • Location: /home/jknapp/code/whp/web-files/api/site-builder.php
   • Handles save/load/list/delete operations
   • Integrates with WHP authentication system
   • Stores sites in user's home directory

3. WHP Integration Layer

   • File: js/whp-integration.js
   • Connects frontend to backend API
   • Provides save/load UI
   • Auto-save functionality

Installation

1. Deploy Backend API

Copy the site builder API to the WHP web files:

cp /home/jknapp/code/whp/web-files/api/site-builder.php /docker/whp/web/api/

Or run WHP update script to sync:

cd /home/jknapp/code/whp
./update.sh

2. Deploy Frontend

Copy the site builder files to the WHP web directory:

# Create site-builder directory in WHP
mkdir -p /docker/whp/web/site-builder

# Copy all files
cp -r /home/jknapp/code/site-builder/* /docker/whp/web/site-builder/

3. Configure Access

The site builder should be accessible to authenticated WHP users at:

https://your-whp-domain.com/site-builder/

User Directory Structure

When a user saves a site, it creates the following structure:

/home/{username}/public_html/site-builder/
├── sites/
│   ├── site_abc123.json        # GrapesJS project data
│   ├── site_abc123.html        # Compiled HTML output
│   ├── site_xyz789.json
│   └── site_xyz789.html

File Formats

JSON File (.json):

{
  "id": "site_abc123",
  "name": "My Awesome Site",
  "created": 1708531200,
  "modified": 1708617600,
  "html": "<div>...</div>",
  "css": "body { ... }",
  "grapesjs": { ... }
}

HTML File (.html):

• Complete, standalone HTML file
• Includes embedded CSS
• Ready to publish/share
• Accessible via: https://your-domain.com/~username/site-builder/sites/site_abc123.html

API Endpoints

All endpoints require WHP authentication (session-based).

List Sites

GET /api/site-builder.php?action=list

Response:

{
  "success": true,
  "sites": [
    {
      "id": "site_abc123",
      "name": "My Site",
      "created": 1708531200,
      "modified": 1708617600,
      "url": "/~username/site-builder/sites/site_abc123.html"
    }
  ]
}

Load Site

GET /api/site-builder.php?action=load&id=site_abc123

Response:

{
  "success": true,
  "site": {
    "id": "site_abc123",
    "name": "My Site",
    "html": "<div>...</div>",
    "css": "body { ... }",
    "grapesjs": { ... }
  }
}

Save Site

POST /api/site-builder.php?action=save
Content-Type: application/json

{
  "id": "site_abc123",
  "name": "My Site",
  "html": "<div>...</div>",
  "css": "body { ... }",
  "grapesjs": { ... }
}

Response:

{
  "success": true,
  "site": {
    "id": "site_abc123",
    "name": "My Site",
    "url": "/~username/site-builder/sites/site_abc123.html"
  }
}

Delete Site

GET /api/site-builder.php?action=delete&id=site_abc123

Response:

{
  "success": true,
  "message": "Site deleted successfully"
}

Security

Authentication

• Uses WHP's existing authentication system
• AUTH_USER constant provides current username
• HOME_DIR constant provides user's home directory path
• Session-based authentication (handled by auto-prepend.php)

Path Security

• All user paths are validated and sanitized
• basename() used to prevent path traversal
• Files stored only in user's home directory
• No cross-user access possible

File Permissions

• Site directories created with 0755 permissions
• Files inherit user's ownership
• Web server can read/serve files
• Users can only access their own sites

Frontend Integration

Adding WHP Integration to Index.html

Add this script tag before the closing </body>:

<script src="js/whp-integration.js"></script>

The integration will automatically:

1. Add "Save" and "Load" buttons to the toolbar
2. Enable auto-save every 30 seconds
3. Provide site management dialog

Custom API URL

If the API is hosted elsewhere:

// In whp-integration.js or custom config
window.editor.onReady(() => {
    window.whpInt = new WHPIntegration(window.editor, 'https://custom-api.com/api/site-builder.php');
});

Testing

For AI Agents

You can test the API using curl (requires valid session):

# List sites
curl 'http://localhost/api/site-builder.php?action=list' \
  -H 'Cookie: PHPSESSID=your_session_id'

# Save a test site
curl 'http://localhost/api/site-builder.php?action=save' \
  -X POST \
  -H 'Cookie: PHPSESSID=your_session_id' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Test Site",
    "html": "<h1>Hello World</h1>",
    "css": "h1 { color: blue; }"
  }'

Manual Testing

1. Log into WHP
2. Navigate to /site-builder/
3. Create a test page using the visual editor
4. Click "Save" and enter a site name
5. Verify the site appears in the load dialog
6. Check the generated HTML at /~username/site-builder/sites/

Troubleshooting

"Not authenticated" Error

• Ensure you're logged into WHP first
• Check that auto-prepend.php is running
• Verify session cookies are being sent

Save/Load Fails

• Check PHP error logs: /var/log/apache2/error.log
• Verify directory permissions on ~/public_html/site-builder
• Ensure API file is executable by PHP-FPM

Sites Not Appearing

• Check ownership: ls -la ~/public_html/site-builder/sites/
• Verify files were created: .json and .html files should exist
• Check Apache access logs for 404s

Future Enhancements

Potential improvements:

• Publishing workflow (move from site-builder/ to production location)
• Template library
• Asset management (images, fonts)
• Multi-page site support
• Export to ZIP
• Collaboration features
• Version history

Development

Local Development Setup

For development without WHP authentication:

// Add to whp-integration.js (development only)
const DEV_MODE = true;
if (DEV_MODE) {
    // Mock API responses for testing
    class MockAPI {
        async save(data) { console.log('Mock save:', data); }
        async load(id) { return { success: true, site: mockSite }; }
    }
}

File Locations

Development:

• Frontend: /home/jknapp/code/site-builder/
• Backend: /home/jknapp/code/whp/web-files/api/site-builder.php

Production:

• Frontend: /docker/whp/web/site-builder/
• Backend: /docker/whp/web/api/site-builder.php
• User sites: /home/{username}/public_html/site-builder/sites/

License

This integration follows the WHP project licensing.