Theme Tags

stack & push

Khai báo vị trí bằng stack, bổ sung CSS, script hoặc HTML bằng push / endpush. Engine gom theo ID trong từng lần render và chèn ở bước cuối, kể cả khi push nằm sau stack.

Cú pháp và ví dụ đầy đủ →

include only

Render thành phần. Dùng khả năng hiện có, không tạo alias hoặc triển khai engine trùng chức năng.

include only · thay render

Dùng cú pháp chính thức Lingo; không triển khai alias Liquid.

{% include "blocks/card.html" with title="Áo" only %}

HTML blocks/card.html nhận title, không kế thừa toàn context gọi.

Trường hợp biên và an toàn

Không dynamic path từ input; only để cô lập context. Giới hạn include depth theo profile.

include · thay include

Dùng cú pháp chính thức Lingo; không triển khai alias Liquid.

{% include "blocks/card.html" with title="Áo" only %}

Nội dung partial được render với title.

Trường hợp biên và an toàn

Chặn traversal và vòng include; xử lý thiếu template theo Lingo.

Tiêu chí nghiệm thu

• Kiểm thử ví dụ ở trên cùng đầu vào rỗng, Unicode, sai kiểu và giới hạn đầu ra.
• Khóa hành vi của implementation hiện tại bằng test; không sửa ngữ nghĩa để khớp Liquid.
• Không I/O, truy vấn hoặc thay đổi dữ liệu từ template; dữ liệu commerce chỉ qua resolver có quyền.
• Kiểm thử escaping và profile runtime trước khi công bố cho theme.

Nguồn & quyết định chuyển đổi

Tên tham khảo: render, include. Dùng tên/cú pháp Lingo hoặc helper Skai ghi ở đầu trang, không tạo alias tương thích Liquid.

Nguồn tham khảo Shopify · Quy ước đặc tả Skai

Đối chiếu mã nguồn local: skaiplatform/lingo/filters_builtin.go, tags_*.go, security.go và skaiweb/services/theme_engine/functions.go. Badge “Đang phát triển” biểu thị tài liệu dự kiến, không xác nhận engine đã được triển khai.

section

Render section. Bản thiết kế v0.1 để review trước khi triển khai, chưa phải API phát hành.

Hợp đồng sử dụng

Đặc tả mở rộng Skai; chưa được engine hỗ trợ.

{% section "hero" with settings=hero_settings %}

Render sections/hero.html với cấu hình đã kiểm tra.

Trường hợp biên và an toàn

Đề xuất adapter tái sử dụng luồng sections JSON hiện có, không engine thứ hai. Chỉ key manifest; escape nội dung; không truy vấn DB.

Tiêu chí nghiệm thu

• Kiểm thử ví dụ ở trên cùng đầu vào rỗng, Unicode, sai kiểu và giới hạn đầu ra.
• Sai tham số phải trả lỗi có tên filter/tag; preview hiển thị vị trí lỗi, production không lộ nội bộ.
• Không I/O, truy vấn hoặc thay đổi dữ liệu từ template; dữ liệu commerce chỉ qua resolver có quyền.
• Kiểm thử escaping và profile runtime trước khi công bố cho theme.

Nguồn & quyết định chuyển đổi

Tên tham khảo: section. Hợp đồng và ví dụ là đề xuất riêng cho Skai, không sao chép contract Liquid.

Nguồn tham khảo Shopify · Quy ước đặc tả Skai

Đối chiếu mã nguồn local: skaiplatform/lingo/filters_builtin.go, tags_*.go, security.go và skaiweb/services/theme_engine/functions.go. Badge “Đang phát triển” biểu thị tài liệu dự kiến, không xác nhận engine đã được triển khai.

form() + forms

Tạo khung form. Dùng khả năng hiện có, không tạo alias hoặc triển khai engine trùng chức năng.

Hợp đồng sử dụng

Dùng cú pháp chính thức Lingo; không triển khai alias Liquid.

{{ form("contact") }}

HTML biểu mẫu đã cấu hình bởi runtime.

Trường hợp biên và an toàn

Đã có helper Skai. Không thêm tag form Liquid; xác thực dữ liệu vẫn phải ở server.

Tiêu chí nghiệm thu

• Kiểm thử ví dụ ở trên cùng đầu vào rỗng, Unicode, sai kiểu và giới hạn đầu ra.
• Khóa hành vi của implementation hiện tại bằng test; không sửa ngữ nghĩa để khớp Liquid.
• Không I/O, truy vấn hoặc thay đổi dữ liệu từ template; dữ liệu commerce chỉ qua resolver có quyền.
• Kiểm thử escaping và profile runtime trước khi công bố cho theme.

Nguồn & quyết định chuyển đổi

Tên tham khảo: form. Dùng tên/cú pháp Lingo hoặc helper Skai ghi ở đầu trang, không tạo alias tương thích Liquid.

Nguồn tham khảo Shopify · Quy ước đặc tả Skai

Đối chiếu mã nguồn local: skaiplatform/lingo/filters_builtin.go, tags_*.go, security.go và skaiweb/services/theme_engine/functions.go. Badge “Đang phát triển” biểu thị tài liệu dự kiến, không xác nhận engine đã được triển khai.

