FormManager – Developer Documentation

Overview

Load and initialize

Load the hosted script as a classic script before DOMContentLoaded. It has no JavaScript dependencies. Bootstrap CSS supplies the default No/Yes button appearance, or you can style the generated classes yourself.

<script src="https://update.pmblue.us/resources/form_manager/js"></script>
<script>
document.addEventListener('DOMContentLoaded', () => {
  const form = FormManager.get_form('demo_form');
  if (form) form.check();
});
</script>

The library scans .fm-managed forms once on DOM ready, attaches change/click listeners, then sets global FORM_MANAGER_LOADED = true. It does not initially call check(). Load your initialization callback after the library's callback, and explicitly validate after applying initial values.

FormManager

Initialization

// Automatic (recommended): put class="fm-managed" on your <form>.
// The library auto-initializes on DOMContentLoaded.

// Manual: use a form that has not already been initialized.
const fm = new FormManager(document.querySelector('#dynamic-form'));
fm.fields.forEach(initialize_events);
fm.check();

The constructor creates field managers but does not attach their validation listeners. Call initialize_events(field) for each field when initializing manually, including when loading the script after DOM ready. Avoid constructing a second manager for an automatically initialized form.

Properties

Methods

Usage tip

// Preferred lookup:
const fm = FormManager.get_form('enroll_form');

// Legacy/indexed:
const fallback = FormManager.forms[0];

FieldManager

Each discovered control becomes a FieldManager. Its classes determine type and rules.

Supported classes

Field API

Field Classes (What to add to your markup)

Validation callbacks

Form callbacks (assign on the FormManager instance)

Field validator

Assign a validator function to any field:

// Return values:
//   true  ? valid
//   false ? invalid (unknown reason)
//   "msg" ? invalid (specific reason)
const ssn = FormManager.get_form('demo_form').get_field('ssn');
ssn.validator = (input) => {
  const digits = (input.value || '').replace(/\D+/g,'');
  return /^(?!000|666|9\d\d)\d{3}(?!00)\d{2}(?!0000)\d{4}$/.test(digits)
    ? true
    : 'Enter a valid SSN.';
};

Examples

Quick markup

<form class="fm-managed" name="demo_form">
  <div class="mb-3">
    <label class="form-label">Email</label>
    <input name="email" class="form-control fm-required fm-email">
    <div class="invalid-feedback"></div>
  </div>

  <div class="mb-3">
    <label class="form-label">Phone</label>
    <input name="phone" class="form-control fm-required fm-phone">
    <div class="invalid-feedback"></div>
  </div>

  <div class="mb-3">
    <label class="form-label">SSN</label>
    <input name="ssn" class="form-control fm-ssn fm-required">
    <div class="invalid-feedback"></div>
  </div>

  <div class="mb-3">
    <label class="form-label">Do you agree?</label>
    <div class="fm-no-yes fm-required" name="agree" id="agree"></div>
    <small class="text-muted">This control creates a hidden input with the same name and id; value will be "No" or "Yes".</small>
    <div class="invalid-feedback"></div>
  </div>

  <button type="submit" class="btn btn-primary" disabled>Submit</button>
</form>

Hook up callbacks & use get_form

document.addEventListener('DOMContentLoaded', () => {
  const fm = FormManager.get_form('demo_form');
  if (!fm) return;

  fm.valid_func = (form) => {
    form.fields.forEach(clearError);
    const submit = form.form.querySelector('[type=submit]');
    if (submit) submit.disabled = false;
  };
  fm.incomplete_func = (field) => showError(field, 'This field is required.');
  fm.invalid_func = (field, msg) => showError(field, msg || 'Invalid value.');

  // Initialization does not validate until requested.
  fm.check();
  fm.form.addEventListener('submit', (event) => {
    if (fm.check() !== true) event.preventDefault();
  });

  function showError(field, message) {
    const el = field.get_type() === 'no-yes'
      ? field.field.parentElement : field.field;
    el?.classList?.add('is-invalid');
    const fb = el?.nextElementSibling;
    if (fb && fb.classList.contains('invalid-feedback')) fb.textContent = message;
    const submit = field.form.form.querySelector('[type=submit]');
    if (submit) submit.disabled = true;
  }
  function clearError(field) {
    const el = field.get_type() === 'no-yes'
      ? field.field.parentElement : field.field;
    el?.classList?.remove('is-invalid');
    const fb = el?.nextElementSibling;
    if (fb && fb.classList.contains('invalid-feedback')) fb.textContent = '';
  }
});

Set values and restore No/Yes fields

set_value() returns the stored DOM value. A No/Yes field accepts the exact strings "Yes" and "No", dispatches fm_set_value, and updates active button classes. The container is renamed with an _div suffix while its hidden input receives the original ID and name.

const fm = FormManager.get_form('demo_form');
fm.get_field('agree').set_value('Yes');

// For an input with type="date": numbers are milliseconds since the epoch.
const start = fm.get_field('start_date');
if (start) {
  start.set_value(new Date(2026, 8, 20)); // local calendar date
  start.set_value('2026-09-20');          // native date-input string
}
fm.check();

For date inputs, Date objects and numeric timestamps are converted with local getFullYear(), getMonth(), and getDate() into YYYY-MM-DD. Other inputs receive the value directly. Setting a value does not trigger the form’s validation change handler; call check() explicitly.

