كيفية بناء القوالب عبر تويغ Twig

يقدم تويغ تقنيات أكثر بكثير مما تم شرحه في المقالين السابقين، مدخل إلى محرك القوالب تويغ Twig، وانطلاقة سريعة مع محرك القوالب تويغ. إذ يتألف القالب في تويغ من أربع فئات أساسية هي: الوسوم والمرشحات والدوال والاختبارات، وهو ما سنتحدث عنه في هذا المقال.

الوسوم Tags في تويغ

الوسوم في Twig هي الأوامر التي تستخدم في صيغة افعل شيئا ما

{%    %}

وهي بنيات تحكم، تتحكم في طريقة عمل القوالب وسيرها، فيعد كل من if و for التي تحدثنا عنها في المقال السابق انطلاقة سريعة مع محرك القوالب تويغ، نوعًا من الوسوم في تويغ ولكنها ليست الوحيدة المتاحة هناك حوالي 20 وسمًا مختلفًا في تويغ يمكنك الاطلاع عليها في الرابط التالي ولن نتناول كل تلك الوسوم فالهدف من هذه المقالات هو تمكين القارئ من المضي قدمًا في تويغ وليس الإحاطة بكل ما فيه من تقنيات.

نذكر أن كل وسم في تويغ يحتاج إلى كتلة إغلاق للوسم وتتكون وتكون كتلة الإغلاق:

{% endtag %}

حيث تتبع end باسم الوسم دون فراغ. مثلا يحتاج الوسم if إلى كتلة الإغلاق {% endif %} ويحتاج الوسم for إلى كتلة الإغلاق {% endfor %} وهكذا.

الوسم set والمتغيرات الداخلية في القالب

يمكننا أن نعرف متغير ما داخل القالب نفسه باستخدام الوسم set مثلا في السطر التالي تم تعريف المتغير student، وتم إسناد القيمة ziad له:

