FormManager

Overview

FormManager is the form management system in Now.js Framework. It supports validation, auto-submit, and API integration.

When to use:

• Need form handling
• Need validation
• Need AJAX submission
• Need auto-enhance form elements

Why use it:

• ✅ Automatic validation
• ✅ AJAX submission
• ✅ Loading states
• ✅ Error display
• ✅ Auto-enhance elements
• ✅ Multiple submit handlers
• ✅ Declarative result binding for search/list forms

Basic Usage

HTML Declarative

<form data-form="user-create"
      data-action="/api/users"
      data-method="POST">
  <input type="text" name="name" required>
  <input type="email" name="email" required>
  <button type="submit">Submit</button>
</form>

With Success Redirect

<form data-form="user-create"
      data-action="/api/users"
      data-success-redirect="/users">
  ...
</form>

With Notification

<form data-form="contact"
      data-action="/api/contact"
      data-success-message="Message sent successfully!">
  ...
</form>

Data Attributes

Form level — validation and messages

Form level — security and submission

Form level — the submit lock (double-submit protection)

While a form is being submitted FormManager locks it where the visitor can see it: every submit button of the form (including one outside it that points at it with the form attribute) is disabled, gets the loading class (a spinner on .btn) and aria-busy="true", and the <form> gets the submitting class. Submits that arrive meanwhile are ignored.

A button that was already disabled is not enabled when the lock is released.

Field level — per-field error messages

Put these on an <input>, <select> or <textarea> to replace the standard text.

Server-side field errors returned in the API errors object stay visible through subsequent validation. They clear when the user edits the field (input or change), not just because the field was already dirty. Toasts prefix a known field as Field label: message; unknown fields show the message without a label.

Field level — remembering what was typed

Note: named form fields are submitted exactly like a native form submit. If your sort, filter, keyword, category, or hidden paging inputs live in the same form, they will be re-sent automatically on every AJAX submit and pagination click.

Reserved form names

data-form both switches the form on and names it. Two names are reserved: FormManager
recognises them and applies authentication behaviour no attribute asked for.

data-form="login"

A form named login is treated as the login form of the page:

The redirect is what catches people out: a login form ignores data-success-redirect,
data-redirect and data-use-intended-url. Those are read by determineRedirectUrl(),
which a login form never reaches. RedirectManager.afterLogin() picks the destination:

1. data-redirect-after-login on the form, when it is set — the intended route is skipped
2. the intended route the guard stored when it bounced the visitor to the login page
3. RouterManager.config.auth.redirects.afterLogin
4. / — the built-in after_login target

A redirect action in the response does not replace this either. Every other form skips
its own redirect when the response carries one; a login form runs
RedirectManager.afterLogin() regardless, and since the action waits out its delay
(1000 ms by default) while afterLogin() navigates immediately, the server's action
loses. Send the destination as data-redirect-after-login, or configure
RouterManager.config.auth.redirects.afterLogin.

<!-- Real login form: no redirect attribute needed, and none would be honoured -->
<form data-form="login" data-action="/api/auth/login" data-method="POST"
      data-ajax-submit="true" data-auto-fill-intended-url="true">
  <input type="email" name="username" required>
  <input type="password" name="password" required>
  <label><input type="checkbox" name="remember"> Remember me</label>
  <button type="submit">Sign in</button>
</form>

data-form="register"

When the response of a form named register carries both data.user and data.token,
FormManager signs the new account in the same way — one call to
AuthManager.setAuthenticatedUser(), no separate login step. Its redirect is the ordinary
one, so data-success-redirect and data-redirect work as usual.

Any other form that posts credentials

A demo, a sign-in widget inside a bigger page, or a modal that authenticates a second
account: name it anything else — signin, login-demo, account-login — and the form
stays an ordinary form, redirecting only where you tell it to.

Declarative Watched API Binding

Use this pattern when a form has derived UI that depends on multiple fields and you want the server to return a payload that can be rebound with normal TemplateManager directives.

How it works

1. FormManager reads the fields listed in data-watch-fields.
2. When one of the fields in data-watch-trigger changes, FormManager calls data-watch-api. If data-watch-on-load is not set to false, the watched API is also called once after the initial load payload has been applied.
3. The response payload is merged back into the form state with setFormData().
4. Existing bindings such as data-text, data-attr, data-if, and data-for update automatically.

Example: Derived Leave Preview

<form data-form="leave-request"
      data-load-api="api/eleave/request/get"
      data-watch-api="api/eleave/request/policy"
      data-watch-fields="id,leave_id,start_date,start_period,end_date,end_period"
      data-watch-trigger="leave_id,start_date,start_period,end_date,end_period"
      data-watch-debounce="150">

  <select name="leave_id" data-options-key="leave_id" data-attr="value:leave_id"></select>
  <input type="date" name="start_date" data-attr="value:start_date">
  <input type="date" name="end_date" data-attr="value:end_date">

  <aside data-text="preview.leave_type_detail"></aside>
  <input type="text" data-attr="value:preview.days" readonly>
  <div class="comment" data-text="preview.days_note"></div>

  <div data-if="preview.balance_summary">
    <div data-for="year in preview.balance_summary.years">
      <template>
        <div>
          <strong data-text="year.heading_text"></strong>
          <div data-text="year.summary_text"></div>
        </div>
      </template>
    </div>
  </div>
