Giới thiệu

Lấy các biểu mẫu động với việc gửi và thu thập dữ liệu theo thời gian thực.

🎯 Mô-đun này làm gì?

Mô-đun Forms cho phép bạn lấy các biểu mẫu - biểu mẫu liên hệ, khảo sát, đăng ký, biểu mẫu phản hồi - và thu thập các phản hồi của người dùng với xác thực, tải tệp và thông báo tự động.

Hãy coi nó như một công cụ tạo biểu mẫu của bạn - bạn tạo các biểu mẫu trong bảng điều khiển quản trị OneEntry, hiển thị chúng trong ứng dụng của bạn và tự động thu thập phản hồi.

📖 Giải thích đơn giản

Hãy tưởng tượng bạn cần thu thập thông tin từ người dùng:

📞 Biểu mẫu liên hệ - tên, email, tin nhắn, điện thoại
📋 Khảo sát - câu hỏi trắc nghiệm, đánh giá
👤 Biểu mẫu đăng ký - thông tin người dùng, sở thích
💼 Đơn xin việc - tải lên sơ yếu lý lịch, thư xin việc
📝 Biểu mẫu phản hồi - đánh giá, nhận xét, gợi ý
🎟️ Đăng ký sự kiện - thông tin người tham dự, lựa chọn vé

Thay vì xây dựng các biểu mẫu từ đầu:

✅ Tạo biểu mẫu trong bảng điều khiển quản trị OneEntry (kéo và thả các trường)
✅ Lấy cấu trúc biểu mẫu một cách động
✅ Gửi dữ liệu đến OneEntry (lưu trữ tự động)
✅ Xác thực các trường (bắt buộc, định dạng email, loại tệp)
✅ Nhận thông báo khi các biểu mẫu được gửi
✅ Xem phản hồi trong bảng điều khiển quản trị

Ví dụ thực tế:

Without Forms Module (manual):
- Build form HTML/validation manually ❌
- Set up backend to store submissions ❌
- Create database tables ❌
- Build admin panel to view responses ❌
- Write email notification code ❌

With Forms Module (automated):
- Create form in admin panel ✅
- Fetch form structure via API ✅
- Submit data → Auto-stored ✅
- View responses in dashboard ✅
- Auto email notifications ✅

✨ Khái niệm chính

Biểu mẫu là gì?

Một biểu mẫu là một cách có cấu trúc để thu thập thông tin từ người dùng:

Trường - Các phần tử đầu vào (văn bản, email, hộp kiểm, tải tệp)
Xác thực - Các quy tắc (bắt buộc, định dạng, độ dài tối thiểu/tối đa)
Gửi - Các phản hồi của người dùng được lưu trữ trong cơ sở dữ liệu
Cấu trúc - Bố cục biểu mẫu được xác định trong OneEntry
Động - Lấy cấu trúc biểu mẫu từ API, hiển thị trong ứng dụng của bạn

Vòng đời của biểu mẫu

1. Create form in OneEntry admin
   ↓
2. Define fields (name, email, message, etc.)
   ↓
3. Set validation rules
   ↓
4. Fetch form structure via SDK
   ↓
5. Render form in your app
   ↓
6. User fills form
   ↓
7. Submit data to OneEntry
   ↓
8. Validation happens
   ↓
9. Data stored in database
   ↓
10. Notifications sent (email, webhook)

Các loại trường biểu mẫu

Các loại trường phổ biến mà bạn có thể sử dụng:

Loại trường	Mô tả	Ví dụ sử dụng
text	Nhập văn bản ngắn	Tên, Tiêu đề, Thành phố
email	Địa chỉ email với xác thực	Email liên hệ
textarea	Văn bản nhiều dòng	Tin nhắn, Nhận xét, Tiểu sử
number	Nhập số	Tuổi, Số lượng, Điện thoại
checkbox	Hộp kiểm đơn hoặc nhiều	Đồng ý điều khoản, Sở thích
radio	Lựa chọn đơn từ các tùy chọn	Giới tính, Kích thước, Kế hoạch
select	Menu thả xuống	Quốc gia, Danh mục, Tình trạng
file	Tải tệp	Sơ yếu lý lịch, Ảnh, Tài liệu
date	Chọn ngày	Ngày sinh, Ngày sự kiện

