Giới thiệu

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

Mô-đun Templates cho phép bạn thay đổi cấu trúc và giao diện của dự án mà không cần thay đổi mã nguồn. Templates cho phép bạn quản lý các thành phần thông qua Nền tảng OneEntry trong khi vẫn duy trì các tùy chọn thiết kế và hành vi linh hoạt.

Templates hoạt động bằng cách cho phép bạn mô tả các thành phần trong mã dự án của bạn, sau đó gán chúng với các template được tạo ra bởi nền tảng. Sự tách biệt này cho phép chuyển đổi giữa các triển khai template khác nhau để ảnh hưởng đến cách các thực thể hoạt động.

Hãy coi nó như một bộ cấu hình hệ thống thiết kế của bạn - bạn tạo các template trong bảng điều khiển quản trị OneEntry (Cài đặt > Templates), gán các thành phần của bạn với những template này, và mô-đun này sẽ lấy các cấu hình đó để ứng dụng của bạn có thể hiển thị nội dung một cách động với kiểu dáng nhất quán.

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

Mỗi ứng dụng cần có cách trình bày nội dung nhất quán:

🖼️ Template Hình ảnh - Kích thước và cắt hình đã định nghĩa (hình thu nhỏ, hình chính, hình ảnh trong bộ sưu tập)
📄 Template Trang - Cấu hình bố cục trang (bài viết blog, trang đích)
🧱 Template Khối - Hình thức khối nội dung (thẻ, banner, phần)
🛍️ Template Sản phẩm - Định dạng hiển thị sản phẩm (lưới, danh sách, chi tiết)
🎨 Thiết kế đáp ứng - Kích thước khác nhau cho di động, máy tính bảng, máy tính để bàn
♻️ Cấu hình tái sử dụng - Định nghĩa một lần, sử dụng ở mọi nơi

Vấn đề với logic hiển thị mã cứng:

Vấn đề:

🔒 Không nhất quán - Kích thước khác nhau ở các nơi khác nhau
🎨 Khó bảo trì - Thay đổi yêu cầu chỉnh sửa nhiều tệp
📱 Không đáp ứng - Kích thước cố định không thích ứng
♻️ Không tái sử dụng - Mã trùng lặp ở khắp nơi

Giải pháp từ Templates:

Lợi ích:

🔒 Nhất quán - Cùng một template được sử dụng ở mọi nơi
🎨 Dễ bảo trì - Thay đổi trong bảng điều khiển quản trị, áp dụng ở mọi nơi
📱 Đáp ứng - Các template khác nhau cho các màn hình khác nhau
♻️ Có thể tái sử dụng - Định nghĩa một lần, sử dụng trong toàn bộ ứng dụng

✨ Khái niệm chính

Template là gì?

Một Template là một cấu hình hiển thị xác định cách nội dung nên xuất hiện:

Loại Template - Template hình ảnh, trang, khối, sản phẩm
Kích thước - Chiều rộng, chiều cao, tỷ lệ khung hình
Cài đặt cắt - Cách cắt hình ảnh (giữa, trên, dưới)
Định dạng - Định dạng hình ảnh (JPEG, PNG, WebP)
Chất lượng - Chất lượng nén
Đánh dấu - Định danh duy nhất cho tham chiếu mã

Cấu trúc Template

Mỗi template có cấu trúc như sau:

{
  id: 1,                                    // Định danh duy nhất
  title: "Hình thu nhỏ sản phẩm",           // Tên template (không duy nhất)
  identifier: "product_thumbnail",          // Đánh dấu template (duy nhất)
  generalTypeId: 1,                         // Tham chiếu ID loại
  version: 0,                               // Số phiên bản
  attributeSetIdentifier: null,             // Tập thuộc tính liên kết
  localizeInfos: {                          // Thông tin địa phương hóa
    en_US: {
      title: "Hình thu nhỏ sản phẩm",
      description: "Hình ảnh sản phẩm nhỏ"
    }
  },
  attributeValues: {},                      // Dữ liệu thuộc tính bổ sung
  isActive: true,                           // Trạng thái hoạt động
  createdAt: "2024-01-15T10:00:00Z",
  updatedAt: "2024-01-15T10:00:00Z"
}

Các trường chính:

identifier - Đánh dấu duy nhất cho tham chiếu template (sử dụng cái này, không phải ID)
title - Tên template hiển thị trong bảng điều khiển quản trị
generalTypeId - Danh mục thực thể mà template áp dụng
attributeSetIdentifier - Tập thuộc tính liên kết tùy chọn

Các loại Template

Templates được tổ chức theo loại thực thể và hỗ trợ các danh mục sau:

