/cm-google-form

name: cm-google-form
description: Google App Script form-to-sheet integration with auto-retry, toast notifications, and Zalo/contact fallback. Reusable across any static website.
allowed-tools: Read, Write, Edit, Glob, Grep, Browser
version: 1.0
priority: HIGH

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

| Trigger | Action | |---------|--------| | User says "create form", "connect Google Sheet" | Activate this skill | | User says "form broken", "submit not working" | Debug using Phase 4-5 | | User says "add new form to page" | Start from Phase 2 | | User says "form for another website" | Start from Phase 1 |

---

📋 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:**

| Info | How to Find | |------|-------------| | Form type | `data-form-type` attribute | | Fields | `<input name="...">`, `<select name="...">` | | Submit handler | `onsubmit` attribute | | Page URL | File path |

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:

| Column | Source | Always Include | |--------|--------|---------------| | Timestamp | `new Date()` — auto | ✅ Yes | | (form fields) | `e.parameter.xxx` | From inventory | | Page Source | `e.parameter.url` | ✅ Yes |

Naming Convention

| Element | Convention | |---------|-----------| | Sheet tab name | `Data` | | Form attribute | `data-form-type="<type>"` | | Hidden URL field | `<input type="hidden" name="url" value="">` | | JS global function | `window.submitToGoogleSheet` |

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:**

| Feature | Detail | |---------|--------| | Auto-retry | 3 attempts, exponential backoff (1s → 2s → 4s) | | Toast UI | Success (green), Error (red), Retrying (amber) | | Phone validation | Vietnamese format: `/^0\d{8,10}$/` | | Button states | "Submitting..." → "Retrying (X/3)..." → reset | | CORS handling | Handles opaque responses from Apps Script | | Fallback | Zalo button in error toast | | Auto-dismiss | Success: 6s, Error: 15s, Retrying: 10s |

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

| Setting | Location | Default | |---------|----------|---------| | Apps Script URLs | JS `URLS` object | placeholder | | Fallback contact | Toast Zalo link | `https://zalo.me/...` | | Max retries | `fetchWithRetry` arg | 3 | | Phone regex | Validation block | `/^0\d{8,10}$/` | | Toast auto-dismiss | `showFormToast` timeouts | 6s/15s/10s | | Success message | `.then()` block | Customizable | | Error message | `.catch()` block | Customizable |

---

Phase 5: VERIFY (Test & Report)

Test Checklist

| # | Test Case | Expected | Status | |---|-----------|----------|--------| | 1 | Submit valid form | Toast success (green) + Zalo opens | | | 2 | Submit invalid phone | Toast error "Invalid phone