Tài liệu xStore

Hướng dẫn phát triển giao diện storefront

Bộ lọc

Bộ lọc đứng sau dấu | và biến đổi giá trị trước khi in ra. Nối được nhiều bộ lọc liên tiếp: {{ 'main.css' | asset_url | stylesheet_tag }}.

Danh sách bộ lọc

Bộ lọc Cú pháp Mô tả Ví dụ Từ phiên bản
money {{ số | money }} Định dạng số tiền theo kiểu Việt Nam, kèm ký hiệu ₫. {{ 1234567 | money }} → 1.234.567₫ 1.0
money_vnd {{ số | money_vnd }} Như money nhưng hậu tố là 'VNĐ'. {{ 1234567 | money_vnd }} → 1.234.567 VNĐ 1.0
date_vi {{ chuỗi_ngày | date_vi }} Đổi chuỗi ngày giờ sang dạng dd/mm/yyyy. {{ article.published_at | date_vi }} → 09/08/2026 1.0
stylesheet_tag {{ url | stylesheet_tag }} Sinh thẻ link rel=stylesheet trỏ tới tệp CSS. {{ 'main.css' | asset_url | stylesheet_tag }} 1.0
script_tag {{ url | script_tag }} Sinh thẻ script trỏ tới tệp JavaScript. {{ 'main.js' | asset_url | script_tag }} 1.0
json {{ giá_trị | json }} Đổi giá trị Liquid sang JSON để dùng trong JavaScript. Nhúng vào thuộc tính HTML nháy kép thì phải nối thêm | escape, nếu không dấu nháy của JSON sẽ cắt ngang thuộc tính. {{ variants | json | escape }} 1.1
asset_url {{ 'tên-tệp' | asset_url }} Đường dẫn tới tệp tài nguyên của giao diện, kèm mã phiên bản để trình duyệt không dùng bản cũ. {{ 'main.css' | asset_url }} 1.0

Mã đầy đủ

Khối dưới đây dùng cả sáu bộ lọc riêng của xStore trong một tệp giao diện.

{% comment %} Tài nguyên của bộ giao diện — asset_url gắn sẵn mã phiên bản {% endcomment %}
{{ 'main.css' | asset_url | stylesheet_tag }}
{{ 'main.js'  | asset_url | script_tag }}

{% comment %} Giá: money ra "1.234.567₫", money_vnd ra "1.234.567 VNĐ" {% endcomment %}
<span class="price">{{ product.price | money }}</span>
{% if product.compare_at_price %}
  <s class="price price--original">{{ product.compare_at_price | money_vnd }}</s>
{% endif %}

{% comment %} Ngày: date_vi đổi sang dd/mm/yyyy {% endcomment %}
<time>{{ article.published_at | date_vi }}</time>

Giá trị tiền trong xStore là số nguyên, đơn vị đồng — xem Đối tượng dữ liệu.

Đưa dữ liệu sang JavaScript bằng json

Bộ lọc json đổi bất kỳ giá trị Liquid nào — mảng, đối tượng, chuỗi, số — thành JSON dùng được trong JavaScript.

Trong <script> thì dùng thẳng:

<script>
  const variants = {{ variants | json }};
  const productId = {{ product.id | json }};   // → "k3n8fq2wla", đã có dấu nháy
</script>

Trong thuộc tính HTML nháy kép thì phải nối thêm escape, nếu không dấu nháy của JSON sẽ cắt ngang thuộc tính ngay tại ký tự đầu tiên:

<div x-data="{ variants: {{ variants | json | escape }} }">
  <button @click="chon({{ variant | json | escape }})">Chọn</button>
</div>

Trình duyệt giải mã thực thể HTML trước khi JavaScript chạy, nên &quot; trở lại thành " đúng lúc cần.

Mã định danh luôn là chuỗi. Đừng viết selected.id === {{ variant.id }} — kết quả là selected.id === k3n8fq2wla, tức JavaScript hiểu k3n8fq2wla là tên biến và báo lỗi. Dùng {{ variant.id | json }} để có "k3n8fq2wla".