Loại Template	Danh mục Thực thể	Ví dụ Trường hợp Sử dụng
Khối Sản phẩm	`forCatalogProducts`	Lưới sản phẩm, danh sách sản phẩm, sản phẩm nổi bật
Khối Thông thường	`forOneBlock`	Thẻ nội dung, banner, phần, widget
Trang Lỗi	`forErrorPages`	Trang 404, trang 500, bố cục lỗi tùy chỉnh
Trang Thông thường	`forOnePage`	Bài viết blog, trang đích, trang giới thiệu
Trang Sản phẩm	`forOneProduct`	Chi tiết sản phẩm, so sánh sản phẩm
Trang Danh mục	`forCatalogPage`	Danh sách danh mục, kết quả tìm kiếm
Biểu mẫu	`forForm`	Biểu mẫu liên hệ, biểu mẫu đăng ký, khảo sát
Đơn hàng	`forOrder`	Xác nhận đơn hàng, lịch sử đơn hàng

Các Template Hình ảnh Thông thường

Template	Kích thước	Cắt	Trường hợp Sử dụng
Hình thu nhỏ	150×150	Giữa	Hình ảnh xem trước nhỏ
Hình thẻ	300×200	Giữa	Thẻ sản phẩm, thẻ blog
Hình chính	1920×1080	Giữa	Banner toàn chiều rộng
Hình ảnh bộ sưu tập	800×600	Giữa	Bộ sưu tập hình ảnh
Hình đại diện	100×100	Giữa	Hình ảnh hồ sơ người dùng
Hình chính di động	768×432	Giữa	Banner tối ưu hóa cho di động

Quy trình Cấu hình Template

1. Tạo templates trong bảng điều khiển quản trị
   (Định nghĩa kích thước, cắt, định dạng)
   ↓
2. Lấy templates qua SDK
   (Templates.getTemplates())
   ↓
3. Áp dụng cấu hình template
   (Sử dụng kích thước trong việc hiển thị hình ảnh)
   ↓
4. Hình ảnh tự động được tối ưu hóa
   (OneEntry CDN phục vụ kích thước chính xác)
   ↓
5. Hiển thị nhất quán ở mọi nơi
   (Cùng một template = cùng một giao diện)

Tại sao nên sử dụng mô-đun Templates?

Lợi ích	Mô tả
Thiết kế Nhất quán	Cùng một template được sử dụng trong toàn bộ ứng dụng
Bảo trì Dễ dàng	Thay đổi template trong quản trị, cập nhật ở mọi nơi
Tối ưu hóa Hình ảnh	Tự động thay đổi kích thước và nén
Thiết kế Đáp ứng	Các template khác nhau cho các màn hình khác nhau
Tích hợp CDN	Phân phối hình ảnh tối ưu
Cấu hình Tái sử dụng	Định nghĩa một lần, sử dụng ở mọi nơi

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

Templates được tạo trong Bảng điều khiển Quản trị

Bạn không thể tạo templates qua SDK - chúng được tạo trong bảng điều khiển quản trị OneEntry:

Bảng điều khiển Quản trị OneEntry → Cài đặt → Templates → Tạo Template → Đặt Tên/Đánh dấu/Loại → Lưu

Quy trình Tạo:

Cung cấp một Tên (định danh không duy nhất)
Cung cấp một Đánh dấu (định danh duy nhất)
Chọn một Loại (danh mục thực thể mà template áp dụng)
Nhấp "Tạo" để hoàn tất

Các hoạt động Quản lý:

Cấu hình - Nhấp vào biểu tượng bánh răng để chỉnh sửa tên, đánh dấu hoặc loại
Xóa - Chọn template và nhấp vào biểu tượng xóa, sau đó xác nhận việc xóa

SDK chỉ dùng để lấy cấu hình template, không phải để tạo chúng.

Xác định Template

Ba cách để xác định templates:

Phương pháp	Khi nào sử dụng	Ví dụ
Theo Loại	Tham chiếu trong mã (thực hành tốt nhất)	`product_thumbnail`, `hero_banner`
Theo Đánh dấu	Tham chiếu trong mã (thực hành tốt nhất)	`product_thumbnail`, `hero_banner`
Liệt kê Tất cả	Hiển thị các template có sẵn	`getTemplates()`

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).

Tích hợp CDN cho Template Hình ảnh

OneEntry tự động tối ưu hóa hình ảnh dựa trên các template.

Thiết kế Đáp ứng với Templates

Tạo các template khác nhau cho các kích thước màn hình khác nhau.

Cấu trúc Template:

