בלוקים מותאמים אישית של Liquid לקבלות מודפסות

אפשר להשתמש בבלוק מותאם אישית של Liquid כדי להוסיף תוכן משלך לכותרת או לכותרת התחתית של קבלה מודפסת, כגון פרטי הזמנה, פרטי לקוח, מאפייני מוצר, מטא שדות וברקודים.

בלוקים מותאמים אישית של Liquid מוצגים בקבלות מודפסות של הזמנות מקוונות והזמנות Point of Sale שהושלמו. הם אינם מוצגים בהזמנות שמשתמשות בתשלום לא מקוון.

אפשר להוסיף בלוק מותאם אישית של Liquid מהעורך החזותי של הקבלות ב-Shopify Admin. הערכים שאליהם מתבצעת הפניה נמשכים מנתוני הקבלה בזמן הדפסתה. לדוגמה, קוד ה-Liquid הבא מוסיף את הערת ההזמנה לקבלה כאשר קיימת הערה:

{% if order.note %}
  <p>Order note: {{ order.note }}</p>
{% endif %}

בדף זה

כללי תחביר של Liquid

יש לעבור על כללי התחביר הבאים לפני בניית בלוק מותאם אישית של Liquid:

שמות משתנים נכתבים באותיות קטנות וקווים תחתונים, פורמט הידוע כ-snake_case. לדוגמה, יש להשתמש ב-order.total_price,‏ order.customer.display_name ו-order.line_items.
ערכי כסף הם מספרים רגילים. יש לעצב אותם בעזרת המסנן money, למשל {{ order.total_price | money }}.
מומלץ להגן על ערכים אופציונליים בעזרת משפט if כדי לא להדפיס שורה ריקה, למשל {% if order.customer.email %}{{ order.customer.email }}{% endif %}.
ניתן לעבור על רשימות בלולאה בעזרת משפט for, למשל {% for item in order.line_items %} ... {% endfor %}.
חלק מהתגים של Liquid אינם נתמכים. לא ניתן להשתמש ב-assign,‏ capture,‏ include,‏ render,‏ raw,‏ increment, או decrement. אם הבלוק משתמש בתג שאינו נתמך, הקבלה לא תישמר ותופיע שגיאה.
בלוק מותאם אישית של Liquid יכול להכיל עד 50 KB של קוד.

HTML ו-CSS

ניתן להשתמש ב-HTML בסיסי בתוך בלוק מותאם אישית של Liquid כדי לארגן את התוכן, למשל <p>,‏ <br>,‏ <strong>,‏ <em>, כותרות, רשימות וקישורים. התוכן עושה שימוש בגופנים ובגדלים הקיימים של הקבלה.

לא ניתן להשתמש ב-CSS כדי לשנות את המראה של קבלה. בלוקים של <style> ומאפייני style אינם נתמכים, כדי שבלוק מותאם אישית של Liquid לא יוכל לשנות את העיצוב או להסתיר תוכן במקומות אחרים בקבלה. תגי <script>, מטפלי אירועים כגון onclick וקישורי javascript: גם הם אינם נתמכים.

אם הבלוק מכיל HTML שאינו נתמך, הקבלה לא תישמר ותופיע שגיאה. יש להסיר את ה-HTML שאינו נתמך ולשמור שוב.

משתנים ואובייקטים

בלוק מותאם אישית של Liquid יכול להפנות לאובייקטים ולמשתנים הבאים. חלק מהערכים אינם קיימים בקבלה כברירת מחדל, לכן בלוק מותאם אישית של Liquid הוא דרך אחת להוסיף אותם.

משתנים ברמה העליונה

המשתנים הבאים ברמה העליונה זמינים בבלוק מותאם אישית של Liquid.

