Liquid

من موسوعة حسوب
مراجعة 14:06، 12 أكتوبر 2021 بواسطة جميل-بيلوني (نقاش | مساهمات)
(فرق) → مراجعة أقدم | المراجعة الحالية (فرق) | مراجعة أحدث ← (فرق)
اذهب إلى التنقل اذهب إلى البحث

لغة Liquid هي لغة قوالب آمنة وموجَّهة للعملاء لتطبيقات الويب المرنة، وهي لغة قوالب مفتوحة المصدر أنشأتها منصة شوبيفاي Shopify وكُتِبت بلغة روبي Ruby، وهي العمود الفقري لقوالب شوبيفاي وتُستخدَم لتحميل محتوى ديناميكي على واجهات المتاجر.

اُستخدِمت لغة Liquid في الإنتاج ضمن شوبيفاي منذ عام 2006 وتستخدمها الآن تطبيقات استضافة ويب أخرى متعددة.

يمكنك تنزليها أو الاطلاع عليها على GitHub.

تُرجِم هذا التوثيق مع الإصدار v5.1.0 من Liquid.

مدخل إلى لغة Liquid

تستخدم لغة Liquid مزيجًا من الكائنات objects والوسوم tags والمرشّحات filters ضمن ملفات القالب template لعرض محتوى ديناميكي متغير.

الكائنات Objects

تحتوي الكائنات على المحتوى الذي تعرضه لغة Liquid على الصفحة، حيث تُعرَض الكائنات والمتغيرات عند وضعها ضمن أقواس معقوصة مزدوجة {{ و }}.

{{ page.title }}

الخرج:

Introduction

تعرض لغة Liquid في هذه الحالة محتوى خاصية العنوان title لكائن الصفحة page الذي يحتوي على النص Introduction.

الوسوم Tags

تُنشِئ الوسوم منطق وتحكم تدفق القوالب. لا تنتج محدّدات النسبة المئوية للقوس المعقوص {% و %} والنص المُحاط بهما أيَّ خرج مرئي عند تصيير rendered القالب. يتيح لك هذا إسناد متغيرات وإنشاء شروط أو حلقات بدون إظهار منطق لغة Liquid على الصفحة.

{% if user %}
  Hello {{ user.name }}!
{% endif %}

خرج الشيفرة:

  Hello Adam!

يمكن تصنيف الوسوم إلى أنواع مختلفة هي:

اطّلع على المزيد عن كل نوع من الوسوم في الأقسام الخاصة بها.

المرشحات Filters

تغيّر المرشحات خرج كائن أو متغيّر لغة Liquid، وتُستخدَم ضمن الأقواس المزدوجة المعقوصة {{ }} والوسوم ذات النوع إسناد متغيرات variable assignment ويُفصَل بينهما بمحرف الشريط العمودي |.

{{ "/my/fancy/url" | append: ".html" }}

الخرج:

/my/fancy/url.html

يمكن استخدام مرشّحات متعددة على خرج واحد، إذ تُطبَّق المرشّحات من اليسار إلى اليمين:

{{ "adam!" | capitalize | prepend: "Hello " }}

الخرج:

Hello Adam!

التطبيقات التي تستخدم لغة Liquid

web-applications.png

وغيرها الكثير.

الأساسيات

المعاملات Operators

شرح المعاملات المنطقية ومعاملات موازنة متعددة التي تحتويها Liquid، ويمكنك استخدام هذه المعاملات لإنشاء منطق مع الوسوم ذات النوع control flow (تحكم في تدفق أو خط سير الشيفرة).

نوعا القيم الصحيحة Truthy والخطأ Falsy في Liquid

يشرح هذا القسم أنواع البيانات التي تُقيَّم على أنها صح true أو خطأ false.

أنواع البيانات في لغة Liquid

تشرح هذه الصفحة أنواع البيانات التي تحويها لغة Liquid وكيفية التعامل معها.

إصدارات Liquid

يعرض الإصدارات الأكثر شيوعًا من لغة Liquid الموجودة وهي Liquid و Shopify Liquid و Jekyll Liquid.