interface ITemplateEntity {
  id: number;                        // Định danh duy nhất
  title: string;                     // Tên template (không duy nhất)
  identifier: string;                // Đánh dấu template (duy nhất)
  generalTypeId: number;             // Tham chiếu ID loại
  version: number;                   // Số phiên bản
  attributeSetIdentifier: string | null;  // Tập thuộc tính liên kết
  localizeInfos: {                   // Thông tin địa phương hóa
    [langCode: string]: {
      title: string;
      description?: string;
    };
  };
  attributeValues: any;              // Dữ liệu thuộc tính bổ sung
  isActive: boolean;                 // Trạng thái hoạt động
}

Các loại Template có sẵn:

forCatalogProducts - Khối sản phẩm
forOneBlock - Khối thông thường
forErrorPages - Trang lỗi
forOnePage - Trang thông thường
forOneProduct - Trang sản phẩm
forCatalogPage - Trang danh mục
forForm - Biểu mẫu
forOrder - Đơn hàng

💡 Ghi chú Quan trọng

Templates được tạo trong Bảng điều khiển Quản trị

Nhớ: SDK chỉ dùng để lấy cấu hình template, không phải để tạo templates.

Để tạo/chỉnh sửa templates: Sử dụng Bảng điều khiển Quản trị OneEntry.

Cách Templates Hoạt động

Templates cho phép quản lý linh hoạt các thành phần bằng cách tách biệt cấu trúc khỏi mã:

Mô tả các thành phần trong mã dự án của bạn
Gán các thành phần với các template được tạo ra bởi nền tảng
Chuyển đổi templates để thay đổi cách các thực thể hoạt động
Cập nhật giao diện mà không cần sửa đổi mã nguồn

Sự tách biệt này cho phép nhiều biến thể thiết kế và chức năng mà không cần thay đổi mã.

Tối ưu hóa Hình ảnh

OneEntry CDN tự động tối ưu hóa hình ảnh dựa trên cài đặt template:

Thay đổi kích thước tự động
Chuyển đổi định dạng (JPEG, PNG, WebP)
Nén
Cắt
Lưu trữ

Bạn chỉ cần tham chiếu đến đánh dấu template:

<img src={`${image.url}?template=thumbnail`} />

Templates Đáp ứng

Tạo các template riêng biệt cho các thiết bị khác nhau:

Templates di động (rộng 768px hoặc ít hơn)
Templates máy tính bảng (rộng 1024px)
Templates máy tính để bàn (rộng 1920px)

Sử dụng với phần tử <picture> cho hình ảnh đáp ứng.

Bộ nhớ Cache Template

Templates hiếm khi thay đổi - thực hiện bộ nhớ cache:

Frontend: localStorage, sessionStorage
Backend: Redis, bộ nhớ cache
TTL: 1 giờ được khuyến nghị

📊 Bảng Tham khảo Nhanh

Phương pháp	Mô tả	Trường hợp Sử dụng
getAllTemplates()	Lấy tất cả templates được nhóm theo loại	Liệt kê tất cả các template có sẵn
getTemplateByType()	Lấy templates theo loại thực thể	Lấy templates cho loại thực thể cụ thể
getTemplateByMarker()	Lấy template theo đánh dấu	Lấy cấu hình template cụ thể

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

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

Templates cấu hình hiển thị nội dung chung (trang, khối, sản phẩm), trong khi TemplatePreviews xử lý cụ thể hình ảnh thuộc tính sản phẩm (mẫu màu, mẫu vật liệu). Sử dụng Templates cho nội dung chính, TemplatePreviews cho hình ảnh thuộc tính.

Làm thế nào để áp dụng một template cho URL hình ảnh?

Thêm ?template=marker vào URL hình ảnh, trong đó marker là định danh template. OneEntry CDN tự động phục vụ hình ảnh tối ưu hóa dựa trên cấu hình template (kích thước, cắt, định dạng).

Tôi có thể tạo các template khác nhau cho di động và máy tính để bàn không?

Có! Tạo các template riêng biệt với kích thước phù hợp cho mỗi thiết bị (ví dụ: hero_mobile, hero_desktop). Sử dụng các kỹ thuật thiết kế đáp ứng hoặc các phần tử <picture> để tải template đúng dựa trên kích thước màn hình.

Điều gì xảy ra nếu tôi tham chiếu một template không tồn tại?

Hình ảnh sẽ tải ở kích thước gốc mà không có tối ưu hóa template. Luôn xác minh rằng các đánh dấu template tồn tại và xử lý các template bị thiếu một cách hợp lý với kích thước dự phòng.

Làm thế nào để cập nhật một template mà không ảnh hưởng đến sản xuất?