</form>

Response Shape

The watched API can return any payload that setFormData() can bind. A common pattern is to return a nested preview object plus any supporting option collections.

{
  "success": true,
  "data": {
    "preview": {
      "leave_type_detail": "Vacation • 10 days/year",
      "days": "1.5",
      "days_note": "Calculated automatically from the selected date range",
      "balance_message": "",
      "balance_summary": {
        "years": []
      }
    }
  }
}

Use watched API binding when the UI is a pure function of current form values. If the response should execute server actions such as notification, redirect, modal, or form, use requestApi instead.

data-watch-on-load defaults to true. If data-load-api already returns the derived state you need, set data-watch-on-load="false" to avoid a second initial request.

Use requestApi with data-response-bind="template" when the response should update a non-form target or when the page needs explicit control over which request parameters are sent.

When a result form should keep its filters shareable or refresh-safe, add data-submit-query-params="true" and optionally data-submit-query-fields="year,leave_id,...". FormManager will update the browser query string with the submitted values after each successful AJAX submit.

Declarative Result Binding

Use this pattern when a form should submit with AJAX, bind the response into a result container, and let FormManager create pagination buttons automatically.

How it works

1. The form submits via AJAX.
2. FormManager normalizes the success payload into a canonical schema similar to TableManager:

{
  data: [...],
  meta: {
    page: 1,
    pageSize: 20,
    total: 23,
    totalPages: 2
  },
  filters: {},
  options: {}
}

1. The full normalized payload is exposed on context.state.
2. The primary data source is exposed on context.data.
3. Pagination buttons are rendered into data-submit-pagination-target and update the field named by data-submit-page-field before re-submitting the same form.

Example: Search Form With Cards

<form data-form="partSearch"
      action="api/parts/search/get"
      method="get"
      data-ajax-submit="true"
      data-submit-target="#partResults"
      data-submit-pagination-target="#partResultsPagination"
      data-submit-page-field="page">

  <input type="text" name="q" placeholder="Search...">
  <select name="category_id">
    <option value="">All categories</option>
  </select>
  <input type="hidden" name="page" value="1">
  <input type="hidden" name="limit" value="20">

  <button type="submit">Search</button>
</form>

<section id="partResults" class="hidden" data-class="hidden:!submitted" data-on-load="hydratePartResults">
  <header>
    <p data-if="hasData">
      Showing <strong data-text="pagination.from"></strong>
      -
      <strong data-text="pagination.to"></strong>
      of <strong data-text="meta.total"></strong>
    </p>
  </header>

  <div class="grid" data-if="hasData">
    <div data-for="item in data">
      <template>
        <article class="card">
          <h3 data-text="item.name"></h3>
          <p data-text="item.part_no"></p>
        </article>
      </template>
    </div>
  </div>

  <p data-if="empty">No results</p>
</section>

<div id="partResultsPagination"></div>

Expected API Response

{
  "success": true,
  "data": {
    "data": [{"id": 1, "name": "Gear", "part_no": "GEAR-001"}],
    "total": 23,
    "page": 1,
    "limit": 20,
    "pages": 2
  }
}

Optional data-on-load hydration

function hydratePartResults(element, context) {
  const rows = Array.isArray(context.data) ? context.data : [];
  const meta = context.state?.meta || {};

  console.log('rows', rows);
  console.log('page', meta.page, 'of', meta.totalPages);
}

Active menu item of a page that loads data

When the data data-load-api returns carries menu_path, the menu selects that link instead of the route's menuPath — for example a document page /order?id=248 that belongs under the /orders?status=INV menu item by its type. Without it, the menu item is chosen as before — see MenuManager: Letting the API choose the menu item.

$order['menu_path'] = '/inventory-orders?status='.$order['document_type'];

JavaScript API

// Get a form instance by id — returns the stored state object, not a wrapper with methods
const instance = FormManager.getInstance('my-form');

// Read the form values (accepts an id or an element)
const data = FormManager.getValues('my-form');

// Populate the form — pass silent = true to skip events
FormManager.setFormData(instance, {
  name: 'John',
  email: 'john@example.com'
}, false);

// Reset the form
FormManager.resetForm(instance);

// Validate the whole form
const isValid = await FormManager.validateForm(instance);

// Submit over ajax
await FormManager.submitAjax(instance, FormManager.getFormData(instance));

Every method lives on FormManager, not on the instance — getInstance() only
returns the state object held in a Map, so instance.submit() does not exist.

Validation

HTML5 Validation

<input type="text" name="name" required minlength="2" maxlength="50">
<input type="email" name="email" required>
<input type="number" name="age" min="18" max="100">
<input type="url" name="website" pattern="https?://.+">

Custom Validation

<input type="text" name="username"
       data-validate="username"
       data-validate-message="Username must be 3-20 characters">

FormManager.registerValidator('username', (value) => {
  return /^[a-zA-Z0-9_]{3,20}$/.test(value);
});