التحكم بالمسافات الفارغة Whitespace في Liquid

تتيح Liquid آليةً للتحكم بالمسافات الفارغة عند تصيير الشيفرة وطباعتها في قالب HTML، إذ يُحوَّل أي سطر من شيفرة Liquid في القالب إلى سطر إضافي ضمن ملف HTML المصيَّر حتى إن لم يحتوي ذلك السطر على نص لطباعته فيه، لذا وجب توفير آلية للتحكم بتلك الأسطر والمسافات الفارغة.

الوسوم Tags

وسوم التحكم في تدفق وسير التنفيذ في Liquid

يعرض وسوم التحكم في تدفق وسير التنفيذ Control flow tags التي تحدّد تنفيذ كتل شيفرة Liquid أم لا وتتحكم في تدفق سير تنفيذ شيفرة Liquid.

وسوم التكرار Iteration في Liquid

يعرض الوسوم التكرارية التي تحويها Liquid والتي تنفِّذ كتلًا من الشيفرة تكراريًا.

وسوم القالب Template tags

يعرض الوسوم الخاصة بالقالب التي تحويها Liquid والتي تخبر لغةَ Liquid بمكان تعطيل معالجة التعليقات أو الشيفرة التي ليست تابعة للغة Liquid، وكيفية إنشاء علاقات بين ملفات القوالب.

وسوم المتغيرات في Liquid

يعرض الوسوم الخاصة بالمتغيرات التي تنشئ متغيرات Liquid جديدة.

المرشحات Filters

يعرض هذا القسم كل المرشحات الموجودة في Liquid، وسنسردها ضمن قائمة لسهولة الوصول إليها:

abs

يعيد هذا المرشّح قيمة العدد المطلقة.

append

يضيف هذا المرشّح سلسلة نصية محدَّدة إلى نهاية سلسلة نصية أخرى.

at_least

يحدّد قيمة عددٍ ما بالقيمة الدنيا.

at_most

يحدّد قيمة عددٍ ما بالقيمة العليا.

capitalize

يجعل هذا المرشّح الحرف الأول من سلسلة نصية باللغة الإنجليزية حرفًا كبيرًا ويحوّل الأحرف المتبقية إلى أحرف صغيرة.

ceil

يقرّب هذا المرشّح الدخل إلى أقرب وأكبر عدد صحيح، إذ تحاول لغة Liquid تحويل الدخل إلى عدد قبل تطبيق المرشّح.

compact

يزيل هذا المرشّح أي قيم nil من المصفوفة.

concat

يربط هذا المرشّح (أو يضم معًا) مصفوفات متعددة، إذ تحتوي المصفوفة الناتجة على جميع العناصر من مصفوفات الدخل.

date

يحوّل هذا المرشّح علامة زمنية timestamp إلى تنسيق تاريخ date آخر.

default

يضبط قيمة افتراضية للمتغير الذي لا يملك قيمة مُسنَدة.

divided_by

يقسم هذا المرشّح عددًا على عددٍ آخر.

downcase

يجعل هذا المرشّح كل حرف في سلسلة نصية بحالة الأحرف الصغيرة، وليس له تأثير على السلاسل النصية التي تتكون من أحرف صغيرة مسبقًا.

escape

يطبّق هذا المرشّح عملية الهروب على سلسلة نصية.

escape_once

يطبّق عملية الهروب على سلسلة نصية بدون تغيير الكيانات المُطبَّق عليها الهروب مسبقًا.

first

يعيد هذا المرشّح العنصر الأول من مصفوفة.

floor

يقرّب هذا المرشّح الدخل إلى أقرب وأصغر عدد صحيح.

join

يدمج هذا المرشّح العناصر الموجودة في مصفوفة ضمن سلسلة نصية واحدة باستخدام وسيطه كفاصل بينها.

last

يعيد هذا المرشّح العنصر الأخير من مصفوفة.

lstrip

يزيل هذا المرشّح كل المسافات (مسافات tab والمسافات الفارغة والأسطر الجديدة) من جانب السلسلة النصية الأيسر، ولا يؤثر على المسافات بين الكلمات.

map