Templates là cấu hình, không phải mã. Các thay đổi trong bảng điều khiển quản trị sẽ áp dụng ngay lập tức. Kiểm tra các thay đổi template trong môi trường staging trước, sau đó cập nhật các template sản xuất khi đã được xác minh.

Tôi nên sử dụng loại template nào cho nội dung của mình?

Chọn dựa trên loại thực thể: forOnePage cho các trang tiêu chuẩn, forCatalogProducts cho danh sách sản phẩm, forOneBlock cho các khối nội dung, forOneProduct cho chi tiết sản phẩm. Khớp loại template với danh mục nội dung của bạn.

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

Sử dụng đánh dấu, không phải ID - Đánh dấu ổn định qua các môi trường
Cache templates - Giảm số lần gọi API cho dữ liệu hiếm khi thay đổi
Tạo các template đáp ứng - Kích thước khác nhau cho các màn hình khác nhau
Sử dụng định dạng WebP - Nén tốt hơn so với JPEG/PNG
Định nghĩa cài đặt chất lượng - Cân bằng giữa chất lượng và kích thước tệp
Sử dụng tham số template CDN - ?template=marker để tối ưu hóa
Tạo các đánh dấu ngữ nghĩa - product_thumbnail, không phải img_1
Tài liệu sử dụng template - Giải thích mục đích của mỗi template

Thêm thông tin về templates trong bảng điều khiển quản trị OneEntry: https://doc.oneentry.cloudhttps://doc.oneentry.cloud/docs/templates/content_templates/

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

Mô-đun Templates cấu hình hiển thị nội dung trong ứng dụng của bạn.

Một số templates ảnh hưởng đến hình ảnh được lưu trữ trong OneEntry, trong khi những cái khác xác định giao diện của các thực thể như khối, trang và sản phẩm.


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

🔗 Tài liệu Liên quan

Bảng điều khiển Quản trị OneEntry - Templates Nội dung - Tài liệu chính thức của bảng điều khiển quản trị
Mô-đun TemplatePreviews - Xem trước các template cho hình ảnh thuộc tính
Mô-đun Sản phẩm - Sản phẩm sử dụng các template sản phẩm
Mô-đun Trang - Các trang sử dụng các template trang
Mô-đun Khối - Các khối sử dụng các template khối
Mô-đun Biểu mẫu - Các biểu mẫu sử dụng các template biểu mẫu
Thực hành Tối ưu hóa Hình ảnh

Giới thiệu

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

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

✨ Khái niệm chính​

Template là gì?​

Cấu trúc Template​

Các loại Template​

Các Template Hình ảnh Thông thường​

Quy trình Cấu hình Template​

Tại sao nên sử dụng mô-đun Templates?​

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

Templates được tạo trong Bảng điều khiển Quản trị​

Xác định Template​

Tích hợp CDN cho Template Hình ảnh​

Thiết kế Đáp ứng với Templates​

💡 Ghi chú Quan trọng​

Templates được tạo trong Bảng điều khiển Quản trị​

Cách Templates Hoạt động​

Tối ưu hóa Hình ảnh​

Templates Đáp ứng​

Bộ nhớ Cache Template​

📊 Bảng Tham khảo Nhanh​

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

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

Làm thế nào để áp dụng một template cho URL hình ảnh?​

Tôi có thể tạo các template khác nhau cho di động và máy tính để bàn không?​

Điều gì xảy ra nếu tôi tham chiếu một template không tồn tại?​

Làm thế nào để cập nhật một template mà không ảnh hưởng đến sản xuất?​

Tôi nên sử dụng loại template nào cho nội dung của mình?​

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

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

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

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

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

✨ Khái niệm chính

Template là gì?

Cấu trúc Template

Các loại Template

Các Template Hình ảnh Thông thường

Quy trình Cấu hình Template

Tại sao nên sử dụng mô-đun Templates?

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

Templates được tạo trong Bảng điều khiển Quản trị

Xác định Template

Tích hợp CDN cho Template Hình ảnh

Thiết kế Đáp ứng với Templates

💡 Ghi chú Quan trọng

Templates được tạo trong Bảng điều khiển Quản trị

Cách Templates Hoạt động

Tối ưu hóa Hình ảnh

Templates Đáp ứng

Bộ nhớ Cache Template

📊 Bảng Tham khảo Nhanh

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

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

Làm thế nào để áp dụng một template cho URL hình ảnh?

Tôi có thể tạo các template khác nhau cho di động và máy tính để bàn không?

Điều gì xảy ra nếu tôi tham chiếu một template không tồn tại?

Làm thế nào để cập nhật một template mà không ảnh hưởng đến sản xuất?

Tôi nên sử dụng loại template nào cho nội dung của mình?

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

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

🔗 Tài liệu Liên quan