דלג לתוכן הראשי

מדריך Liquid המלא

Joryio מתאימה הודעות באופן אישי באמצעות Liquid - אתם כותבים מצייני מקום כמו {{ user.firstName }} ומסננים כמו {{ price | currency }}, והם נפתרים לערך המתאים לכל נמען בזמן השליחה. העמוד הזה הוא המדריך המלא: כל מרחבי השמות של המשתנים וכל המסננים המותאמים של Joryio, עם דוגמאות.

חדשים ב‑Liquid של Joryio? התחילו מתבניות Liquid ליסודות, וחזרו לכאן כשתצטרכו את הפרטים.

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

שתי התנהגויות מקלות שכדאי להכיר:

  • משתנה ללא ערך מוצג כטקסט ריק - לעולם לא כשגיאה.
  • מסנן לא מוכר משאיר את הערך ללא שינוי במקום להיכשל.

משתנים​

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

מרחב שמותמה הוא מכילפרטים
user.firstName, user.lastName, user.email, user.phone, user.id, user.externalId, user.whatsappNameמאפייני ברירת המחדל של איש הקשרמשתני הודעה
user.custom.<attribute>כל מאפיין מותאם של איש הקשר (למשל user.custom.plan)משתני הודעה
trigger.properties.<field>איך הם נכנסו למסע - אירוע הכניסה, קבוע לכל הריצהמשתני הודעה
event.properties.<field>, event.nameהדבר האחרון שהם עשו - האירוע האחרון שקידם את המסעמשתני הודעה
reply.text, reply.type, reply.profile.nameקיצורים ידידותיים לתשובה הנכנסת האחרונה של איש הקשר ב‑WhatsApp או ב‑SMSמשתני הודעה
blocks.<slug>בלוק תוכן לשימוש חוזר, המעובד במקומובלוקי תוכן
unsubscribe_url, preferences_url, resubscribe_urlקישורי הרשמה ייחודיים לכל נמען (אימייל, SMS, סשן WhatsApp)תבניות Liquid
cart.items, cart.value, cart.subtotal, cart.currency, cart.checkoutUrlעגלת החנות המסונכרנת של איש הקשר - פריטים עם name, quantity, price, total, imageUrl, url, sku value הוא הסכום שהחנות שלחה (יכול לכלול משלוח); subtotal הוא סכום הפריטים, לפני משלוח ומס.מוצרים
last_order.items, last_order.total, last_order.currency, last_order.placedAt, last_order.orderUrlההזמנה האחרונה שלהם שלא בוטלה ולא זוכתה - אותם שדות פריט כמו בעגלהמוצרים
top_productsהמוצרים שהם מזמינים הכי הרבה - עד 5 עם name, sku, imageUrl, url, timesOrdered, lastOrderedAt, הנפוץ ביותר ראשוןמוצרים
המסננים products ו‑entityרשומות מקטלוג המוצרים או מישות מותאמת מתוך סינון שמורהזנות קטלוג למטה

trigger.*, event.* ו‑reply.* זמינים רק בתוך מסע; כל השאר פועלים בכל מקום.

cart, last_order ו-top_products ריקים לאיש קשר ללא הזמנות בחנות - עטפו אותם ב-{% if %}.

מסננים​

משרשרים מסננים עם | ומעבירים ארגומנטים אחרי :. למשל:

{{ user.firstName | capitalize | default: "חבר" }}
{{ order.total | currency: "EUR" }}

טקסט​