For new No/Yes containers, data-value="Yes" or data-value="1" initializes Yes; any other non-empty data-value initializes No. With no value the hidden input starts empty. Required No/Yes fields consider both Yes and No complete; require consent explicitly with a custom validator when only Yes is allowed.

Existing snapshot markup is reused when the container already contains input.fm-ny-input, .fm-no, and .fm-yes. The saved input value is preserved and an existing _div suffix is normalized. Initial snapshot construction does not synchronize button active classes; call set_value(field.get_value()) on the field after restoring to synchronize its UI.

const agree = fm.get_field('agree');
agree.set_value(agree.get_value());
agree.validator = (input) => input.value === 'Yes'
  ? true : 'Please select Yes to consent.';

Add a field after initialization

const extra = document.createElement('input');
extra.name = 'alternate_email';
extra.className = 'fm-email';
fm.form.appendChild(extra);
fm.add_field(extra); // constructs the manager and attaches change handling
fm.check();

Form and field object relationships

Each FormManager wraps one form element in form.form and holds its field managers in form.fields. Each FieldManager points back to the owning manager through field.form and to its value-bearing DOM element through field.field. For a No/Yes control that element is the generated or restored hidden input, not the visible container.

All validators and callbacks are synchronous. Return exactly true for success; a Promise from an async function is not awaited and will be treated as failure. Validators receive DOM elements; form failure callbacks receive FieldManager objects; valid_func and additional_validation_func receive the FormManager.

Form workflows

1. Cross-field confirmation with visible feedback

This runs after initialization of a form named signup containing fields named email and confirm_email. It adds a message element, makes both fields required, and defines the UI behavior for every validation path.

const signup = FormManager.get_form('signup');
if (signup) {
  const email = signup.get_field('email');
  const confirmation = signup.get_field('confirm_email');
  const message = document.createElement('p');
  signup.form.appendChild(message);
  const submit = signup.form.querySelector('[type="submit"]');
  const report = (text, valid) => {
    message.textContent = text;
    if (submit) submit.disabled = !valid;
  };
  email.required = true;
  confirmation.required = true;
  signup.incomplete_func = field => report(`${field.name} is required`, false);
  signup.invalid_func = (field, error) => report(error || `${field.name} is invalid`, false);
  signup.additional_validation_func = manager => {
    if (manager.get_field('email').get_value() !== confirmation.get_value()) {
      report('Email addresses must match', false);
      return false;
    }
    return true;
  };
  signup.valid_func = () => report('', true);
  signup.form.addEventListener('submit', event => {
    if (signup.check() !== true) event.preventDefault();
  });
  signup.check();
}

2. Restore saved field values and collect a payload

This example assumes a managed form named profile with ordinary single-value controls, including a No/Yes field contact_allowed and date input review_date. It skips missing saved fields safely. Each set_value() updates the object and its DOM element before one final check.

const profile = FormManager.get_form('profile');
const saved = {display_name: 'Taylor', contact_allowed: 'No', review_date: '2026-09-20'};
if (profile) {
  for (const [name, value] of Object.entries(saved)) {
    const field = profile.get_field(name);
    if (field) field.set_value(value);
  }
  profile.check();
  profile.form.addEventListener('submit', event => {
    event.preventDefault();
    if (profile.check() !== true) return;
    const payload = {};
    for (const field of profile.fields) {
      if (field.name) payload[field.name] = field.get_value();
    }
    console.log(JSON.stringify(payload));
  });
}

The payload loop is for single-value fields. Handle checked state, repeated names, multi-selects, and file inputs explicitly when your form contains them. FormManager has no built-in network submission API.

3. Create a managed form dynamically

This form is added after DOM ready, so it uses manual construction. The input exists before the manager scans it; initialize its events once. Later controls can be added through add_field().

const element = document.createElement('form');
element.name = 'dynamic_contact';
const address = document.createElement('input');
address.name = 'email';
address.className = 'fm-email';
address.required = true;
const button = document.createElement('button');
button.type = 'submit';
button.textContent = 'Save contact';
element.append(address, button);
document.body.appendChild(element);

const contact = new FormManager(element);
contact.fields.forEach(initialize_events);
const notes = document.createElement('textarea');
notes.name = 'notes';
element.insertBefore(notes, button);
contact.add_field(notes);
element.addEventListener('submit', event => {
  event.preventDefault();
  if (contact.check() === true) {
    console.log(contact.get_field('email').get_value());
  }
});
contact.check();

Validation behavior

Empty values generally pass type validators; required checks run separately. Native input types do not select these validators: add the corresponding fm-* class. If several type classes are present, the first match wins in this order: email, phone, SSN, No/Yes, number, street address.

• Validation runs on change for ordinary controls and on No/Yes clicks, not on every keystroke. The constructor and DOM-ready initialization do not intercept form submission.
• Default callbacks enable or disable the first submit control. Add a submit listener calling check(), as shown above, and perform server validation for submitted data.
• Keep callable incomplete_func and invalid_func callbacks. Setting one to null suppresses both its UI action and that branch’s failure result. Replace with a no-op function to suppress UI while preserving failure behavior.
• additional_validation_func must return exactly true. Failure returns false but does not invoke a failure callback or disable submit automatically; the callback must update any required UI.
• get_value() reads .value, so checkboxes/radio inputs need application logic using .checked. It does not collect all selected values from a multiple select.
• Type, required state, and validators are captured at construction. Changing CSS classes later does not automatically replace the stored validator or required flag. Update the manager explicitly.