paginate

Phân trang dữ liệu. Bản thiết kế v0.1 để review trước khi triển khai, chưa phải API phát hành.

Hợp đồng sử dụng

Đặc tả mở rộng Skai; chưa được engine hỗ trợ.

{% paginate catalog_query by 12 as pagination %}
{% for item in pagination.items %}{{ item.title }}{% endfor %}
{% endpaginate %}

Chỉ một trang tối đa 12 mục; total_pages/current_page do resolver cung cấp.

Trường hợp biên và an toàn

Giới hạn page_size 1–100; page từ request đã parse; query workspace/app bắt buộc. Không slice dữ liệu đã tải hết; không gọi SQL từ template.

Tiêu chí nghiệm thu

• Kiểm thử ví dụ ở trên cùng đầu vào rỗng, Unicode, sai kiểu và giới hạn đầu ra.
• Sai tham số phải trả lỗi có tên filter/tag; preview hiển thị vị trí lỗi, production không lộ nội bộ.
• Không I/O, truy vấn hoặc thay đổi dữ liệu từ template; dữ liệu commerce chỉ qua resolver có quyền.
• Kiểm thử escaping và profile runtime trước khi công bố cho theme.

Nguồn & quyết định chuyển đổi

Tên tham khảo: paginate. Hợp đồng và ví dụ là đề xuất riêng cho Skai, không sao chép contract Liquid.

Nguồn tham khảo Shopify · Quy ước đặc tả Skai

Đối chiếu mã nguồn local: skaiplatform/lingo/filters_builtin.go, tags_*.go, security.go và skaiweb/services/theme_engine/functions.go. Badge “Đang phát triển” biểu thị tài liệu dự kiến, không xác nhận engine đã được triển khai.

comment

Ghi chú template. Dùng khả năng hiện có, không tạo alias hoặc triển khai engine trùng chức năng.

Hợp đồng sử dụng

Dùng cú pháp chính thức Lingo; không triển khai alias Liquid.

{% comment %}Ghi chú nội bộ{% endcomment %}OK

OK

Trường hợp biên và an toàn

Không ghi bí mật vào source dù không render; không cần alias.

Tiêu chí nghiệm thu

• Kiểm thử ví dụ ở trên cùng đầu vào rỗng, Unicode, sai kiểu và giới hạn đầu ra.
• Khóa hành vi của implementation hiện tại bằng test; không sửa ngữ nghĩa để khớp Liquid.
• Không I/O, truy vấn hoặc thay đổi dữ liệu từ template; dữ liệu commerce chỉ qua resolver có quyền.
• Kiểm thử escaping và profile runtime trước khi công bố cho theme.

Nguồn & quyết định chuyển đổi

Tên tham khảo: comment. Dùng tên/cú pháp Lingo hoặc helper Skai ghi ở đầu trang, không tạo alias tương thích Liquid.

Nguồn tham khảo Shopify · Quy ước đặc tả Skai

Đối chiếu mã nguồn local: skaiplatform/lingo/filters_builtin.go, tags_*.go, security.go và skaiweb/services/theme_engine/functions.go. Badge “Đang phát triển” biểu thị tài liệu dự kiến, không xác nhận engine đã được triển khai.

entries — Danh sách nội dung và phân trang

Có sẵn · Theme runtime

Truy vấn nội dung theo content type được cấp cho application hiện tại. Block tạo phạm vi riêng cho entries.items và entries.pagination; không tự lặp, không ghi đè dữ liệu bên ngoài.

{% entries type="post" limit=8 order="published_at desc" page_key="posts_page" %}
  {% for entry in entries.items %}
    <h2>{{ entry.title }}</h2>
  {% empty %}
    <p>Chưa có bài viết.</p>
  {% endfor %}

  {% if entries.pagination.has_previous %}
    <a href="{{ entries.pagination.previous_url }}">Trang trước</a>
  {% endif %}
  {% if entries.pagination.has_next %}
    <a href="{{ entries.pagination.next_url }}">Trang tiếp</a>
  {% endif %}
{% endentries %}

Tham số

• type: key content type, bắt buộc, phải được bind vào application.
• limit: mặc định 8; từ 1 đến 100 và chịu giới hạn runtime.
• page_key: mặc định page; đặt posts_page để đọc ?posts_page=2. Mỗi danh sách phân trang độc lập dùng một key riêng.
• term: ID taxonomy term; mặc định rỗng, không lọc taxonomy. Không phải từ khóa tìm kiếm.
• order: mặc định updated_at desc. Hỗ trợ updated_at, created_at, published_at, id cùng asc hoặc desc.
• status: mặc định/rỗng là published. Không cho đọc draft qua tag.

Tương thích phân trang hiện có

Dùng chung paginator với post.paginate(8): giữ nguyên page, per_page, total, total_pages, has_previous, has_next, previous_url, next_url. items và records là hai tên của cùng danh sách. Link phân trang giữ query parameter khác, chỉ đổi key của block hiện tại.

Tag chỉ đăng ký trong theme engine, không thuộc Lingo core. Runtime có allowlist tags cần cho phép entries. Block lồng nhau khôi phục dữ liệu cha khi kết thúc.