تخطّ إلى المحتوى الرئيسي

مرجع Liquid

تُخصّص Joryio الرسائل باستخدام Liquid: اكتب عناصر نائبة مثل {{ user.firstName }} وفلاتر مثل {{ price | currency }}، ثم تُحلّ لكل مستلم وقت الإرسال. هذه الصفحة هي المرجع الكامل لكل نطاق متغير وكل فلتر مخصص في Joryio، مع أمثلة.

هل هذه أول تجربة لك مع Liquid في Joryio؟ ابدأ بـ قوالب Liquid للتعرّف إلى الأساسيات، ثم عد إلى هنا عندما تحتاج إلى التفاصيل.

تُسجّل جميع الفلاتر أدناه في محرك Liquid مشترك واحد تستخدمه جميع مسارات العرض؛ لذلك يظهر القالب نفسه بالطريقة نفسها في قوالب Email وSMS وWhatsApp وPush وIn-app و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>Content Block قابل لإعادة الاستخدام، يُعرض ضمن النصContent Blocks
unsubscribe_url, preferences_url, resubscribe_urlروابط اشتراك خاصة بكل مستلم (Email أو SMS أو جلسة WhatsApp)قوالب Liquid
فلاتر products وentityسجلات كتالوج المنتجات أو الكيانات المخصصة من اختيار محفوظخلاصات الكتالوج أدناه

لا تُحلّ trigger.* وevent.* وreply.* إلا داخل رحلة؛ أما البقية فتعمل في كل مكان.

الفلاتر​

اربط الفلاتر باستخدام |، ومرّر الوسائط بعد :. مثال:

{{ user.firstName | capitalize | default: "there" }}
{{ 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: "there" }} → there (عند الفراغ)

الأرقام والمال​

الفلتروظيفتهمثال ← الناتج
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" يحتفظ بالعناصر الصادقة؛ و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 %}
Total spent: {{ 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 %}

ملاحظات حول السلوك:

  • تُخزَّن الاختيارات المتماثلة لكل مستلم (التي لا تستخدم فلاتر لسمة مستخدم أو للسياق) مؤقتًا لخمس دقائق تقريبًا، لذلك لا تعيد الإرسالات الجماعية الاستعلام لكل مستلم. أما اختيارات الكيانات المخصصة فتُقيَّم من جديد لكل مستلم.
  • إن تعذر العثور على اختيار الكيان/المنتج أو فشل الاستعلام، يعيد الفلتر مصفوفة فارغة؛ فتظهر حلقة for بلا محتوى، لا كخطأ.
  • ينشئ خيارا كتالوج المنتجات والكيان المخصص في منتقي التخصيص مقتطف assign لك. راجع متغيرات الرسائل.
متوقف تدريجيًا: catalog

الفلتر القديم catalog هو اسم بديل متوقف تدريجيًا لـ entity وما زال يعمل كي لا تنكسر القوالب الحالية. استخدم entity للكيانات المخصصة وproducts لكتالوج المتجر مستقبلًا.

أوجه اختلاف Joryio عن Liquid القياسي​

تتعمّد بعض الفلاتر الاختلاف عن نظيراتها في Shopify/LiquidJS:

  • capitalize يحوّل باقي السلسلة أيضًا إلى أحرف صغيرة ("mAYA" تصبح Maya لا MAYA).
  • يعتبر default السلسلة الفارغة مفقودة، لذا يعود {{ user.firstName | default: "there" }} إلى قيمة بديلة حتى عندما تكون السمة موجودة لكنها فارغة.
  • يضيف 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.

ذو صلة​