Async Validation

FormManager.registerValidator('unique-email', async (value) => {
  const response = await ApiService.get(`/api/check-email?email=${value}`);
  return response.data.available;
});

Events

All of these go out through EventManager.emit(), which does not dispatch a DOM
event — listen with EventManager.on(), not addEventListener():

EventManager.on('form:submitted', (data) => {
  console.log('Form submitted:', data.formId, data.response);
});

API Reference

FormManager.getInstance(id)

Get form instance

FormManager.submit(element)

Submit form

FormManager.validate(element)

Validate form

Returns: boolean

FormManager.reset()

Reset form

FormManager.getValues(identifier)

Get form values

Returns: Object

FormManager.registerValidator(name, fn, defaultMessage)

Add custom validator

FormManager.reloadFormData(target)

Fetches data-load-api again and fills the form the way the first load did: fields, options, and every table or line-item list bound to the form's data. The cache is bypassed, file inputs are cleared, nothing counts as edited any more, and the fresh values become the baseline a reset returns to.

A table without a data-source of its own gets its rows from the form, so this is how it shows new rows after a save. A response can ask for it with {"type": "redirect", "url": "reload", "target": "form"} (see ResponseHandler).

Returns: Promise<boolean> - false when the form is not found, declares no data-load-api, or the request failed

await FormManager.reloadFormData('editproduct');

Real-World Examples

Contact Form

<form data-form="contact"
      data-action="/api/contact"
      data-method="POST"
      data-success-message="Message sent successfully!"
      data-success-reset="true">

  <div class="form-group">
    <label>Name</label>
    <input type="text" name="name" required>
  </div>

  <div class="form-group">
    <label>Email</label>
    <input type="email" name="email" required>
  </div>

  <div class="form-group">
    <label>Message</label>
    <textarea name="message" required minlength="10"></textarea>
  </div>

  <button type="submit">Send</button>
</form>

Edit Form

<form data-form="user-edit"
      data-action="/api/users/{{id}}"
      data-method="PUT"
      data-success-redirect="/users"
      data-confirm="Confirm save?">

  <input type="hidden" name="id" value="{{id}}">
  <input type="text" name="name" value="{{name}}">
  <input type="email" name="email" value="{{email}}">

  <button type="submit">Save</button>
</form>

Search Form With Automatic Pagination

<form data-form="usersSearch"
      action="/api/users/search"
      method="get"
      data-ajax-submit="true"
      data-submit-target="#userResults"
      data-submit-pagination-target="#userResultsPagination"
      data-submit-page-field="page">

  <input type="text" name="search" placeholder="Keyword">
  <select name="status">
    <option value="">All statuses</option>
    <option value="active">Active</option>
    <option value="inactive">Inactive</option>
  </select>
  <input type="hidden" name="page" value="1">
  <input type="hidden" name="limit" value="20">

  <button type="submit">Filter</button>
</form>

<div id="userResults">
  <div data-for="user in data">
    <template>
      <article>
        <strong data-text="user.name"></strong>
      </article>
    </template>
  </div>
</div>

<div id="userResultsPagination"></div>

File Upload

<form data-form="upload"
      data-action="/api/upload"
      data-enctype="multipart/form-data">

  <input type="file" name="document"
         accept=".pdf,.doc,.docx"
         required>

  <button type="submit">Upload</button>
</form>

With Custom Handler

form:submitting is emitted through EventManager.emit(), so a listener can
observe a submit but cannot cancel it — there is no DOM event to call
preventDefault() on:

EventManager.on('form:submitting', (data) => {
  console.log('Submitting form:', data.formId);
});

To take the submit over completely, leave data-form off the element and handle
the native submit event yourself:

const form = document.getElementById('custom-form');

form.addEventListener('submit', async (e) => {
  e.preventDefault();

  const formData = FormManager.getValues(form);

  // Custom processing
  formData.processed = true;

  try {
    const response = await ApiService.post('/api/custom', formData);
    NotificationManager.success('Success!');
  } catch (error) {
    NotificationManager.error(error.message);
  }
});

CSS for Validation

/* Invalid field */
.form-group.invalid input,
.form-group.invalid textarea,
.form-group.invalid select {
  border-color: #ef4444;
}

/* Error message */
.form-group .error-message {
  color: #ef4444;
  font-size: 0.875rem;
  margin-top: 4px;
}

/* Valid field */
.form-group.valid input {
  border-color: #22c55e;
}

/* Loading state */
form.loading button[type="submit"] {
  opacity: 0.7;
  pointer-events: none;
}

form.loading button[type="submit"]::after {
  content: ' ⏳';
}

Common Pitfalls

⚠️ 1. Must Have name Attribute

<!-- ❌ Missing name -->
<input type="text" id="username">

<!-- ✅ Has name -->
<input type="text" name="username">

⚠️ 2. Button type

<!-- ❌ Default can submit -->
<button>Click</button>

<!-- ✅ Specify type -->
<button type="submit">Submit</button>
<button type="button">Cancel</button>

Related Documentation

• ElementManager - Form elements
• ApiService - API calls
• NotificationManager - Notifications