Import saved page — drag-drop .json → builder.load() round-trip

Walkthrough

1. 1

   Save the canvas as a `.json` blob — `getData()` is the round-trip source of truth

   builder.getData() returns the canonical JSON tree (the same shape builder.load() reads). Write it to a Blob, create an object URL, click an off-screen <a download> to drop it in the buyer's Downloads folder. No backend round-trip; no provider lock-in; the file lives on the buyer's disk.

   Why .json and not .bundle.zip? Two reasons. (1) Re-hydration only NEEDS the JSON — the rendered HTML + theme assets that .bundle.zip ships are output, not input. The engine reads JSON via load() and rebuilds the canvas from there. (2) Reading .zip client-side requires JSZip (or alternative) — adds 30+ KB to the buyer's page weight for a feature most production buyers solve server-side anyway. Save+import as .json stays drop-in dependency-free.

   Pair this with the C.15 export pipeline: ship the rendered HTML + assets as .zip (production output), ship the JSON as .json (editable source). The JSON is your "save" format; the ZIP is your "publish" format. Both come from the same getData()+ getHtml() read pair.

   JavaScript Copy

   // Save the canvas as a portable .json file. No backend, no JSZip.
   document.getElementById('c16SaveBtn').addEventListener('click', () => {
     const data = builder.getData();              // canonical JSON tree
     const text = JSON.stringify(data, null, 2);  // pretty-print for diffability
     const blob = new Blob([text], { type: 'application/json;charset=utf-8' });
     const url  = URL.createObjectURL(blob);
   
     const a   = document.createElement('a');
     a.href     = url;
     a.download = `page-${Date.now()}.json`;     // suggest a unique filename
     document.body.appendChild(a);
     a.click();
     a.remove();
     setTimeout(() => URL.revokeObjectURL(url), 0);
   });

2. 2

   Wire the dropzone — `FileReader` → `JSON.parse` → `builder.load(...)`

   The dropzone is the whole demo wrapper. dragenter + dragover set dropEffect = 'copy' + flip a CSS class so the buyer sees a clear "release here" affordance; dragleave + drop tear down. The drop handler reads the file via FileReader.readAsText, parses JSON, and feeds it into builder.load(parsed, templates, configData, mediaUrl). The 4 args after the first MUST be the same themeTemplates / themeConfigData / themeMediaUrl the editor was constructed against — the JSON file ONLY contains the page tree, not the theme bundle. Mixing themes mid-load is a separate feature (theme picker — see builder.php + demo/_partials/builder/theme-picker.php).

   Two anchor points in the same dropzone: a hidden <input type="file"> as a click-to-open keyboard fallback (drag-drop is mouse-only — anyone navigating with a keyboard / screen reader needs the input). Both code paths funnel into the same handleFile(file) helper so the buyer maintains ONE round-trip implementation.

   Robust error handling: invalid JSON shows a "Couldn't parse JSON" status. Files that don't look like a builder page (no blocks array, missing theme) show "Not a BuilderJS page". The engine's load() is forgiving but if the JSON is shaped wrong the canvas comes out blank — pre-validate so you can tell the buyer WHY before the canvas blanks.

   JavaScript Copy

   const dropZone = document.getElementById('c16DropZone');
   const fileInput = document.getElementById('c16FileInput');
   const statusPill = document.getElementById('c16StatusPill');
   
   function setStatus(text, tone) {
     statusPill.textContent = text;
     statusPill.dataset.tone = tone || '';
   }
   
   function handleFile(file) {
     if (!file || !file.name.endsWith('.json')) {
       setStatus('Drop a .json file', 'error');
       return;
     }
     const reader = new FileReader();
     reader.onload = () => {
       let parsed;
       try { parsed = JSON.parse(reader.result); }
       catch (e) { setStatus('Could not parse JSON: ' + e.message, 'error'); return; }
   
       // Light validation — fail loud BEFORE load() blanks the canvas.
       if (!parsed || !Array.isArray(parsed.blocks)) {
         setStatus('Not a BuilderJS page (missing blocks[])', 'error');
         return;
       }
   
       setStatus('Importing…', 'busy');
       builder.load(parsed, themeTemplates, themeConfigData, mediaUrl, () => {
         const sizeKb = (file.size / 1024).toFixed(1);
         setStatus(`Imported ${file.name} (${sizeKb} KB)`, 'success');
       });
     };
     reader.onerror = () => setStatus('Could not read file', 'error');
     reader.readAsText(file);
   }
   
   // Drag-drop path — mouse users.
   dropZone.addEventListener('dragover', (e) => {
     e.preventDefault();
     e.dataTransfer.dropEffect = 'copy';
     dropZone.classList.add('is-drop-active');
   });
   dropZone.addEventListener('dragleave', () => dropZone.classList.remove('is-drop-active'));
   dropZone.addEventListener('drop', (e) => {
     e.preventDefault();
     dropZone.classList.remove('is-drop-active');
     if (e.dataTransfer.files.length > 0) handleFile(e.dataTransfer.files[0]);
   });
   
   // File-input path — keyboard / screen-reader users.
   fileInput.addEventListener('change', (e) => {
     if (e.target.files.length > 0) handleFile(e.target.files[0]);
   });

