cm-google-form

Google Forms → Sheet Integration Skill

Connect HTML forms → Google Sheets via Google Apps Script. Auto-retry, toast UI, contact fallback on errors. Zero dependencies, works on any static site.

🎯 When to Use

📋 5-Phase Workflow

Phase 1: DISCOVER → Scan forms, identify fields, determine sheet structure
Phase 2: PLAN → Design sheet columns, map form fields, create deployment plan
Phase 3: BUILD → Generate Apps Script + Frontend JS + Toast CSS
Phase 4: INTEGRATE → Wire forms to JS, add CSS, deploy Apps Script
Phase 5: VERIFY → Test submit, test retry, test error fallback

🔴 Rule: NEVER skip Phase 1. Always read existing forms first.

Phase 1: DISCOVER (Scan & Analyze)

Goal: Understand what forms exist and what fields they have.

Actions:

1. Search for forms in the project:

   grep -r "data-form-type\|onsubmit\|<form" --include="*.html" .
   

2. For each form found, extract:

3. Ask user (Socratic Gate):
   • How many separate Google Sheets? (1 shared sheet or separate?)
   • What columns does each sheet need?
   • Is there a fallback contact channel? (WhatsApp, Messenger, Hotline?)
   • Fallback contact URL (e.g., https://wa.me/15551234567)

Output: Form Inventory Table

| # | Form Type | Pages | Fields | Target Sheet |
|---|-----------|-------|--------|-------------|
| 1 | massage   | 7     | name, phone, branch, problem, time, package | Sheet Massage |
| 2 | course    | 1     | name, phone, goal | Course Sheet |

Phase 2: PLAN (Design & Map)

Goal: Map form fields → Sheet columns → Apps Script params.

Sheet Column Design

For each sheet, define columns in order:

Naming Convention

Deliverables Checklist

• Apps Script code per sheet
• Frontend JS with retry + toast
• Toast CSS component
• HTML form markup template
• Deploy instructions
• Verification test plan

Phase 3: BUILD (Generate Code)

3A. Google Apps Script Template

See templates/apps-script.js for the full template.

Key rules:

• Always use doPost(e) — NOT doGet
• Always wrap in try/catch
• Always return JSON with {status: "success"} or {status: "error", message: "..."}
• Column order MUST match sheet.appendRow([...]) order
• Tab name MUST match SHEET_NAME constant

3B. Frontend JavaScript

See templates/form-submit.js for the full template.

Key features:

3C. Toast CSS

See templates/toast.css for the full template.

3 variants: --success, --error, --retrying

3D. HTML Form Markup

See templates/form-markup.html for examples.

Required attributes:

<form data-form-type="TYPE" onsubmit="window.submitToGoogleSheet(event)">
  <input type="hidden" name="url" value="">
  <!-- form fields with name="..." -->
  <button type="submit">Submit Text</button>
</form>

Phase 4: INTEGRATE (Wire Everything)

Step-by-step:

1. Add Toast CSS → Append to main CSS file (e.g., design-system.css)
2. Add Form JS → Add to shared JS file or create js/form-handler.js
3. Update HTML forms:
   • Add data-form-type="..." attribute
   • Add onsubmit="window.submitToGoogleSheet(event)"
   • Add <input type="hidden" name="url" value="">
   • Ensure all inputs have name="..." matching Apps Script params
4. Configure URLs:
   • Replace placeholder URLs in JS with deployed Apps Script URLs
5. Configure fallback contact:
   • Replace Zalo URL in JS toast with project's contact URL

Customization Points

Phase 5: VERIFY (Test & Report)

Test Checklist

How to Test Retry

1. Open DevTools → Network tab
2. Block domain script.google.com
3. Submit form → Should see 3 retry attempts
4. Unblock → Submit again → Should succeed

Report Template

## Form Integration Test Report

**Date:** YYYY-MM-DD
**Pages tested:** X/Y

| Page | Form Type | Submit | Retry | Fallback | Sheet |
|------|-----------|--------|-------|----------|-------|
| index.html | massage | ✅ | ✅ | ✅ | ✅ |
| khoa-hoc.html | course | ✅ | ✅ | ✅ | ✅ |

**Issues found:** None / [list issues]
**Resolution:** [fixes applied]

❌ Anti-Patterns

📑 Templates

🔗 Related Skills