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

מדריך 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
המסננים products ו‑entityרשומות מקטלוג המוצרים או מישות מותאמת מתוך סינון שמורהזנות קטלוג למטה

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

מסננים​

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

{{ 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: "חבר" }} ← חבר (כשהמאפיין ריק)

מספרים וכסף​

מסנןמה הוא עושהדוגמה ← פלט
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){{ order.createdAt | date_format }} ← Jul 12, 2026 · {{ order.createdAt | date_format: "long" }} ← July 12, 2026 · "full" ← Sunday, July 12, 2026
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

מערכים​

מסנןמה הוא עושהדוגמה ← פלט
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 שלכם פשוט לא מציגה כלום, לעולם לא שגיאה.
  • האפשרויות Product catalog ו־Custom entity בבורר ההתאמה האישית בונות עבורכם את קטע ה‑assign (ראו משתני הודעה).
מיושן: catalog

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

במה 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.

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