3. 3

   Round-trip end to end — Save, refresh, drop the .json back, watch the canvas re-hydrate

   The full buyer journey: edit page → click Save → reload page (or open in a different tab) → drag-drop the saved .json back onto the wrapper → canvas re-hydrates byte-identically. The trip is symmetric because getData() and load() are sibling pure functions: load(getData()) is a no-op identity for any valid page tree (Builder.js Lesson 5 — verified by 60+ engine specs in e2e/test-data-blob-mass.spec.js).

   Production hardening — what to add when this leaves localhost:

   • File-size cap. A 10MB JSON parses fine but blocks the main thread for ~50ms. Set a cap (1MB is generous) + show a friendly error above it. Catches accidental "I dropped the wrong 1GB log file" mistakes early.
   • Theme compatibility check. The JSON carries a theme + theme_dir field; if it doesn't match the editor's current theme, the canvas may render with mismatched templates. Either (a) reject with "Saved with theme X, editor is theme Y" or (b) auto-switch the theme picker to match the import.
   • Confirm-overwrite gate. If the canvas has unsaved changes, the import wipes them. Wire a history.canUndo() check + a confirm dialog ("Importing replaces the current canvas. Discard changes?") so dropped files don't silently destroy work.
   • Multi-page imports. If your app handles multi-page projects, dropped files might be a single page or a multi-page bundle. Sniff the JSON shape (single object vs array) + branch accordingly. The C.15 bundle pattern is one extension surface; another is a .bjs-project.json wrapper carrying multiple page trees.

   For server-side import (drop the file, POST it to a backend, return the parsed JSON): keep the dropzone but route through fetch('/backend/import.php', { method: 'POST', body: file }) + parse the response. Useful when the buyer's app needs to record the import (audit trail, multi-tenant scoping, format migration). Same dropzone wiring; the handleFile helper just routes through fetch instead of FileReader.

   JavaScript Copy

   // Production hardening — file-size cap + theme check + unsaved-work gate.
   const MAX_IMPORT_BYTES = 1 * 1024 * 1024;  // 1 MB
   
   function handleFileHardened(file) {
     if (file.size > MAX_IMPORT_BYTES) {
       setStatus('File too large (' + (file.size / 1024).toFixed(0) + ' KB > 1024 KB)', 'error');
       return;
     }
     if (builder.history && builder.history.canUndo() && !confirm('Importing replaces the current canvas. Discard changes?')) {
       setStatus('Import cancelled', '');
       return;
     }
   
     const reader = new FileReader();
     reader.onload = () => {
       let parsed;
       try { parsed = JSON.parse(reader.result); }
       catch (e) { setStatus('Could not parse JSON', 'error'); return; }
   
       if (parsed.theme && parsed.theme !== currentThemeDir) {
         setStatus(`Theme mismatch — editor=${currentThemeDir} file=${parsed.theme}`, 'error');
         return;
       }
   
       setStatus('Importing…', 'busy');
       builder.load(parsed, themeTemplates, themeConfigData, mediaUrl, () => {
         setStatus(`Imported ${file.name}`, 'success');
       });
     };
     reader.readAsText(file);
   }
   
   // Server-side import variant — same dropzone, fetch in place of FileReader.
   async function handleFileServer(file) {
     setStatus('Uploading…', 'busy');
     const body = new FormData();
     body.append('file', file);
     const resp = await fetch('/backend/import.php', { method: 'POST', body });
     if (!resp.ok) { setStatus('Server rejected import', 'error'); return; }
     const parsed = await resp.json();
     builder.load(parsed, themeTemplates, themeConfigData, mediaUrl, () => {
       setStatus(`Imported ${file.name}`, 'success');
     });
   }