Thiết lập giao diện#

Một bộ giao diện có thể tự khai báo các tuỳ chọn để chủ cửa hàng tự chỉnh trong trang quản trị mà không cần sửa mã. Khai báo nằm ở tệp config/settings_schema.json trong bộ giao diện; giá trị đọc ra bằng {{ settings.<mã> }}.

Cách hoạt động#

1. Bạn thêm tệp config/settings_schema.json vào bộ giao diện (tab Tệp).
2. Hệ thống tự dựng biểu mẫu tương ứng ở tab Thiết lập, kèm giá trị mặc định.
3. Chủ cửa hàng chỉnh giá trị và lưu.
4. Mẫu giao diện đọc giá trị đó bằng {{ settings.<mã> }}.

Thêm một mục vào tệp khai báo là đủ để có ô nhập tương ứng — không cần sửa gì ở phần quản trị.

Cấu trúc tệp khai báo#

{
  "version": 1,
  "groups": [
    {
      "name": "Thương hiệu",
      "settings": [
        {
          "id": "accent_color",
          "type": "color",
          "label": "Màu nhấn",
          "default": "#e11d48"
        }
      ]
    }
  ]
}

Các loại ô nhập#

checkbox trả về boolean thật, nên viết thẳng được:

{% if settings.show_flash_sale %}
  ...
{% endif %}

image_picker trả về tên tệp, cần ghép qua asset_url:

<img src="{{ settings.logo_asset | asset_url }}" alt="{{ store.name }}">

settings khác custom thế nào#

Hai nhóm biến này không thay thế nhau — một giao diện thường dùng cả hai.

Nguyên tắc: thông tin của cửa hàng thì để ở custom, lựa chọn hiển thị của giao diện thì để ở settings.

Xem trước giao diện chưa xuất bản#

Trong tab Thiết lập, khung bên phải hiển thị bản xem trước của chính bộ giao diện đang sửa — kể cả khi bộ đó chưa được kích hoạt. Lưu thiết lập thì khung xem trước tự tải lại.

Trang đang ở chế độ xem trước có biến theme_preview bằng true (chỉ trong theme.html), dùng để hiện dải cảnh báo:

{% if theme_preview %}
  <div class="preview-bar">Bạn đang xem trước một giao diện chưa xuất bản.</div>
{% endif %}

Liên kết xem trước có chữ ký số và hết hạn sau 30 phút; trang xem trước không bị lập chỉ mục bởi công cụ tìm kiếm.

Thiết lập được máy chủ đọc: khối sản phẩm trang chủ#

Hầu hết thiết lập chỉ được chính giao diện đọc bằng {{ settings.<mã> }}. Có một ngoại lệ: home_box_categories được máy chủ đọc trước khi dựng trang chủ, để chuẩn bị sẵn biến home_boxes (HomeBox).

{
  "id": "home_box_categories",
  "type": "textarea",
  "label": "Danh mục hiện trên trang chủ",
  "info": "Slug danh mục, ngăn nhau bằng dấu phẩy, theo thứ tự hiển thị.",
  "default": "laptop, pc-gaming, man-hinh"
}

Cách máy chủ xử lý giá trị này:

• Khoảng trắng thừa quanh mỗi slug được cắt bỏ; mục rỗng bị loại.
• Slug không tồn tại thì bị bỏ qua, không báo lỗi và không làm hỏng trang chủ — gõ sai một slug chỉ làm thiếu một khối.
• Danh mục không còn sản phẩm nào cũng bị bỏ nguyên khối, vì một băng chuyền rỗng trông như lỗi.
• Chưa khai báo thiết lập, hoặc để trống, thì home_boxes là danh sách rỗng.

Vì vậy giao diện luôn phải chịu được home_boxes rỗng:

{% for box in home_boxes %}
  <section>
    <h2>{% if box.category.url %}<a href="{{ box.category.url }}">{{ box.category.title }}</a>
        {% else %}{{ box.category.title }}{% endif %}</h2>
    {% for child in box.children %}
      <a href="{{ child.url }}">{{ child.title }}</a>
    {% endfor %}
    {% for product in box.products %}
      {% include 'components/product_item' %}
    {% endfor %}
  </section>
{% endfor %}

Danh mục con của khối nằm ở box.children, không phải box.category.children — box.category chỉ mang id, title, slug, url và image_url.

Lưu ý#

• Bỏ một mục khỏi tệp khai báo sẽ xoá giá trị đã lưu của mục đó.
• Đổi type của một mục sẽ chuyển đổi lại giá trị đang lưu theo kiểu mới.
• Tệp khai báo sai cú pháp sẽ bị từ chối khi lưu; bản đang chạy không bị ảnh hưởng.
• Nhân bản một bộ giao diện sẽ mang theo toàn bộ giá trị thiết lập.
• Trang thanh toán (checkout) không có settings, giống như custom và menus.

Duyệt bảng dữ liệu dạng khoá–giá trị#

Khi lặp qua một map trong Liquid (ví dụ product.metafields.specs), bộ máy Liquid của xStore trả về giá trị, không trả về khoá:

{% for v in product.metafields.specs %}{{ v }}{% endfor %}
{%- comment -%} → chỉ ra giá trị, không có tên trường {%- endcomment -%}

Vì vậy hãy truy cập trực tiếp theo tên trường khi bạn biết trước khoá:

{{ product.metafields.specs.warranty }}