Giới thiệu

Lấy các biểu mẫu động với các bản 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 bản gử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ư là trình 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ế:

Không có Mô-đun Forms (thủ công):
- Xây dựng HTML/xác thực biểu mẫu thủ công ❌
- Thiết lập backend để lưu trữ các bản gửi ❌
- Tạo bảng cơ sở dữ liệu ❌
- Xây dựng bảng điều khiển quản trị để xem phản hồi ❌
- Viết mã thông báo email ❌

Với Mô-đun Forms (tự động):
- Tạo biểu mẫu trong bảng điều khiển quản trị ✅
- Lấy cấu trúc biểu mẫu qua API ✅
- Gửi dữ liệu → Tự động lưu ✅
- Xem phản hồi trong bảng điều khiển ✅
- Thông báo email tự động ✅

✨ 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, ô 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)
Bản 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. Tạo biểu mẫu trong quản trị OneEntry
   ↓
2. Định nghĩa các trường (tên, email, tin nhắn, v.v.)
   ↓
3. Thiết lập các quy tắc xác thực
   ↓
4. Lấy cấu trúc biểu mẫu qua SDK
   ↓
5. Hiển thị biểu mẫu trong ứng dụng của bạn
   ↓
6. Người dùng điền biểu mẫu
   ↓
7. Gửi dữ liệu đến OneEntry
   ↓
8. Xác thực diễn ra
   ↓
9. Dữ liệu được lưu trữ trong cơ sở dữ liệu
   ↓
10. Thông báo được gửi (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	Ô kiểm đơn hoặc nhiều	Thỏa thuận đ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",   // Định danh duy nhất
  localizeInfos: {
    title: "Liên hệ với chúng tôi",    // Tiêu đề biểu mẫu
    description: "Liên hệ với chúng tôi" // Mô tả biểu mẫu
  },
  fields: [   // Các trường biểu mẫu
    {
      marker: "name",
      type: "text",
      localizeInfos: { title: "Tên" },
      isRequired: true,
      validation: { minLength: 2, maxLength: 50 }
    },
  ],
  statusId: 1,                 // 1 = hoạt động, 0 = nháp
  isActive: true,              // Biểu mẫu có được kích hoạt không
  successMessage: "Cảm ơn bạn!" // Thông điệp sau khi gửi
}

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, // Phải được điền
  "validation": {
    "format": "email",  // Phải là email hợp lệ
    "minLength": 5,     // Tối thiểu 5 ký tự
    "maxLength": 100,   // Tối đa 100 ký tự
    "pattern": "^[a-z0-9]+@[a-z]+\\.[a-z]{2,}$"  // Biểu thức chính quy tùy chỉnh
  }
}

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 - Biểu thức chính quy 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 marker	Lấy biểu mẫu cụ thể trong mã

Lưu ý: Để tạo/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 các 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 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 các biểu mẫu.

Để tạo/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 làm đ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 các marker để tham chiếu các biểu mẫu (không phải ID)
Xác thực dữ liệu trên cả 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 điệp 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ông tin thêm 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 bản gử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

Giới thiệ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 các 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​