FormManager

ภาพรวม

FormManager คือระบบจัดการ forms ใน Now.js Framework รองรับ validation, auto-submit และ API integration

ใช้เมื่อ:

• ต้องการ form handling
• ต้องการ validation
• ต้องการ AJAX submission
• ต้องการ auto-enhance form elements

ทำไมต้องใช้:

• ✅ Automatic validation
• ✅ AJAX submission
• ✅ Loading states
• ✅ Error display
• ✅ Auto-enhance elements
• ✅ Multiple submit handlers
• ✅ Declarative result binding สำหรับฟอร์มค้นหา/รายการ

การใช้งานพื้นฐาน

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="ส่งข้อความสำเร็จ!">
  ...
</form>

Data Attributes

ระดับฟอร์ม — การตรวจสอบและข้อความ

ระดับฟอร์ม — ความปลอดภัยและการส่ง

ระดับฟิลด์ — ข้อความผิดพลาดเฉพาะฟิลด์

ใส่บน <input> <select> หรือ <textarea> เพื่อแทนข้อความมาตรฐาน

ระดับฟิลด์ — จำค่าที่กรอกไว้

หมายเหตุ: ถ้า sort, filter, keyword, category หรือ hidden paging fields อยู่ในฟอร์มเดียวกันและมี name อยู่แล้ว ค่าพวกนี้จะถูกส่งซ้ำอัตโนมัติทุกครั้งที่ submit แบบ AJAX หรือกดแบ่งหน้า

ชื่อฟอร์มที่ถูกสงวน

data-form ทำสองอย่างพร้อมกัน คือเปิดใช้งานฟอร์มและตั้งชื่อให้ฟอร์มนั้น โดยมีชื่อที่ถูกสงวนไว้ 2 ชื่อ
ซึ่ง FormManager จะจำได้และใส่พฤติกรรมของระบบ authentication ให้เอง แม้ไม่ได้สั่งผ่าน attribute ใดเลย

data-form="login"

ฟอร์มที่ชื่อ login จะถูกถือว่าเป็นฟอร์ม login ของหน้านั้น:

เรื่องที่มักทำให้งง คือการเปลี่ยนหน้า: ฟอร์ม login จะไม่สนใจ data-success-redirect,
data-redirect และ data-use-intended-url เพราะ attribute เหล่านั้นถูกอ่านใน
determineRedirectUrl() ซึ่งฟอร์ม login ไม่เคยวิ่งไปถึง ปลายทางจริงถูกเลือกโดย
RedirectManager.afterLogin() ตามลำดับนี้:

1. data-redirect-after-login ที่ตั้งไว้บนฟอร์ม — ถ้ามี จะข้าม intended route ไปเลย
2. intended route ที่ guard เก็บไว้ตอนเด้งผู้ใช้มาหน้า login
3. RouterManager.config.auth.redirects.afterLogin
4. / — ค่าเริ่มต้นของ after_login

การส่ง action ชนิด redirect กลับมาก็ไม่ได้แทนที่ลำดับนี้เช่นกัน ฟอร์มอื่นจะข้ามการ redirect ของ
ตัวเองเมื่อผลลัพธ์มี action นี้ แต่ฟอร์ม login จะเรียก RedirectManager.afterLogin() เสมอ และ
เนื่องจาก action ต้องรอ delay ของมันก่อน (ค่าเริ่มต้น 1000 ms) ส่วน afterLogin() เปลี่ยนหน้าทันที
ผลคือ action จากเซิร์ฟเวอร์แพ้ ถ้าต้องการกำหนดปลายทางเอง ให้ส่งผ่าน data-redirect-after-login
หรือตั้งค่าที่ RouterManager.config.auth.redirects.afterLogin

<!-- ฟอร์ม login จริง: ไม่ต้องใส่ attribute redirect และถึงใส่ก็ไม่มีผล -->
<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"> จำฉันไว้</label>
  <button type="submit">เข้าสู่ระบบ</button>
</form>

data-form="register"

