@buildll/sdk

v1.0.0

Published

5 months ago

React helpers for Buildll content editor - Optional components and hooks for adding inline content editing with persistent deployment

0High
0Medium
0Low

buildll

Buildll Content Editor

Inline content editing with persistent deployment

Transform any website into an editable CMS that automatically deploys changes to your live site. Edit content through the Buildll dashboard and watch changes go live instantly.

How It Works

1. Add Editor Script to Your Website

Include the Buildll editor script in your website's <head>:

<!DOCTYPE html>
<html>
<head>
    <script src="https://buildll.com/buildll-editor.js"></script>
</head>
<body>
    <!-- Your website content -->
</body>
</html>

2. Mark Content as Editable

Add data-buildll-* attributes to elements you want to be editable:

// React/Next.js Example
export default function HomePage() {
  return (
    <div>
      <h1
        data-buildll-id="hero-title"
        data-buildll-text="Welcome to Your Website"
        data-buildll-type="text"
      >
        Welcome to Your Website
      </h1>
      <p
        data-buildll-id="hero-description"
        data-buildll-text="This content is editable in Buildll Dashboard"
        data-buildll-type="text"
      >
        This content is editable in Buildll Dashboard
      </p>
    </div>
  );
}

<!-- Static HTML Example -->
<div>
  <h1
    data-buildll-id="hero-title"
    data-buildll-text="Welcome to Your Website"
    data-buildll-type="text"
  >
    Welcome to Your Website
  </h1>
  <p
    data-buildll-id="hero-description"
    data-buildll-text="This content is editable"
    data-buildll-type="text"
  >
    This content is editable
  </p>
</div>

3. Configure Deployment (Optional)

To enable automatic deployment when content is edited:

GitHub Repository: Provide your GitHub repository URL
GitHub Token: Personal access token with repo permissions
Deploy Hook: Webhook URL from Vercel/Netlify for automatic builds

Required Attributes

Each editable element needs these attributes:

data-buildll-id: Unique identifier for the content element
data-buildll-text: Current text content (used for matching in repository)
data-buildll-type: Content type (currently only "text" supported)

Content Editing Process

Client opens Buildll dashboard
Site loads in editor iframe with visual editing overlay
Click any marked element to open edit modal
Edit content and save changes
Automatic deployment:
- Content saved to database
- GitHub repository updated with new content
- Deploy webhook triggered (if configured)
- Live site updates with changes

Deployment Flow

When content is edited and saved:

Content saved to database
    ↓
Buildll searches GitHub repository for matching text
    ↓
Updates found files with new content
    ↓
Creates git commit: "Update content via Buildll editor"
    ↓
Triggers deploy webhook (if configured)
    ↓
Hosting provider rebuilds and deploys
    ↓
Live website updates with new content

Integration Examples

React Component Helper

// components/EditableText.jsx
export function EditableText({ id, children, tag: Tag = 'p', ...props }) {
  return (
    <Tag
      data-buildll-id={id}
      data-buildll-text={children}
      data-buildll-type="text"
      {...props}
    >
      {children}
    </Tag>
  );
}

// Usage
<EditableText id="hero-title" tag="h1" className="text-4xl">
  Welcome to Our Company
</EditableText>

Next.js Hook

// hooks/useBuildllEditable.js
import { useEffect, useRef } from 'react';

export function useBuildllEditable(id, text, type = 'text') {
  const ref = useRef();

  useEffect(() => {
    if (ref.current) {
      ref.current.setAttribute('data-buildll-id', id);
      ref.current.setAttribute('data-buildll-text', text);
      ref.current.setAttribute('data-buildll-type', type);
    }
  }, [id, text, type]);

  return ref;
}

// Usage
function MyComponent() {
  const ref = useBuildllEditable('hero-title', 'Welcome');
  return <h1 ref={ref}>Welcome</h1>;
}

Deployment Configuration

GitHub Setup

Create a GitHub Personal Access Token:
- Go to GitHub Settings > Developer settings > Personal access tokens
- Generate new token with repo scope
- Copy token for Buildll configuration

Hosting Provider Webhooks

For Vercel:

Project Settings > Git > Deploy Hooks
Create new deploy hook
Copy webhook URL

For Netlify:

Site Settings > Build & Deploy > Build Hooks
Add build hook
Copy webhook URL

Troubleshooting

Editor Shows Cross-Origin Warning

Problem: Editor shows "Note: This site is hosted on a different domain..."

Solution: Add the Buildll editor script to your website as shown above.

Content Changes Don't Deploy

Solutions:

Verify GitHub repository URL and token are correct
Ensure data-buildll-text matches repository content exactly
Check deploy webhook URL is configured correctly
Verify GitHub token has repo permissions

Elements Not Clickable