מסנןמה הוא עושהדוגמה ← פלט
capitalizeהופך את האות הראשונה לגדולה ואת שאר המחרוזת לקטנה{{ "mAYA" | capitalize }} ← Maya
uppercaseממיר את כל המחרוזת לאותיות גדולות{{ "sale" | uppercase }} ← SALE
lowercaseממיר את כל המחרוזת לאותיות קטנות{{ "SALE" | lowercase }} ← sale
truncateחותך מחרוזת לאורך נתון (ברירת מחדל 50) ומוסיף סיומת (ברירת מחדל ...). הסיומת מתווספת אחרי החיתוך, מעבר לאורך{{ "The quick brown fox jumps" | truncate: 9 }} ← The quick...
strip_htmlמסיר תגי HTML{{ "<b>Sale</b> today" | strip_html }} ← Sale today
url_encodeמקודד מחרוזת ל‑URL (לבניית קישורים){{ "red shoes" | url_encode }} ← red%20shoes
pluralizeמקבל מספר ומחזיר את צורת היחיד או הרבים של המילה. הרבים כברירת מחדל הוא היחיד + s; ארגומנט שלישי לצורות רבים חריגות3 {{ 3 | pluralize: "item" }} ← 3 items
defaultערך גיבוי כשהערך הוא null, לא מוגדר או מחרוזת ריקה{{ user.firstName | default: "חבר" }} ← חבר (כשהמאפיין ריק)
landing_page_urlקישור לדף נחיתה מפורסם לפי ה-slug שלו. נושא את הטוקן של הנמען, כך שהדף יודע מי הגיע; ארגומנט אופציונלי מוסיף מחרוזת שאילתה. הקישור נבנה תמיד; slug שלא פורסם (או שאינו קיים) מקבל 404 בהפניה. ריק רק כשה-slug אינו תקין או כשלעיבוד אין מרחב עבודה{{ "spring-sale" | landing_page_url: "utm_campaign=spring" }} ← https://api-eu1.joryio.com/api/p/go/<workspace>/spring-sale?jp=…&utm_campaign=spring

מספרים וכסף​

מסנןמה הוא עושהדוגמה ← פלט
currencyמעצב מספר כסכום כסף. קוד המטבע כברירת מחדל הוא USD; אפשר להעביר כל קוד ISO. העיצוב לפי en-US (סימן המטבע לפני, פסיקים לאלפים){{ 1249.5 | currency }} ← $1,249.50 · {{ order.total | currency: "EUR" }} ← €49.90

תאריכים​

מסנןמה הוא עושהדוגמה ← פלט
date_formatמעצב תאריך. סגנונות: short (ברירת מחדל), long, full. כשמתקבל סגנון לא מוכר, נעשה שימוש ב‑short. שמות החודשים והימים באנגלית (en-US). התאריך מוצג באזור הזמן של סביבת העבודה, גם בתצוגה המקדימה וגם בשליחה; ערך של תאריך בלבד, כמו יום הולדת (1990-05-01), לעולם לא זז. אפשר גם תבנית strftime ("%d %b %H:%M"), וארגומנט שני אופציונלי מציין אזור זמן IANA אחר - אזור לא מוכר חוזר לאזור הזמן של סביבת העבודה{{ order.createdAt | date_format }} ← Jul 12, 2026 · {{ order.createdAt | date_format: "long" }} ← July 12, 2026 · "full" ← Sunday, July 12, 2026 · {{ order.createdAt | date_format: "%d %b %H:%M", "America/New_York" }} → 12 Jul 05:30
add_daysמוסיף N ימים לתאריך (מספר שלילי מחסיר). מחזיר חותמת זמן ISO - שרשרו date_format כדי להפוך אותה לקריאה{{ order.createdAt | add_days: 7 | date_format }} ← Jul 19, 2026
time_agoזמן יחסי בשפה אנושית (ברזולוציית שנה/חודש/שבוע/יום/שעה/דקה/שנייה){{ user.custom.lastOrderAt | time_ago }} ← 3 days ago

תאריכים ושעות בתוכן ההודעה מוצגים באזור הזמן של סביבת העבודה, אותו אזור שבו משתמשת שאר האפליקציה. זה חל על date_format ועל המסנן הסטנדרטי date ({{ order.createdAt | date: "%H:%M" }}); כדי להשתמש באזור אחר, העבירו אותו כארגומנט האחרון.

מערכים​