ถ้าผลลัพธ์ของฟอร์มชื่อ register มีทั้ง data.user และ data.token FormManager จะพาผู้ใช้ใหม่
เข้าสู่ระบบให้ด้วยวิธีเดียวกัน คือเรียก AuthManager.setAuthenticatedUser() โดยไม่ต้อง login ซ้ำ
ส่วนการเปลี่ยนหน้ายังเป็นแบบปกติ data-success-redirect และ data-redirect จึงใช้ได้ตามเดิม

ฟอร์มอื่นที่ส่ง credentials

ไม่ว่าจะเป็นฟอร์มตัวอย่าง, กล่อง sign-in ที่ฝังอยู่ในหน้าใหญ่ หรือ modal ที่ยืนยันตัวตนของอีกบัญชี
ให้ตั้งชื่ออื่นแทน เช่น signin, login-demo, account-login แล้วฟอร์มนั้นจะเป็นฟอร์มธรรมดา
ที่เปลี่ยนหน้าเฉพาะตามที่สั่งไว้เท่านั้น

Declarative Watched API Binding

ใช้รูปแบบนี้เมื่อฟอร์มมี UI ที่คำนวณต่อจากหลาย field และต้องการให้ server ส่ง payload กลับมาเพื่อ bind ผ่าน directives ปกติของ TemplateManager โดยไม่ต้องเขียน JavaScript เฉพาะหน้า

หลักการทำงาน

1. FormManager อ่านค่าจาก field ที่ระบุไว้ใน data-watch-fields
2. เมื่อ field ใน data-watch-trigger เปลี่ยนค่า FormManager จะเรียก data-watch-api และถ้า data-watch-on-load ไม่ได้ตั้งเป็น false จะเรียกอีกครั้งหนึ่งหลังจาก initial load เสร็จ
3. payload ที่ตอบกลับจะถูก merge กลับเข้า form state ผ่าน setFormData()
4. bindings เดิม เช่น data-text, data-attr, data-if และ data-for จะอัปเดตเองอัตโนมัติ

ตัวอย่าง: 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

watched API สามารถส่ง payload ใดก็ได้ที่ setFormData() bind ได้ ตัวอย่างทั่วไปคือส่ง object ชื่อ preview พร้อม 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": []
      }
    }
  }
}

ใช้ watched API binding เมื่อ UI เป็นฟังก์ชันตรงของค่าฟอร์มปัจจุบัน ถ้าต้องการให้ response สั่ง notification, redirect, modal หรือ form ให้ใช้ requestApi แทน

data-watch-on-load เป็น true โดย default ถ้า data-load-api ส่ง derived state ที่ต้องใช้กลับมาอยู่แล้ว ให้ตั้ง data-watch-on-load="false" เพื่อตัด initial request รอบที่สอง

ถ้าผลลัพธ์ควรถูก bind ไปยัง target ที่อยู่นอกฟอร์ม หรือต้องการควบคุม params ที่ส่งอย่าง explicit ให้ใช้ requestApi คู่กับ data-response-bind="template"

Declarative Result Binding

ใช้รูปแบบนี้เมื่อฟอร์มควร submit แบบ AJAX แล้ว bind response ลงใน result container พร้อมให้ FormManager สร้างปุ่มแบ่งหน้าให้อัตโนมัติ

หลักการทำงาน

1. ฟอร์ม submit ผ่าน AJAX
2. FormManager จะ normalize payload ให้เป็น schema กลางคล้าย TableManager:

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

1. payload เต็มจะอยู่ใน context.state
2. data หลักสำหรับแสดงรายการจะอยู่ใน context.data
3. ปุ่มแบ่งหน้าจะถูก render ลง data-submit-pagination-target และจะอัปเดต field ตามชื่อใน data-submit-page-field ก่อน submit ฟอร์มเดิมซ้ำ

ตัวอย่าง: ฟอร์มค้นหา + card results

<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="ค้นหา...">
  <select name="category_id">
    <option value="">ทุกหมวดหมู่</option>
  </select>
  <input type="hidden" name="page" value="1">
  <input type="hidden" name="limit" value="20">

  <button type="submit">ค้นหา</button>
