Giới thiệu

Tạo các khối nội dung có thể tái sử dụng được sử dụng trên nhiều trang khác nhau.

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

Mô-đun Blocks cho phép bạn sử dụng các thành phần nội dung tái sử dụng (khối) chứa các tập hợp thuộc tính và có thể được sử dụng trên nhiều trang và trang sản phẩm - như tiêu đề, chân trang, banner, đánh giá, hoặc bất kỳ nội dung nào lặp lại.

Hãy nghĩ về nó như những viên gạch LEGO cho trang web của bạn - bạn tạo một khối một lần, và tái sử dụng nó ở mọi nơi bạn cần. Thay đổi khối một lần, và nó sẽ tự động cập nhật ở mọi nơi.

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

Hãy tưởng tượng bạn đang xây dựng một trang web với:

• 🔝 Tiêu đề - logo, menu điều hướng (giống nhau trên mọi trang)
• 🔽 Chân trang - thông tin liên hệ, liên kết mạng xã hội (giống nhau trên mọi trang)
• 📢 Banner khuyến mãi - ưu đãi đặc biệt (xuất hiện trên nhiều trang)
• ⭐ Đánh giá - nhận xét của khách hàng (được tái sử dụng ở những nơi khác nhau)
• 📞 Mẫu liên hệ - xuất hiện trên nhiều trang

Thay vì sao chép nội dung này vào mỗi trang:

• ✅ Tạo một lần dưới dạng một Khối
• ✅ Chèn khối vào bất cứ nơi nào bạn cần
• ✅ Cập nhật ở một nơi → thay đổi tự động ở mọi nơi
• ✅ Giữ cho nội dung của bạn DRY (Không lặp lại)

Ví dụ thực tế:

Không có Blocks (sao chép-dán):

• Cập nhật chân trang → Chỉnh sửa 50 trang thủ công ❌
• Thêm liên kết mạng xã hội → Cập nhật ở mọi nơi ❌
• Nội dung không nhất quán trên các trang ❌

Với Blocks (có thể tái sử dụng):

• Cập nhật khối chân trang → Thay đổi trên tất cả 50 trang ngay lập tức ✅
• Thêm liên kết mạng xã hội → Cập nhật một lần ✅
• Luôn nhất quán ✅

✨ Khái niệm chính

Khối là gì?

Một khối là một thành phần nội dung có thể tái sử dụng chứa:

• Nội dung - Văn bản, hình ảnh, liên kết, bất kỳ dữ liệu nào
• Thuộc tính - Các trường tùy chỉnh bạn định nghĩa
• Đánh dấu - Định danh duy nhất để tham chiếu
• Trạng thái - Hoạt động, nháp, đã lưu trữ

Khả năng tái sử dụng của Khối

Các khối có thể:

• ✅ Được sử dụng trên nhiều trang và nếu các khối được cập nhật, chúng sẽ được cập nhật ở mọi nơi
• ✅ Được địa phương hóa (nội dung khác nhau theo ngôn ngữ)

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

Thực hành tốt nhất: Luôn sử dụng đánh dấu trong mã của bạn (chúng không bao giờ thay đổi).

Cấu trúc Khối

Mỗi khối có các trường chính này:

{
  id: 3, // unique ID
  localizeInfos: { // block localized data
    title: 'Block', // block localized title
  },
  version: 0, // block version
  position: 1, // block position in array of blocks
  identifier: 'block', // block identifier
  type: 'common_block', // block type
  templateIdentifier: null, // template identifier
  isVisible: true, // visibility
  attributeValues: {}, // block attributes
}

Thuộc tính Tùy chỉnh

Các khối sử dụng AttributesSets cho các trường tùy chỉnh:

Ví dụ:

• Khối chân trang: văn bản bản quyền, liên kết mạng xã hội, thông tin liên hệ
• Banner chính: tiêu đề, tiêu đề phụ, nút CTA, hình ảnh nền
• Đánh giá: tên tác giả, ảnh, trích dẫn, đánh giá
• Mẫu liên hệ: cấu hình các trường, văn bản nút gửi