תיאור המשתנים ברמה העליונה הזמינים עבור בלוק מותאם אישית של Liquid
משתנה	תיאור
order	ההזמנה שמודפסת.
shop	החנות.
location	המיקום הקמעונאי.
settings	הגדרות התצוגה של הקבלה, שהן המתגים שהוגדרו בעורך.
purchased_gift_cards	כרטיסי המתנה שנרכשו בהזמנה זו.
staff_member_description	איש הצוות שמשויך להזמנה, כאשר התצוגה של אנשי צוות מופעלת.
locale	ההגדרות האזוריות של הקבלה, כגון en.
is_pickup	האם ההזמנה היא הזמנה לאיסוף.
pickup_location	מיקום האיסוף, במידת הרלוונטיות.

אובייקט הזמנה

תיאור של אובייקט ההזמנה
מאפיין	תיאור
name	שם ההזמנה, כגון 1001#.
created_at	חותמת הזמן של ההזמנה. לשימוש עם מסנן `date`.
note	הערת ההזמנה.
subtotal_price	סכום הביניים. יש לעצב בעזרת המסנן `money`.
total_price	סך הכול. יש לעצב בעזרת המסנן `money`.
shipping_price	עלות השילוח שנגבתה. יש לעצב בעזרת המסנן `money`.
total_tip_received	סך כל הטיפ. יש לעצב בעזרת המסנן `money`.
balance_due	הסכום שנותר לתשלום. יש לעצב בעזרת המסנן `money`.
change_due	העודף שניתן. יש לעצב בעזרת המסנן `money`.
taxes_included	האם המס כלול במחירים.
receipt_number	מספר הקבלה.
barcode_content	התוכן שיש לקודד בברקוד.
qr_code_content	התוכן שיש לקודד בקוד QR. לשימוש עם מסנן `qrcode`.
line_items	הפריטים שנרכשו. המאפיינים של כל פריט מפורטים באובייקט פריט השורה של ההזמנה.
transactions	התשלומים. המאפיינים של כל תשלום מפורטים באובייקט עסקה.
discounts	ההנחות ברמת ההזמנה. המאפיינים של כל הנחה מפורטים באובייקט הנחה.
tax_lines	שורות המס. המאפיינים של כל שורת מס מפורטים באובייקט שורת מס.
refunds	ההחזרים הכספיים של ההזמנה.
shipping_address	הכתובת לשילוח. נכסי הכתובת מפורטים ב-אובייקט הכתובת.
customer	פרטי הלקוח, מפורטים ב-אובייקט הלקוח.
metafields	מטא שדות של ההזמנה.

אובייקט לקוח

האובייקט order.customer מכיל את פרטי הלקוח.

תיאור של אובייקט הלקוח
מאפיין	תיאור
display_name	השם לתצוגה של הלקוח.
first_name	השם הפרטי של הלקוח.
last_name	שם המשפחה של הלקוח.
email	כתובת הדוא"ל של הלקוח.
phone	מספר הטלפון של הלקוח.
default_address	כתובת ברירת המחדל של הלקוח.
metafields	מטא שדות של הלקוח.

אובייקט של פריט שורה בהזמנה

כל פריט ב- order.line_items מכיל את הנכסים הבאים.

תיאור של אובייקט פריט השורה בהזמנה
מאפיין	תיאור
name	שם המוצר או השורה.
variant_title	הגרסה, למשל גדול / כחול.
sku	המק"ט.
vendor	הספק.
quantity	הכמות.
price	המחיר ליחידה. יש לפרמט באמצעות המסנן `money`.
total_price	סך הכול לשורה. יש לפרמט באמצעות המסנן `money`.
discounted_total_price	סך הכול לשורה לאחר הנחות. יש לפרמט באמצעות המסנן `money`.
discounted_unit_price	המחיר ליחידה לאחר הנחות. יש לפרמט באמצעות המסנן `money`.
discounts	ההנחות שהוחלו על השורה.
selling_plan_name	שם המנוי או תוכנית המכירה, אם ישנם.
staff_member_description	איש הצוות שמשויך לשורה.
custom_attributes	נכסי פריט השורה, נגישים לפי מפתח.
product_metafields	מטא שדות של המוצר, נגישים לפי מפתח.
variant_metafields	מטא שדות של הגרסה, נגישים לפי מפתח.