מסנןמה הוא עושהדוגמה ← פלט
joinמאחד פריטי מערך למחרוזת. המפריד כברירת מחדל הוא , {{ names | join }} ← Ana, Ben, Gal · {{ names | join: " / " }} ← Ana / Ben / Gal
mapשולף מאפיין אחד מכל פריט ומחזיר מערך חדש{{ items | map: "name" | join }} ← Mug, Tee
firstהפריט הראשון{{ items | first }}
lastהפריט האחרון{{ items | last }}
sizeאורך של מערך או של מחרוזת (0 לכל דבר אחר){{ cart.items | size }} ← 3
countמספר הפריטים במערך (0 אם זה לא מערך){{ cart.items | count }} ← 3

צבירה וסינון​

המסננים האלה פועלים על מערכים של רשומות - פריטי עגלה, הזמנות או הזנות קטלוג. כל ארגומנט field תומך בנתיבי נקודה לתוך אובייקטים מקוננים (למשל "price.amount").

מסנןמה הוא עושהדוגמה ← פלט
sumמסכם שדה מספרי בכל פריטי המערך (ערכים חסרים נספרים כ‑0){{ orders | sum: "totalAmount" }} ← 540
avgממוצע של שדה מספרי (0 למערך ריק){{ orders | avg: "totalAmount" }} ← 180
maxהערך המספרי הגדול ביותר של שדה (ערכים לא מספריים מדולגים; 0 אם אין){{ products | max: "price" }} ← 129.9
minהערך המספרי הקטן ביותר של שדה{{ products | min: "price" }} ← 19.9
whereמסנן את המערך. שלוש צורות קריאה: where: "featured" משאיר פריטים שהערך שלהם נחשב true;‏ where: "category", "shoes" משאיר פריטים שערכם שווה לערך הנתון; where: "price", "gt", 100 משווה באמצעות אופרטור: eq, neq, gt, gte, lt, lte, contains, in (גם צורות הסימנים ==, !=, >, >=, <, <= פועלות){{ items | where: "category", "shoes" | count }} ← 2
sortממיין לפי שדה, בסדר asc (ברירת מחדל) או desc. בלי שדה - ממיין את הערכים עצמם{{ products | sort: "price", "desc" | first }} ← המוצר היקר ביותר

דוגמה מלאה - שלוש ההזמנות האחרונות של הנמען:

{% assign recent = orders | sort: 'createdAt', 'desc' %}
{% for order in recent limit: 3 %}
- {{ order.createdAt | date_format }}: {{ order.totalAmount | currency }}
{% endfor %}
סך הקניות: {{ orders | sum: 'totalAmount' | currency }}

הזנות קטלוג​

שני מסננים מושכים אוספי רשומות לתוך הודעה, וכל אחד מהם מגובה בסינון שמור בסביבת העבודה שלכם. שניהם מחזירים מערך - משתמשים בהם בתג assign ואז עוברים על התוצאה בלולאה.

products - קטלוג המוצרים של החנות​

מושך מקטלוג המוצרים המסונכרן (Shopify / WooCommerce / Magento) דרך סינון מוצרים. יש קטלוג מוצרים אחד, ולכן הארגומנט הוא שם הסינון:

{% assign products = 'featured' | products %}
{% for item in products %}
- {{ item.name }}: {{ item.price | currency }}
{% endfor %}

entity - הזנת ישות מותאמת​

מושך רשומות מישות מותאמת. הארגומנט הראשון הוא שם הישות, והשני (אופציונלי) הוא שם הסינון:

{% assign episodes = 'tv_series' | entity: 'latest' %}
{% for item in episodes %}
- {{ item.name }}
{% endfor %}

אפשר להעביר משתנים לסינון ישות שמקבל פרמטרים - למשל להעביר אליו את אירוע הכניסה של המסע:

{% assign items = 'products' | entity: 'product_by_id', trigger %}