</form>

<section id="partResults" class="hidden" data-class="hidden:!submitted" data-on-load="hydratePartResults">
  <header>
    <p data-if="hasData">
      แสดง <strong data-text="pagination.from"></strong>
      -
      <strong data-text="pagination.to"></strong>
      จาก <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">ไม่พบข้อมูล</p>
</section>

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

รูปแบบ API Response ที่คาดหวัง

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

data-on-load สำหรับ hydrate เพิ่มเติม

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);
}

JavaScript API

// ดึง instance ของฟอร์มจาก id — คืน state object ไม่ใช่อ็อบเจกต์ที่มีเมธอด
const instance = FormManager.getInstance('my-form');

// อ่านค่าในฟอร์ม (รับ id หรือ element)
const data = FormManager.getValues('my-form');

// เติมค่าลงฟอร์ม — silent = true คือไม่ยิง event
FormManager.setFormData(instance, {
  name: 'John',
  email: 'john@example.com'
}, false);

// ล้างฟอร์ม
FormManager.resetForm(instance);

// ตรวจความถูกต้องทั้งฟอร์ม
const isValid = await FormManager.validateForm(instance);

// ส่งฟอร์มแบบ ajax
await FormManager.submitAjax(instance, FormManager.getFormData(instance));

เมธอดทุกตัวอยู่บน FormManager ไม่ใช่บนตัว instance — getInstance() คืน
state object ที่เก็บใน Map เท่านั้น เรียก instance.submit() ไม่ได้

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 ต้องมี 3-20 ตัวอักษร">

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;
});

เหตุการณ์

เหตุการณ์ทั้งหมดนี้ส่งผ่าน EventManager.emit() ซึ่งไม่ได้ dispatch DOM event
จึงต้องดักด้วย EventManager.on() ไม่ใช่ addEventListener():

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

API อ้างอิง

FormManager.getInstance(id)

รับ 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

ตัวอย่างการใช้งานจริง

Contact Form

<form data-form="contact"
      data-action="/api/contact"
      data-method="POST"
      data-success-message="ส่งข้อความสำเร็จ!"
      data-success-reset="true">

  <div class="form-group">
    <label>ชื่อ</label>
    <input type="text" name="name" required>
  </div>

  <div class="form-group">
    <label>อีเมล</label>
    <input type="email" name="email" required>
  </div>

  <div class="form-group">
    <label>ข้อความ</label>
    <textarea name="message" required minlength="10"></textarea>
  </div>

  <button type="submit">ส่ง</button>
</form>

Edit Form

<form data-form="user-edit"
      data-action="/api/users/{{id}}"
      data-method="PUT"
      data-success-redirect="/users"
      data-confirm="ยืนยันการบันทึก?">

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

  <button type="submit">บันทึก</button>
</form>

Search Form พร้อมแบ่งหน้าอัตโนมัติ

<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="คำค้นหา">
  <select name="status">
    <option value="">ทุกสถานะ</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">กรอง</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">อัพโหลด</button>
</form>

With Custom Handler

form:submitting ถูกส่งผ่าน EventManager.emit() ผู้ฟังจึงได้แค่ สังเกต
การส่งฟอร์ม แต่ ยกเลิกไม่ได้ เพราะไม่มี DOM event ให้เรียก preventDefault():

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

ถ้าต้องการเข้าคุมการส่งฟอร์มเองทั้งหมด ให้ไม่ต้องใส่ data-form ที่อีลิเมนต์นั้น
แล้วจัดการ submit event ปกติเอง:

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: ' ⏳';
}

ข้อควรระวัง

⚠️ 1. ต้องมี name Attribute

<!-- ❌ ไม่มี name -->
<input type="text" id="username">

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

⚠️ 2. Button type

<!-- ❌ Default สามารถ submit ได้ -->
<button>Click</button>

<!-- ✅ ระบุ type -->
<button type="submit">Submit</button>
<button type="button">Cancel</button>

เอกสารที่เกี่ยวข้อง

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