📋 Những điều bạn cần biết

Cấu trúc biểu mẫu

Mỗi biểu mẫu có các trường chính này:

{
  id: 123,
  marker: "contact_form",   // Unique identifier
  localizeInfos: {
    title: "Contact Us",    // Form title
    description: "Get in touch" // Form description
  },
  fields: [   // Form fields
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Name" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = active, 0 = draft
  isActive: true,              // Is form enabled
  successMessage: "Thank you!" // Message after submission
}

Xác thực trường

Mỗi trường có thể có các quy tắc xác thực:

{
  "marker": "email",
  "type": "email",
  "isRequired": true, // Must be filled
  "validation": {
    "format": "email",  // Must be valid email
    "minLength": 5,     // Min 5 characters
    "maxLength": 100,   // Max 100 characters
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Custom regex
  }
}

Các quy tắc xác thực phổ biến:

isRequired - Trường phải được điền
minLength - Độ dài văn bản tối thiểu
maxLength - Độ dài văn bản tối đa
format - Định dạng email, điện thoại, URL
pattern - Mẫu regex tùy chỉnh
min / max - Phạm vi số
fileTypes - Các định dạng tệp được phép
maxFileSize - Kích thước tệp tối đa

📊 Bảng tham khảo nhanh - Phương thức

Phương thức	Chức năng	Khi nào sử dụng
getAllForms()	Lấy tất cả các biểu mẫu (phân trang)	Liệt kê tất cả các biểu mẫu có sẵn
getFormByMarker()	Lấy biểu mẫu theo mã đánh dấu	Lấy biểu mẫu cụ thể trong mã

Lưu ý: Để tạo/chỉnh sửa biểu mẫu, hãy sử dụng bảng điều khiển quản trị OneEntry. SDK được sử dụng để lấy biểu mẫu và gửi dữ liệu.

❓ Câu hỏi thường gặp (FAQ)

Làm thế nào để tôi tạo hoặc chỉnh sửa biểu mẫu?

Các biểu mẫu được tạo trong bảng điều khiển quản trị OneEntry:

Đăng nhập vào quản trị OneEntry
Đi đến phần Biểu mẫu
Tạo biểu mẫu mới hoặc chỉnh sửa biểu mẫu hiện có
Thêm các trường (kéo và thả)
Cấu hình các quy tắc xác thực
Kích hoạt biểu mẫu

SDK được sử dụng để lấy biểu mẫu và gửi dữ liệu, không phải để tạo biểu mẫu.

Làm thế nào để tôi xác thực dữ liệu biểu mẫu trước khi gửi?

Sử dụng xác thực trình duyệt + kiểm tra thủ công:

Tôi có thể tải tệp lên cùng với biểu mẫu không?

Có! Sử dụng mô-đun FileUploading và thêm file vào trường của bạn:

Tìm hiểu thêm: FormsData Module

Tôi có thể gửi thông báo tùy chỉnh khi biểu mẫu được gửi không?

Có, cấu hình trong bảng điều khiển quản trị OneEntry:

Thông báo qua email cho quản trị viên/người dùng
Thông báo webhook đến máy chủ của bạn
Tích hợp với mô-đun Events

Làm thế nào để tôi xử lý các lỗi gửi biểu mẫu?

Luôn sử dụng try/catch

Các biểu mẫu có thể có các trường điều kiện (hiện/ẩn dựa trên các trường khác) không?

Không trực tiếp trong SDK, nhưng bạn có thể triển khai trong giao diện người dùng của bạn

💡 Lưu ý quan trọng

Các biểu mẫu được tạo trong bảng điều khiển quản trị

Nhớ: SDK được sử dụng để lấy các biểu mẫu và gửi dữ liệu, không phải để tạo biểu mẫu.

Để tạo/chỉnh sửa biểu mẫu: Sử dụng bảng điều khiển quản trị OneEntry hoặc Admin API.

Luôn xác thực dữ liệu

✅ Xác thực phía khách hàng không đủ:

Xác thực trên khách hàng (trải nghiệm người dùng tốt hơn)
Xác thực trên máy chủ (OneEntry tự động thực hiện điều này)

Xử lý tải tệp cẩn thận

✅ Các thực hành tốt nhất cho việc tải tệp:

Xác thực loại tệp trước khi tải lên
Kiểm tra giới hạn kích thước tệp
Hiển thị tiến trình tải lên
Xử lý lỗi tải lên

🎓 Các thực hành tốt nhất

✅ Những điều nên làm:

Sử dụng mã đánh dấu để tham chiếu các biểu mẫu (không phải ID)
Xác thực dữ liệu trên khách hàng và máy chủ
Hiển thị trạng thái tải trong quá trình gửi
Cung cấp thông báo lỗi rõ ràng
Vô hiệu hóa nút gửi sau khi gửi thành công
Xóa biểu mẫu sau khi gửi thành công
Xử lý lỗi tải tệp một cách nhẹ nhàng
Sử dụng try/catch để xử lý lỗi

❌ Những điều không nên làm:

Cứng mã ID biểu mẫu trong mã
Gửi biểu mẫu mà không có xác thực
Bỏ qua xử lý lỗi
Cho phép gửi trùng lặp
Tải lên tệp mà không có xác thực kích thước/loại
Hiển thị lỗi kỹ thuật cho người dùng
Quên cung cấp phản hồi cho người dùng
Bỏ qua trạng thái tải

Thêm thông tin về giao diện người dùng của mô-đun https://doc.oneentry.cloud/docs/forms/introduction

Định nghĩa của mô-đun Forms


const { Forms } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Các ví dụ sử dụng nâng cao có thể được tìm thấy trong Giới thiệu về Forms.

🔗 Tài liệu liên quan

FormsData Module - Xem và quản lý các phản hồi biểu mẫu
Events Module - Thiết lập thông báo tự động khi gửi biểu mẫu
FileUploading Module - Xử lý tải tệp trong các biểu mẫu
Users Module - Quản lý người dùng gửi biểu mẫu

🎯 Mô-đun này làm gì?​

📖 Giải thích đơn giản​

✨ Khái niệm chính​

Biểu mẫu là gì?​

Vòng đời của biểu mẫu​

Các loại trường biểu mẫu​

📋 Những điều bạn cần biết​

Cấu trúc biểu mẫu​

Xác thực trường​

📊 Bảng tham khảo nhanh - Phương thức​

❓ Câu hỏi thường gặp (FAQ)​

Làm thế nào để tôi tạo hoặc chỉnh sửa biểu mẫu?​

Làm thế nào để tôi xác thực dữ liệu biểu mẫu trước khi gửi?​

Tôi có thể tải tệp lên cùng với biểu mẫu không?​

Tôi có thể gửi thông báo tùy chỉnh khi biểu mẫu được gửi không?​

Làm thế nào để tôi xử lý các lỗi gửi biểu mẫu?​

Các biểu mẫu có thể có các trường điều kiện (hiện/ẩn dựa trên các trường khác) không?​

💡 Lưu ý quan trọng​

Các biểu mẫu được tạo trong bảng điều khiển quản trị​

Luôn xác thực dữ liệu​

Xử lý tải tệp cẩn thận​

🎓 Các thực hành tốt nhất​

Định nghĩa của mô-đun Forms​

🔗 Tài liệu liên quan​