Mô hình field nested-v1. Theme khai báo "field_contract": "nested-v1" trong config/theme.json. Field hệ thống giữ ở cấp gốc (item.title, term.name); field tùy chỉnh đọc qua item.fields.{key}, term.fields.{key}. Các field hệ thống như categories vẫn ở cấp gốc dù lưu dạng quan hệ. Section settings, block settings và configs không đổi. Bản release chưa chuyển đổi vẫn dùng mô hình cũ; thay đổi draft chỉ lên runtime sau khi publish.

first và media

Lấy phần tử đầu tiên của danh sách, không cần vòng lặp. Filter first đã có sẵn trong Lingo.

Resource post dùng key hệ thống images thay cho featured_image. Mặc định chỉ chọn một ảnh, có thể bật Nhiều giá trị; cột images lưu được cả danh sách. Ảnh đầu tiên dùng làm ảnh đại diện.

Media luôn là mảng UUID

Các field media đang bật, bao gồm images và thumbs, luôn trả danh sách UUID qua entries và model catalog. Chọn một: ["uuid"]. Chọn nhiều: ["uuid-1", "uuid-2"]. Không chọn: []. Không tự lấy metadata hoặc tải ảnh gốc. Field bị tắt vẫn không xuất hiện.

LINGO

{{ item.images | first | image_url: width: 450 }}
{{ item.fields.thumbs.0 | image_url: width: 450 }}
{% for file_id in item.fields.thumbs %}
  <img src="{{ file_id | image_url: width: 192, height: 160, crop: 'top' }}" loading="lazy">
{% endfor %}

Mảng rỗng qua first trả chuỗi rỗng; hãy kiểm tra có ảnh trước khi tạo thẻ img. Filter dùng chung cho mảng object taxonomy và các danh sách khác; với chuỗi, first lấy ký tự đầu tiên, vì vậy không dùng first trực tiếp trên UUID đơn bên ngoài hợp đồng media này.

Cấu hình field media

Trong Cài đặt bản ghi, chọn kiểu Media: chọn Chỉ hình ảnh hoặc File theo đuôi mở rộng. Có thể giới hạn thêm bằng jpg, png, webp, pdf, zip… (không phân biệt hoa thường; cho phép dấu chấm đầu đuôi). Để trống danh sách đuôi nghĩa là không giới hạn thêm trong nhóm đã chọn. Cờ Nhiều giá trị chỉ quyết định số lượng được chọn, không thay đổi kiểu kết quả theme.

{"media_type":"image","extensions":["jpg","jpeg","png","webp"]}
{"media_type":"all","extensions":["pdf","zip"]}

Cửa sổ chọn file lọc theo cấu hình; backend kiểm tra file được chọn thuộc đúng phạm vi, MIME ảnh và extension. Giới hạn upload toàn hệ thống vẫn được áp dụng. image_url chỉ dành cho ảnh public, không dùng tạo URL cho PDF/ZIP.

Tương thích dữ liệu cũ

UUID đơn, mảng UUID và chuỗi UUID phân cách xuống dòng được chuẩn hóa khi đọc. Không ghi lại dữ liệu cũ, không cắt bỏ file khi thay đổi cờ Nhiều giá trị. Không dùng split cho thumbs nữa. Template cũ cần thêm first hoặc .0 trước image_url.

Xem image_url →