يُنشئ هذا المرشّح مصفوفة من القيم عن طريق استخراج قيم خاصيةٍ مسمَّاة من كائن آخر.

minus

يطرح عددًا من عدد آخر.

modulo

يعيد هذا المرشّح الباقي من عملية قسمة.

newline_to_br

يدخل هذا المرشّح الفاصل السطري (<br /‎>) الخاص بلغة HTML أمام كل سطر جديد (‎\n) في سلسلة نصية.

plus

يجمع هذا المرشّح عددين.

prepend

يضيف هذا المرشّح سلسلة نصية محدَّدة إلى بداية سلسلة نصية أخرى.

remove

يزيل كل ظهور لسلسلة نصية فرعية محدَّدة من سلسلة نصية.

remove_first

يزيل الظهور الأول فقط لسلسلة نصية فرعية محدَّدة من سلسلة نصية.

replace

يستبدل هذا المرشّح كلَّ ظهور لوسيطه الأول في سلسلة نصية بوسيطه الثاني.

replace_first

يستبدل الظهور الأول فقط لوسيطه الأول في سلسلة نصية بوسيطه الثاني.

reverse

يعكس هذا المرشّح ترتيب العناصر في مصفوفة، ولكن لا يمكنه عكس سلسلة نصية.

round

يُستخدَم لتقريب عدد إلى أقرب عدد صحيح أو إلى العدد المُمرَّر كوسيط الذي يمثل عدد المنازل العشرية.

rstrip

يزيل كل المسافات (مسافات tab والمسافات الفارغة والأسطر الجديدة) من جانب السلسلة الأيمن، ولا يؤثر على المسافات بين الكلمات.

size

يعيد هذا المرشّح عدد المحارف في سلسلة نصية أو عدد العناصر في مصفوفة.

slice

يعيد هذا المرشّح سلسلة نصية فرعية مؤلفة من محرف واحد أو يعيد سلسلة من عناصر المصفوفة التي تبدأ بالفهرس المحدَّد باستخدام الوسيط الأول.

sort

يرتب هذا المرشّح عناصر المصفوفة بترتيب حسّاس لحالة الأحرف.

sort_natural

يرتب العناصر في مصفوفة بترتيب غير حساس لحالة الأحرف.

split

يقسم هذا المرشّح سلسلة نصية إلى مصفوفة باستخدام وسيطه كفاصل بين العناصر، حيث يُستخدَم المرشّح split لتحويل العناصر المفصول بينها بفواصل من سلسلة نصية إلى مصفوفة.

strip

يزيل هذا المرشّح كل المسافات (مسافات tabs والمسافات الفارغة والأسطر الجديدة) من جانبي السلسلة النصية الأيسر والأيمن، ولا يؤثر على المسافات بين الكلمات.

strip_html

يزيل وسوم لغة HTML من سلسلة نصية.

strip_newlines

يزيل محارف الأسطر الجديدة (فواصل الأسطر) من سلسلة نصية.

times

يضرب عددًا بعدد آخر.

truncate

يقتطع سلسلة نصية وصولًا إلى عدد المحارف الذي مُرِّر كوسيط.

truncatewords

يقصّر هذا المرشّح من طول السلسلة النصية وصولًا إلى عدد الكلمات الممرَّرة كوسيط.

uniq

يزيل العناصر المكرَّرة في المصفوفة.

upcase

يجعل هذا المرشّح كل حرف في السلسلة النصية حرفًا كبيرًا، وليس له أي تأثير على السلاسل النصية التي تتكوّن كلها من أحرف كبيرة مسبقًا.

url_decode

يفك هذا المرشّح تشفير سلسلة نصية مُشفَّرة كعنوان URL أو مُشفَّرة باستخدام المرشّح url_encode.

url_encode

يحوّل محارف عنوان URL غير آمن في سلسلة نصية إلى محارف مُشفَّرة كنسبة مئوية.

where

ينشئ هذا المرشّح مصفوفة تتضمن فقط الكائنات التي تملك قيمة خاصية معينة، أو أي قيمة صحيحة truthy افتراضيًا.

مصادر