Twig/macro

إذا أردت فهم طبيعة الشيفرات الجامعة macros في محرك القوالب Twig فانظر الدوال في لغات البرمجة العادية إذ هما متقاربتان في الوظيفة، وهذه الشيفرات الجامعة مفيدة في إعادة استخدام أجزاء القالب كي لا نعيد اختراع العجلة ونكرر شيفرات موجودة مسبقًا. تعرَّف الشيفرات الجامعة في قوالب عادية. تخيل أن لديك قالبًا مساعدًا ما يعرِّف كيفية تصيير render استمارات HTML من خلال الشيفرات الجامعة واسمه forms.html:

{% macro input(name, value, type = "text", size = 20) %}
    <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
{% endmacro %}

{% macro textarea(name, value, rows = 10, cols = 40) %}
    <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea>
{% endmacro %}

من الممكن لكل شيفرة جامعة أن يكون لها قيمة افتراضية -وهي text هنا كقيمة افتراضية لـ type إذا لم يزودنا بها الاستدعاء-، لكن الشيفرات الجامعة تختلف عن دوال PHP في بضعة أمور:

• وسائط arguments الشيفرات الجامعة تكون اختيارية دومًا.
• إذا مررنا وسائط تموضع positionalإضافية إلى شيفرة جامعة فستذهب إلى المتغير الخاص varargs كقائمة من القيم.

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

تستطيع تمرير السياق كله كوسيط من خلال استخدام المتغير الخاص ‎_context.

استيراد الشيفرات الجامعة

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

يستخدم المثال التالي وسم import ليستورد كل الشيفرات الجامعة من قالب ما:

{% import "forms.html" as forms %}

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

<p>{{ forms.input('username') }}</p>
<p>{{ forms.input('password', null, 'password') }}</p>

توجد طريقة أخرى عبر استيراد الأسماء من القالب إلى فضاء الاسم الحالي namespace من خلال وسم from:

{% from 'forms.html' import input as input_field, textarea %}

<p>{{ input_field('password', '', 'password') }}</p>
<p>{{ textarea('comment') }}</p>

حين تكون استخدامات الشيفرة الجامعة والتعريفات في نفس القالب فلا تحتاج إلى استيراد الشيفرات بما أنها متاحة تلقائيًا في المتغير الخاص ‎_self:

<p>{{ _self.input('password', '', 'password') }}</p>

{% macro input(name, value, type = "text", size = 20) %}
    <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/>
{% endmacro %}

قواعد الشيفرات الجامعة

إن القواعد الحاكمة للشيفرات الجامعة هي نفسها سواء استوردتها باستخدام import أو from، فالشيفرات الجامعة المستوردة تكون دائمًا محلية للقالب الحالي، وهذا يعني أنها متاحة في جميع الكتل والشيفرات الجامعة الأخرى المعرَّفة في القالب الحالي لكنها تكون غير متاحة في القوالب المدرَجة أو الفرعية، بل تحتاج إلى إعادة استيرادها صراحة إلى كل قالب منها. كذلك لا تكون الشيفرات الجامعة المستوردة متاحة في متن وسوم embed، بل تحتاج إلى إعادة استيرادها صراحة داخل الوسم.

عند استدعاء import أو from من وسم block فإن الشيفرات الجامعة المستوردة تكون معرَّفة في الكتلة الحالية فقط، وتتخطى الشيفرات الجامعة المعرفة بنفس الأسماء على مستوى القالب.

التحقق من تعريف شيفرة جامعة

يمكن التحقق مما إذا كانت شيفرة جامعة معرفة أم لا باستخدام اختبار defined:

{% import "macros.twig" as macros %}

{% from "macros.twig" import hello %}

{% if macros.hello is defined -%}
    OK
{% endif %}

{% if hello is defined -%}
    OK
{% endif %}

وسوم النهاية للشيفرات الجامعة المسماة

يسمح لك Twig أن تضع اسم الشيفرة الجامعة بعد وسم النهاية من أجل تيسير القراءة، ويجب أن يطابق الاسم الذي يلي كلمة endmacro اسم الشيفرة الجامعة:

{% macro input() %}
    ...
{% endmacro input %}

انظر أيضًا

• مقدمة عن محرك القوالب Twig
• الوسوم في Twig

المصادر

• صفحة الوسم macro في توثيق Twig الرسمي