Tìm hiểu thêm: Xem AttributesSets Module

---

📊 Bảng tham khảo nhanh - Các phương thức phổ biến

Phương thức	Chức năng	Khi nào sử dụng
getBlocks()	Lấy tất cả các khối (phân trang, lọc)	Liệt kê tất cả các khối có sẵn
getBlockByMarker()	Lấy khối theo đánh dấu	Lấy khối cụ thể trong mã
searchBlock()	Tìm kiếm các khối	Lấy các khối

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

Sự khác biệt giữa Blocks và Pages là gì?

• Pages/Product Pages - Các trang hoàn toàn tự chứa với URL (ví dụ: /about) mà bạn có thể thêm các khối và các thành phần trang khác có thể được tái sử dụng trên nhiều trang.
• Blocks - Các thành phần có thể tái sử dụng được chèn vào các trang (ví dụ, chân trang)

Hãy nghĩ về nó như:

• Trang = Tài liệu đầy đủ
• Khối = Đoạn văn bạn tái sử dụng trong nhiều tài liệu

---

Làm thế nào để tôi cập nhật nội dung của một khối?

Cập nhật nó trong OneEntry bảng điều khiển quản trị:

1. Đi đến phần Blocks
2. Tìm khối của bạn (ví dụ, "Chân trang")
3. Chỉnh sửa thuộc tính
4. Lưu

Tất cả các trang sử dụng khối đó sẽ tự động cập nhật! ✨

---

Tôi nên tạo nhiều khối nhỏ hay ít khối lớn?

Nhiều khối nhỏ là tốt hơn:

✅ Tốt (nhỏ, tập trung):

- header_logo
- header_navigation
- footer_copyright
- footer_social_links

❌ Tránh (quá lớn):

- entire_page_layout (contains everything)

Tại sao? Các khối nhỏ dễ tái sử dụng và bảo trì hơn.

---

Làm thế nào để tôi hiển thị/ẩn các khối một cách có điều kiện?

Kiểm tra trường isVisible

---

Tôi có thể tạo các khối một cách động qua API không?

SDK là chỉ đọc. Để tạo các khối, hãy sử dụng bảng điều khiển quản trị OneEntry.

---

Làm thế nào để tôi xử lý các khối bị thiếu một cách nhẹ nhàng?

Luôn sử dụng try/catch

---

💡 Ghi chú quan trọng

Thực hành tốt nhất về Đánh dấu Khối

✅ Tên đánh dấu tốt:

• Mô tả: global_footer, homepage_hero
• Sử dụng dấu gạch dưới: contact_form
• Chữ thường: promo_banner
• Chỉ định phạm vi: global_header so với blog_header

❌ Tên đánh dấu xấu:

• Chung chung: block1, content
• Khoảng trắng: my block
• Trộn lẫn chữ hoa chữ thường: MyBlock, ProMoBanner

Bộ nhớ đệm Khối

Các khối thay đổi hiếm khi → hãy lưu chúng vào bộ nhớ đệm!

🎓 Thực hành tốt nhất

• Tạo các khối nhỏ, tập trung (trách nhiệm đơn lẻ)
• Sử dụng các đánh dấu mô tả (footer, không phải block1)
• Lưu các khối vào bộ nhớ đệm để giảm số lần gọi API
• Xử lý các khối bị thiếu một cách nhẹ nhàng (try/catch)
• Tài liệu hóa mục đích của từng khối
• Giữ cấu trúc khối nhất quán
• Kiểm tra các thay đổi khối trước khi xuất bản
• Sử dụng statusId để xem trước các thay đổi

---

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

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

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

---

🔗 Tài liệu liên quan

• Pages Module - Quản lý các trang sử dụng khối
• AttributesSets Module - Định nghĩa thuộc tính khối
• Products Module - Sử dụng khối trong các trang sản phẩm

---