הערות על ההתנהגות:

  • סינונים שזהים לכל הנמענים (ללא מסנני מאפייני משתמש או הקשר) נשמרים במטמון - כ‑5 דקות בתצוגה המקדימה בעורך, כדקה בשליחה - כך ששליחות המוניות אינן מריצות שאילתה מחדש לכל נמען. סינוני ישויות מותאמים אישית מחושבים מחדש לכל נמען.
  • אם סינון הישות או המוצרים לא נמצא (או שהשאילתה נכשלה), המסנן מחזיר מערך ריק - לולאת ה‑for שלכם פשוט לא מציגה כלום, לעולם לא שגיאה.
  • שלושת המסננים (products, entity והשם החלופי catalog) פועלים בכל מסלול עיבוד ובאותם שמות: התצוגה המקדימה בעורך, שליחת קמפיינים, שליחה ממסעות וכל worker של ערוץ. מה שהתצוגה המקדימה מציגה הוא מה שהנמען מקבל.
  • האפשרויות Product catalog ו־Custom entity בבורר ההתאמה האישית בונות עבורכם את קטע ה‑assign (ראו משתני הודעה).
מיושן: catalog

המסנן הישן catalog הוא שם חלופי שהוצא משימוש עבור entity, אך הוא עדיין פועל כדי שתבניות קיימות לא יישברו. מעתה העדיפו entity לישויות מותאמות ו‑products לקטלוג החנות.

המלצות​

recommendations.<slot> הוא מערך של מוצרים מומלצים לנמען, מתוך מודל המלצות. המשבצת היא שם המודל כמפתח (For you הופך ל-for_you); recommendations.default הוא מודל ברירת המחדל של סביבת העבודה. לכל פריט יש name, ‏price (מעוצב), ‏compareAtPrice, ‏discountPercent, ‏url, ‏image, ‏description ו-id. הוא עובד בכל ערוץ - אימייל (קמפיינים ומסעות), SMS,‏ WhatsApp,‏ Viber,‏ Push,‏ in-app ודפי נחיתה - וגם בתצוגות מקדימות ובשליחות בדיקה:

{% for item in recommendations.for_you limit: 3 %}
{{ item.name }} - {{ item.price }} {{ item.url }}
{% endfor %}

ראו משבצות Liquid לשמות המשבצות ושדות הפריט, ואת רשימת החסימה למוצרים שלעולם אינם מומלצים.

במה Joryio שונה מ‑Liquid סטנדרטי​

כמה מסננים מתנהגים בכוונה אחרת מהמסננים המקבילים ב‑Shopify/LiquidJS:

  • capitalize גם הופך את שאר המחרוזת לאותיות קטנות ("mAYA" הופך ל‑Maya, לא ל‑MAYA).
  • default מתייחס למחרוזת ריקה כאל ערך חסר, כך ש‑{{ user.firstName | default: "חבר" }} משתמש בערך הגיבוי גם כשהמאפיין קיים אך ריק.
  • truncate מוסיף את הסיומת אחרי אורך החיתוך (Liquid סטנדרטי סופר את שלוש הנקודות בתוך האורך).
  • where ו‑sort מרחיבים את המסננים המובנים: הם מקבלים את צורות הקריאה הסטנדרטיות וגם מוסיפים אופרטורים להשוואה, כיוון מיון ונתיבי נקודה בשדות.

Liquid סטנדרטי ממשיך לעבוד​

כל מה שלמעלה נוסף על גבי LiquidJS הסטנדרטי: התגים המובנים - {% if %} / {% elsif %} / {% else %}, {% for %}, {% assign %}, {% case %} וחבריהם - והמסננים המובנים (upcase, downcase, date, replace, split, plus, times ועוד רבים) עובדים בכל תבנית של Joryio. כשמסנן של Joryio חולק שם עם מסנן מובנה (capitalize, default, where, sort, join, map, first, last, size), הגרסה של Joryio המתוארת בעמוד הזה היא זו שרצה. הרשימה המלאה של המסננים המובנים נמצאת בכתובת liquidjs.com/filters/overview.html.

קישורים קשורים​