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 - 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ó ở bất cứ đâu 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 ở nhiều nơi)
📞 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 ở bất cứ đâu 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 (Don't Repeat Yourself)

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 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ối vs Trang

Tính năng	Trang	Khối
Mục đích	Nội dung trang hoàn chỉnh	Thành phần tái sử dụng
URL	Có URL riêng (`/about`)	Không có URL (được nhúng)
Cách sử dụng	Được xem trực tiếp	Được chèn vào các trang
Ví dụ	Trang Giới thiệu	Chân trang, Tiêu đề

Sự khác biệt chính: Các trang là điểm đến, các khối là các khối xây dựng.

Các loại khối phổ biến

Các khối điển hình bạn có thể tạo:

Loại khối	Nội dung ví dụ	Nơi sử dụng
Tiêu đề	Logo, menu điều hướng, tìm kiếm	Mỗi trang
Chân trang	Thông tin liên hệ, liên kết, bản quyền	Mỗi trang
Banner Hero	Hình ảnh lớn + nút CTA	Trang chính, trang đích
Đánh giá	Nhận xét của khách hàng	Nhiều trang
Mẫu liên hệ	Mẫu email	Trang liên hệ, modal
Banner khuyến mãi	Thông báo ưu đãi đặc biệt	Các trang đã chọn
Liên kết mạng xã hội	Biểu tượng Facebook, Twitter	Chân trang, thanh bên
Đăng ký bản tin	Hộp đăng ký email	Chân trang, blog

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
✅ Cập nhật một lần, phản ánh ở 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

Xác định Khối

Ba cách để xác định các khối:

Phương pháp	Khi nào sử dụng	Ví dụ
Liệt kê tất cả	Bảng điều khiển quản trị, bộ chọn khối	`getBlocks()`
Theo Đánh dấu	Tham chiếu trong mã (thực hành tốt nhất)	`footer`, `header`, `promo_banner`
Tìm kiếm khối	Tham chiếu nội bộ	`searchBlock('foo')`

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 sau:

{
  id: 3, // ID duy nhất
  localizeInfos: { // dữ liệu khối đã địa phương hóa
    title: 'Block', // tiêu đề khối đã địa phương hóa
  },
  version: 0, // phiên bản khối
  position: 1, // vị trí khối trong mảng các khối
  identifier: 'block', // định danh khối
  type: 'common_block', // loại khối
  templateIdentifier: null, // định danh mẫu
  isVisible: true, // khả năng hiển thị
  attributeValues: {}, // thuộc tính của khối
}

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 Hero: 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 Pháp Thông Dụng

Phương pháp	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 - Các trang hoàn chỉnh độc lập với URL (ví dụ: /about)
Blocks - Các thành phần 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 bảng điều khiển quản trị OneEntry:

Đi đến phần Blocks
Tìm khối của bạn (ví dụ: "Chân trang")
Chỉnh sửa thuộc tính
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 (chứa mọi thứ)

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

Tôi có thể sử dụng cùng một khối nhiều lần trên một trang không?

Có! Lấy một lần, hiển thị nhiều lầ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 statusId và 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 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 khéo léo?

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ỉ ra phạm vi: global_header vs blog_header

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

Chung chung: block1, content
Khoảng trắng: my block
Trộn lẫn chữ: 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 khéo léo (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

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

Giới thiệu

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

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

✨ Khái niệm chính​

Khối là gì?​

Khối vs Trang​

Các loại khối phổ biến​

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

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

Xác định Khối​

Cấu trúc Khối​

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

📊 Bảng Tham Khảo Nhanh - Các Phương Pháp Thông Dụng​

❓ Câu Hỏi Thường Gặp (FAQ)​

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

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

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

Tôi có thể sử dụng cùng một khối nhiều lần trên một trang không?​

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

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

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

💡 Ghi chú quan trọng​

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

Bộ nhớ đệm Khối​

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

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

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