אובייקט עסקה

כל תשלום ב- order.transactions מכיל את הנכסים הבאים. אשראי בחנות שנוצל בהזמנה יופיע כתשלום בשם 'אשראי בחנות'. יתרת האשראי בחנות של הלקוח אינה זמינה כמשתנה.

תיאור של אובייקט העסקה
מאפיין	תיאור
name	שם התשלום, למשל Visa, מזומן או אשראי בחנות.
payment_type	קוד סוג התשלום.
amount	הסכום. יש לפרמט באמצעות המסנן `money`.
kind	סוג העסקה.
status	סטטוס העסקה.
credit_card_number	מספר הכרטיס המוסתר, במידת הרלוונטיות.
created_at	חותמת הזמן של העסקה.
additional_details	שורות של פרטי תשלום נוספים.

אובייקט החנות

האובייקט shop מכיל את פרטי החנות.

תיאור של אובייקט החנות
מאפיין	תיאור
name	שם החנות.
domain	דומיין החנות.
currency	מטבע החנות.
id	מזהה החנות.

אובייקט מיקום

האובייקט location מכיל את פרטי מיקום החנות הפיזית.

תיאור של אובייקט המיקום
מאפיין	תיאור
name	שם המיקום.
address1	שורת הכתובת הראשונה.
address2	שורת הכתובת השנייה.
city	העיר.
province	המחוז או המדינה.
province_code	קוד המחוז או המדינה.
zip	המיקוד.
country	המדינה.
phone	מספר הטלפון.
metafields	מטא שדות של המיקום.

אובייקט כתובת

כתובת, למשל order.shipping_address או order.customer.default_address, מכילה את הנכסים הבאים.

תיאור של אובייקט הכתובת
מאפיין	תיאור
company	שם החברה.
name	שם הנמען.
address1	שורת הכתובת הראשונה.
address2	שורת הכתובת השנייה.
city	העיר.
province	המחוז או המדינה.
province_code	קוד המחוז או המדינה.
zip	המיקוד.
country	המדינה.
country_code	קוד המדינה.
phone	מספר הטלפון.

אובייקט הנחה

כל הנחה ב- order.discounts או item.discounts מכיל את הנכסים הבאים.

תיאור של אובייקט ההנחה
מאפיין	תיאור
description	תיאור ההנחה.
amount	סכום ההנחה. יש לפרמט באמצעות המסנן `money`.
percentage	אחוז ההנחה.

אובייקט שורת מס

כל שורת מס ב- order.tax_lines מכיל את הנכסים הבאים.

תיאור של אובייקט שורת המס
מאפיין	תיאור
title	כותרת המס.
rate	שיעור המס כמספר עשרוני.
rate_percentage	שיעור המס כאחוזים.
price	סכום המס. יש לפרמט באמצעות המסנן `money`.
taxable_amount	הסכום החייב במס. יש לפרמט באמצעות המסנן `money`.

אובייקט כרטיס מתנה

כל כרטיס מתנה ב- purchased_gift_cards מכיל את הנכסים הבאים.

תיאור של אובייקט כרטיס המתנה
מאפיין	תיאור
code	קוד כרטיס המתנה.
masked_code	קוד כרטיס המתנה המוסתר.
balance	היתרה של כרטיס המתנה. יש לעצב באמצעות המסנן `money`.
created_at	חותמת הזמן של כרטיס המתנה.
qr_code_content	התוכן לקידוד בקוד QR.

מטא שדות ומאפיינים

מטא שדות ומאפיינים של פריטי שורה מגיעים בשתי צורות.