{% set student = 'ziad' %}
    Hello {{ student }}
{# output: Hello ziad #}

يمكن للمتغير أن يكون رقما أو نصا أو مصفوفة، مثل:

{% set age = 20 %}
{% set colors = ['red', yellow'] %}

هناك طريقة ثانية في تويغ لإسناد قيمة للمتغير وهي على النحو التالي:

{% set student %}
    Ziad
{% endset %}

لاحظ في الطريقة الأولى أننا تضع علامة المساواة بعد اسم المتغير ثم نضع بعدها قيمة المتغير أما في الطريقة الثانية فإننا نغلق تعليمة تعريف المتغير ثم نكتب قيمته ثم نضع عبارة {% endset %}.

الوسم include

يُستخدَم الوسم include لإدراج محتويات قالب آخر ضمن القالب الحالي مما يتيح لنا تقسيم الملفات أو إعادة استخدام أجزاء منها، فيمكن أيضا إدراج محتويات أي ملف نصي عادي أيضًا وليس فقط ملف تويغ.

لنفرض مثلًا أننا نريد أن نكتب صفحات ويب ونريد اختصار الجهد بتفادي كتابة ترويسة html في كل صفحة عندها ننشئ ملف نسميه header.twig:

{# file name: header.twig #}
<!doctype html>
<html>
<head>
    <meta charset="utf-8" />
    <title>{{ title }}</title>
</head>
<body>
<h1>{{ title }}</h1>

بعد ذلك يمكننا كتابة أي صفحة نريدها على النحو التالي:

{# كتابة صفحة بطريقة سريعة #}
{% include ‘header.twig’ %}
My 1st article
</body>
</html>

يمكننا أيضا أن نمرر متغير إلى ملف الترويسة بحيث نحدد عنوان صفحة ويب:

{# تمرير متغير إلى الملف المطلوب إدراجه #}
{% include ‘header.twig’ with {'title': 'My 1st page'} %}
My 1st article
</body>
</html>

يمكننا أيضا تخزين محتويات الملف في متغير ما، لنفرض أننا قمنا بكتابة وصف عام للشركة في ملف نصي ثم نريد أن نستخدم هذا الوصف كقيمة لمتغير داخلي في قالب تويغ:

{# خزن ملف نصي في متغير #}
{% set description %}
    {% include ‘description.txt’ %}
{% endset %}
{# or #}
{% set description = include('description.txt') %}

لمزيد من المعلومات عن الوسوم في تويغ يمكن زيارة صفحة الوسوم على موسوعة حسوب.

ما هي المرشحات في تويغ

تقوم المرشحات في تويغ بمعالجة البيانات قبل عرضها أو قبل إسنادها إلى متغير داخلي أما البيانات نفسها فلا تتأثر محتوياتها وتبقى كما هي، وتستخدم في صيغة أظهر شيء ما {{ }} حيث نضع بعد اسم المتغير | ثم نكتب المرشح المطلوب استخدامه، انظر إلى المثال التالي:

{% set student = 'ziad' %}
Welcome {{ student|upper }}
Hello {{ student }}
{# outputs:
   Welcome ZIAD
   Hello ziad #}

المثال السابق يُستخدم المرشح upper لجعل الأحرف كبيرة قبل إظهار قيمة المتغير name، مع ملاحظة أن القيم المخزنة في المتغير لم تتغير بل بقيت كما هي عندما تم استدعائها مرة ثانية دون المرشح السابق.

يمكننا أيضا استخدام الوسم apply للتعامل مع المرشحات على النحو التالي:

{% apply upper %}
    Hello ziad
{% endapply %}
{# output: HELLO ZIAD #}

وباختصار عندما نستدعي أي مرشح في تويغ فإنه يمرر قيمة المتغير ويستخدمه كمدخل لعملية محددة ثم يظهر لنا نتيجة تلك العملية.

المرشحات upper وlower وcapitalizes

لقد شاهدنا أن المرشح upper يقوم بتحويل النص إلى الحروف الكبيرة بينما المرشح lower يعطي النص مكتوبًا بالحروف الصغيرة أما capitalizes فهو يحول أول حرف من الجملة فقط إلى حرف كبير:

{{ 'my first car'|capitalize }}
{# outputs 'My first car' #}

مرشح التنسيق Format

يقوم المرشح format بوضع نص محدد بدلا عن نائب النص s% انظر مثلًا:

{{ "Hello student %s"|format('Ziad') }}
{# output: Hello student Ziad #}

مرشح هروب الأمان Escape

يعد من أهم المرشحات حيث يستخدم للتخلص من أية وسوم قد تسبب مشاكل في الإظهار ويفضل استخدامه دوما مع المتغيرات النصية. يمكن اختصار استخدام المرشح escape إلى e حيث يمكن كتابته على النحو التالي:

{# escape for Html safty #}
<div>{{ description|e }}</div>

كما يمكن كتابته على النحو التالي أيضًا:

{# escape for Html safty #}
<div>{{ description|escape }}</div>

يمكن تمرير وسيط للمرشح السابق لتحديد نوع يناسب المكان الذي سوف يظهر به المتغير مثال:

{# escape for js safety #}
<script>
    function getDescription() {
      return {{ description|e('js') }};
    }
</script>

{# escape for css safety #}
<style>
    {{ mystyles|e('css') }}
</style>

لمزيد من المعلومات عن هذا المرشح وبقية المرشحات، يمكن زيارة توثيق المرشحات في موسوعة حسوب.

الدوال في تويغ

الدوال في تويغ هي مجموعة من التعليمات البرمجية التي تؤدي مهمة ما ينتج عنها قيمة. يمكن استدعاء الدالة وإعادة استخدامها عدة مرات.

نستدعي الدوال عن طريق كتابة أسمائها متبوعة بأقواس، ويمكن أن نمرر لها وسيطًا واحدًا أو أكثر داخل تلك الأقواس وذلك بهدف تمرير المعلومات إلى الدالة.

كمثال الدالة range تعيد مصفوفة تحتوي على أعداد صحيحة محصورة بين رقمين:

{% for i in range(0, 3) %}
    {{ i }},
{% endfor %}
{# outputs 0, 1, 2, 3, #}

عند استدعاء الدالة السابقة نقوم بتمرير ثلاث وسطاء لها، الوسيط الأول هو بداية المجال والثاني نهاية المجال وأما الوسيط الثالث فهو الخطوة أو الفارق بين رقمين في المجال وهو اختياري.

الوسم والدالة block

في تويغ يمكن أن يكون لدينا دالة لها ذات الاسم المستخدم للوسم، فالكلمة block في تويغ قد تشير إلى الوسم block، كما قد تشير إلى الدالة block ويمكن التمييز بين الحالتين بسهولة عبر المثال التالي:

<html>
<head>
<title>
{% block title %}
    Hello Twig
{% endblock %}
</title>
</head>
<body>
<h1>{{ block('title') }}</h1>
</body>
</html>

نلاحظ أن الوسم يكون ضمن صيغة افعل شيئا ما {% %} ويستخدم لتعريف الكتلة وتحديد محتوياتها بينما الدالة تكون ضمن صيغة أظهر شيئا ما {{ }} يتم اتباعها بقوسين يوجد بينهما وسيط يمرر للدالة حيث تستخدم الدالة block لإظهار محتويات كتلة سبق أن تم تعريفها بالوسم block.

المرشح والدالة date

يقوم المرشح date بتغير تنسيق التاريخ عند إظهار قيمة متغير ما حسب الصيغة المعطاة له

{{ birth|date("m/d/Y") }

أما الدالة date فإنها تعيد التاريخ الحالي عند استدعائها بدون وسطاء:

{{ date() }}
{# تظهر التاريخ الحالي #}

يمكن أن تمرر وسيط للدالة date ويمكن لقيمة الوسيط أن تكون تعبير نصي عن التاريخ مثلا النص "2022/01/01" يحول إلى التاريخ المقابل له كما يمكن أن يكون فرق بالتاريخ عن التاريخ الحالي:

{{ date('2022/01/01') }}
{# تعيد التاريخ المحدد 2022/01/01 #}
{{ date('-2days') }}
{# تعيد التاريخ الحالي مطروح منه يومين #}

يمكن أن نمرر لها وسيطين حيث يحوي الوسيط الثاني على المنطقة الزمنية التي سوف يكون التاريخ فيها:

{{ date('-2days', 'Europe/Paris') }}

يمكن موازنة التواريخ المعادة بواسط تعبير شرطي:

{% if post.date > date('-30days') %}
    This is a new post
{% endif %}

الفرق بين المرشح والدالة

تتصف المرشحات في تويغ بالخصائص التالية:

المرشحات مخصصة لمعالجة البيانات
المرشح يعيد قيمة دوما
القيمة التي يعيدها المرشح تكون نص دومًا
يأخذ المرشح وسيط واحد أو أكثر
يكتب الوسيط الأول قبل المرشح ويوضع بينهما | مثال:

{{ student|upper }}

عندما يحتاج إلى وسيط واحد لا يتم إتباعها بأقواس
عندما يحتاج أكثر من وسيط يتم اضافة قوسين بعد اسم المرشح مع وضع الوسيط بينهما

{{ description|escape('html') }}

يرجى ملاحظة أن الوسيط الأول هو المتغير نفسه الذي يأتي قبل علامة | أما ما بين ' ' فهو الوسيط الثاني.

أما الدوال، فتتصف بالخصائص التالية:

الدوال مخصصة لإعادة قيمة غير مرتبطة بالبيانات عادة
يمكن أن تكون القيمة تعيدها الدالة نصا أو رقما أو تاريخا أو مصفوفة
الدوال في تويغ تعيد قيمة دوما وهذا يختلف عن تعريف الدوال في لغات البرمجة
يمكن للدوال أن لا تأخذ أي وسيط ويمكن أن تأخذ وسيط واحد أو أكثر
حتى عندما لا تأخذ الدالة أي وسيط فإنها تتبع بأقواس

{{ date() }}

عندما تحتاج الدالة إلى وسيط واحد أكثر فإنها تمرر إليها بين الأقواس:

{% set list = range(1, 6) %}

الاختبارات في تويغ

الاختبارات في تويغ هي عبارة عن عوامل تختبر قيمة متغير ما وتستخدم على النحو التالي:

{% if line is odd %}
.......
{% endif %}

حيث تستخدم مع عبارة is و تتحق من كون المتغير يحقق شرط محدد والاختبارات المعرفة مسبقا في تويغ هي:

defined, divisible by, even, iterable, odd, same as

لمزيد من المعلومات عن الاختبارات يمكن الرجوع إلى صفحة الاختبارات في موسوعة حسوب.

ختامًا

لقد تحدثنا في هذا المقال عن مكونات تويغ من وسوم ومرشحات ودوال واختبارات وهي المكونات الأساسية التي يقوم عليها القالب، وفي المقال القادم سوف نقوم بالتطبيق العملي على ما تعلمناه حيث نتعلم إنشاء قالب فرعي لووردبرس باستخدام تويغ.