FormOMatic Documentation

Overview

FormOMatic is a Google Forms renderer that allows you to:

• Embed Google Forms with custom styling that matches your website
• Use hidden fields to pass data (user IDs, page context, etc.)
• Capture tracking data (IP address, referrer, geolocation)
• Host forms on custom branded pages
• Redirect users after form submission

FormOMatic acts as a styling layer on top of Google Forms. Your form data is still submitted to and stored in Google Forms/Sheets - FormOMatic just provides a better presentation layer.

Quick Start

Get a form embedded on your site in 3 steps:

Step 1: Create a Google Form

Create your form at forms.google.com and copy the public form URL (the one that ends in /viewform).

Step 2: Add to FormOMatic

Go to the FormOMatic Builder, paste your Google Form URL, customize the styling, and save the form.

Step 3: Embed on Your Site

Copy the embed code and paste it into your website's HTML:

<!-- FormOMatic Embed -->
<div id="formomatic-abc123"></div>
<script src="https://formomatic.com/app/assets/js/customform.js"></script>
<script src="https://formomatic.com/app/api/embed.php?id=abc123"></script>
<link rel="stylesheet" href="https://formomatic.com/app/assets/css/styles-embed.css">

Creating Forms in Google Forms

Supported Question Types

FormOMatic supports these Google Forms question types:

• Short answer - Single line text input
• Paragraph - Multi-line textarea
• Multiple choice - Radio buttons (can be styled as buttons or cards)
• Checkboxes - Multiple selection checkboxes
• Dropdown - Select menu
• Linear scale - Rating slider (1-5, 1-10, etc.)
• Multiple choice grid - Table of radio buttons
• Date - Date picker
• Time - Time picker

Form Settings Recommendations

• Enable "Collect email addresses" if you want respondent emails
• Set "Limit to 1 response" if needed (requires Google sign-in)
• Configure your response destination (Google Sheets recommended)

Getting the Form URL

After creating your form:

1. Click the "Send" button
2. Click the link icon
3. Copy the URL (should look like: https://docs.google.com/forms/d/e/XXXXX/viewform)

Embedding Forms

Basic Embed Code

The standard embed code consists of three parts:

<!-- 1. Container where form will render -->
<div id="formomatic-{PUBLIC_ID}"></div>

<!-- 2. Form renderer script -->
<script src="https://formomatic.com/app/assets/js/customform.js"></script>

<!-- 3. Form configuration (loads your saved settings) -->
<script src="https://formomatic.com/app/api/embed.php?id={PUBLIC_ID}"></script>

<!-- 4. Styles (optional but recommended) -->
<link rel="stylesheet" href="https://formomatic.com/app/assets/css/styles-embed.css">

Replace {PUBLIC_ID} with your form's public ID (e.g., abc123).

Multiple Forms on One Page

Each form needs its own container with unique ID:

<div id="formomatic-form1"></div>
<div id="formomatic-form2"></div>

<script src="https://formomatic.com/app/assets/js/customform.js"></script>
<script src="https://formomatic.com/app/api/embed.php?id=form1"></script>
<script src="https://formomatic.com/app/api/embed.php?id=form2"></script>
<link rel="stylesheet" href="https://formomatic.com/app/assets/css/styles-embed.css">

Hidden Fields

Hidden fields allow you to pass data to your form without the user seeing or filling in the field. This is useful for tracking context like user IDs, page URLs, or any custom data.

How to Create Hidden Fields

1. In Google Forms, add a Short answer question
2. Name it with the prefix hf- followed by your field name (e.g., hf-user-id)
3. In FormOMatic builder, the field will automatically be detected and hidden

Passing Values via Data Attributes

Pass values to hidden fields using data-hf-* attributes on the container:

<div id="formomatic-abc123"
     data-hf-user-id="12345"
     data-hf-page-url="https://example.com/contact"
     data-hf-source="homepage-banner">
</div>

The attribute name maps to the field name:

• data-hf-user-id maps to field named hf-user-id
• data-hf-page-url maps to field named hf-page-url
• data-hf-source maps to field named hf-source

Dynamic Values with JavaScript

<div id="formomatic-abc123"></div>
<script>
  // Set hidden field values dynamically
  const container = document.getElementById('formomatic-abc123');
  container.setAttribute('data-hf-user-id', getUserId());
  container.setAttribute('data-hf-timestamp', Date.now());
</script>

Tracking Fields

Tracking fields automatically capture visitor information. Unlike hidden fields, you don't need to pass values - FormOMatic fills them automatically.

Available Tracking Fields

Create Short answer questions in Google Forms with these exact names:

Setting Up Tracking Fields

1. In Google Forms, add Short answer questions named exactly as shown above
2. In FormOMatic, these will be auto-detected and hidden
3. Values are populated automatically when the form loads

Styling & Customization

FormOMatic provides extensive styling options in the builder. All styles are saved with your form configuration.

Available Style Options

Multiple Choice Display Styles

Multiple choice and checkbox fields can be displayed in three styles:

• Radio Buttons (default) - Standard radio/checkbox inputs
• Pill Buttons - Horizontal pill-shaped toggle buttons
• Cards - Large card-style buttons with optional images

Custom Submit Button Text

Change the submit button text from "Submit" to anything you want (e.g., "Send Message", "Get Quote", "Sign Up").

Hosted Pages

FormOMatic can host your forms on branded pages without embedding on your own site.

Hosted Page URL Structure

https://pages.formomatic.com/{username}/{form-slug}/

Setting Up Hosted Pages

1. In your account settings, set your home slug (username)
2. When saving a form, set a form slug
3. Your form will be available at the hosted URL

Redirect After Submit

Instead of showing a "Thank you" message, you can redirect users to a custom URL after form submission.

Setting a Redirect URL

1. In the FormOMatic builder, find "After Submission" in the sidebar
2. Enter your redirect URL (e.g., https://example.com/thank-you)
3. Save the form

Leave the field empty to show the default "Thank you" message.

Supported Field Types Reference

API Reference

Embed Endpoint

GET https://formomatic.com/app/api/embed.php?id={PUBLIC_ID}

Returns JavaScript that initializes and renders the form.

Parameters

Form Configuration Object

The embed endpoint returns a config object with these properties:

{
  formUrl: "https://docs.google.com/forms/d/e/.../viewform",
  styles: {
    primaryColor: "#667eea",
    textColor: "#2d3748",
    backgroundColor: "#ffffff",
    fontFamily: "system-ui",
    formWidth: "700px",
    borderRadius: "8px",
    // ... more style options
  },
  fieldOrder: [0, 1, 2, 3],           // Order of fields
  fieldRows: { "0": [0, 1], "1": [2] }, // Fields grouped in rows
  hiddenFields: [4, 5],               // Indices of hidden fields
  customLabels: {                      // Custom labels per field
    "0": { title: "Your Name", description: "..." }
  },
  submitButtonText: "Send Message",
  redirectUrl: "https://example.com/thanks",
  questions: [ ... ],                  // Parsed form questions
  trackingFields: [ ... ],             // Auto-filled tracking data
  hiddenFieldInfo: [ ... ]             // hf-* field mappings
}

CustomForm JavaScript Class

The form renderer class with available methods:

const form = new CustomForm(container, formUrl, containerId);

// Configuration methods
form.setStyles(stylesObject);
form.setFieldOrder(orderArray);
form.setFieldRows(rowsObject);
form.setHiddenFields(indicesArray);
form.setCustomLabels(labelsObject);
form.setSubmitButtonText(text);
form.setRedirectUrl(url);
form.setTrackingFields(fieldsArray);
form.setHiddenFieldInfo(infoArray);
form.setFormData(dataObject);

// Initialize and render
form.init();

WordPress Plugin

FormOMatic provides a WordPress plugin for easy embedding.

Installation

1. Download the plugin from formomatic-1.0.0.zip
2. In WordPress, go to Plugins → Add New → Upload Plugin
3. Upload the zip file and activate
4. Go to Settings → FormOMatic and enter your API key

Usage

Use the shortcode in any post or page:

[formomatic id="abc123"]

With Hidden Fields

[formomatic id="abc123" hf-user-id="123" hf-page="contact"]

Available Shortcode Attributes

Gutenberg Block

The plugin also adds a "FormOMatic Form" block to the block editor. Search for "FormOMatic" in the block inserter.

Troubleshooting

Form Not Loading

• Check that the container ID matches: formomatic-{PUBLIC_ID}
• Ensure all three scripts are loaded (customform.js, embed.php, styles-embed.css)
• Check browser console for JavaScript errors
• Verify the form is set to "active" status in FormOMatic

Styles Not Applying

• Make sure styles-embed.css is loaded
• Check for CSS conflicts with your site's styles
• Try disabling "Inherit Parent Styles" option

Hidden Fields Not Working

• Field names must start with hf- in Google Forms
• Data attributes must match: data-hf-fieldname
• Ensure attributes are set before the embed script loads

Form Submissions Not Recorded

• Verify the Google Form is accepting responses
• Check that required fields are filled
• Look for validation errors in the form