מטא שדות ומאפיינים של פריטי שורה מבוססים על מפתחות (keyed). אפשר לגשת לערך ישירות לפי המפתח שלו:

{{ item.product_metafields.care_instructions }}
{{ item.custom_attributes.engraving }}

מטא שדות של הזמנה ושל לקוח הם רשימות. אפשר לעבור עליהם בלולאה (Loop):

{% for m in order.metafields %}
  {{ m.namespace }}.{{ m.key }}: {{ m.value }}
{% endfor %}

המפתחות מנורמלים ל-snake_case. אפשר לגשת למפתח כמו Care Instructions או careInstructions כ-care_instructions. יש להפנות תמיד לערכים מבוססי מפתח באותיות קטנות עם קווים תחתונים.

הזמינות של מטא שדות של הזמנה ולקוח תלויה בכך שמטא שדות אלו קיימים ברשומה.

מסנני Liquid

אפשר להשתמש במסננים כדי לעצב את המידע בבלוק Liquid המותאם אישית שלך. כדי להחיל מסנן, יש להוסיף תו קו ניצב, |, ולאחר מכן את המסנן בתוך הפלט של Liquid, לדוגמה {{ order.total_price | money }}.

מסנני Liquid סטנדרטיים פועלים גם הם. למידע נוסף על מסנני Liquid, עיין בהפניה למסננים.

תיאור של המסננים הזמינים עבור בלוק Liquid מותאם אישית
מסנן	דוגמה	תיאור
money	{{ order.total_price \| money }}	מעצב סכום במטבע הקבלה.
date	{{ order.created_at \| date: '%B %e, %Y' }}	מעצב תאריך או שעה.
percent	{{ tax_line.rate \| percent }}	מעצב שבר עשרוני כאחוז, לדוגמה 0.2 כ-20%.
t	{{ 'receipt.total' \| t }}	מחזיר תווית מתורגמת.
barcode	{{ order.barcode_content \| barcode }}	מציג ברקוד.
qrcode	{{ order.qr_code_content \| qrcode }}	מציג קוד QR.

דוגמאות לבלוקים מותאמים אישית של Liquid

הדוגמאות הבאות מוסיפות תוכן שלא מופיע בתבנית הקבלה המודפסת המוגדרת כברירת מחדל.

כדי להוסיף את הערת ההזמנה (אם קיימת), יש להשתמש בקוד ה-Liquid הבא:

{% if order.note %}<p>Note: {{ order.note }}</p>{% endif %}

כדי להוסיף מק"ט (SKU) לצד כל פריט, יש להשתמש בקוד ה-Liquid הבא:

{% for item in order.line_items %}
  <p>{{ item.name }} — {{ item.sku }} ×{{ item.quantity }}</p>
{% endfor %}

כדי להוסיף מאפיין של פריט שורה, כמו חריטה, יש להשתמש בקוד ה-Liquid הבא:

{% for item in order.line_items %}
  {% if item.custom_attributes.engraving %}
    <p>{{ item.name }} — Engraving: {{ item.custom_attributes.engraving }}</p>
  {% endif %}
{% endfor %}

כדי להוסיף מטא שדה של מוצר, כמו הוראות טיפול, יש להשתמש בקוד ה-Liquid הבא:

{% for item in order.line_items %}
  {% if item.product_metafields.care_instructions %}
    <p>{{ item.name }}: {{ item.product_metafields.care_instructions }}</p>
  {% endif %}
{% endfor %}

כדי להוסיף מטא שדה של לקוח, יש להשתמש בקוד ה-Liquid הבא:

{% for m in order.customer.metafields %}
  {% if m.key == 'loyalty_tier' %}<p>Loyalty tier: {{ m.value }}</p>{% endif %}
{% endfor %}

כדי להוסיף קוד QR המקשר להזמנה, יש להשתמש בקוד ה-Liquid הבא:

{{ order.qr_code_content | qrcode }}