الفرق بين المراجعتين لصفحة: «Twig/macro»
أسامه-دمراني (نقاش | مساهمات) إدخال 2.0 تمام المحتوى وانظر أيضًا والتصانيف والمصادر. |
جميل-بيلوني (نقاش | مساهمات) طلا ملخص تعديل |
||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE: الوسم macro في Twig}}</noinclude> | <noinclude>{{DISPLAYTITLE: الوسم macro في Twig}}</noinclude> | ||
إذا أردت فهم طبيعة الشيفرات الجامعة (macros) في محرك القوالب Twig فانظر الدوال في لغات البرمجة العادية إذ هما متقاربتان في الوظيفة، وهذه الشيفرات الجامعة مفيدة في إعادة استخدام أجزاء القالب كي لا نعيد اختراع العجلة ونكرر شيفرات موجودة مسبقًا. تعرَّف الشيفرات الجامعة في قوالب عادية. تخيل أن لديك قالبًا مساعدًا ما يعرِّف كيفية تصيير (render) استمارات [[HTML]] من خلال الشيفرات الجامعة واسمه <code>forms.html</code>: | |||
{{DISPLAYTITLE: الوسم macro في Twig}}<syntaxhighlight lang="twig"> | |||
{% macro input(name, value, type = "text", size = 20) %} | {% macro input(name, value, type = "text", size = 20) %} | ||
<input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/> | <input type="{{ type }}" name="{{ name }}" value="{{ value|e }}" size="{{ size }}"/> | ||
| سطر 8: | سطر 9: | ||
<textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea> | <textarea name="{{ name }}" rows="{{ rows }}" cols="{{ cols }}">{{ value|e }}</textarea> | ||
{% endmacro %} | {% endmacro %} | ||
</syntaxhighlight>من الممكن لكل شيفرة جامعة أن يكون لها قيمة افتراضية -وهي <code>text</code> هنا كقيمة افتراضية لـ <code>type</code> إذا لم يزودنا بها الاستدعاء-، لكن الشيفرات الجامعة تختلف عن دوال PHP في بضعة أمور: | </syntaxhighlight>من الممكن لكل شيفرة جامعة أن يكون لها قيمة افتراضية -وهي <code>text</code> هنا كقيمة افتراضية لـ <code>type</code> إذا لم يزودنا بها الاستدعاء-، لكن الشيفرات الجامعة تختلف عن دوال [[PHP]] في بضعة أمور: | ||
* وسائط (arguments) الشيفرات الجامعة تكون اختيارية دومًا. | * وسائط (arguments) الشيفرات الجامعة تكون اختيارية دومًا. | ||
* إذا مررنا وسائط تموضع (positional)إضافية إلى شيفرة جامعة فستذهب إلى المتغير الخاص <code>varargs</code> كقائمة من القيم. | * إذا مررنا وسائط تموضع (positional)إضافية إلى شيفرة جامعة فستذهب إلى المتغير الخاص <code>varargs</code> كقائمة من القيم. | ||
ومن الناحية الأخرى فإن الشيفرات الجامعة تشترك مع دوال PHP في أنها ليس لها وصول إلى متغيرات القالب الحالية. | ومن الناحية الأخرى فإن الشيفرات الجامعة تشترك مع دوال [[PHP]] في أنها ليس لها وصول إلى متغيرات القالب الحالية. | ||
تستطيع تمرير السياق كله كوسيط من خلال استخدام المتغير الخاص <code>_context</code>. | تستطيع تمرير السياق كله كوسيط من خلال استخدام المتغير الخاص <code>_context</code>. | ||
| سطر 40: | سطر 41: | ||
== قواعد الشيفرات الجامعة == | == قواعد الشيفرات الجامعة == | ||
إن القواعد الحاكمة للشيفرات الجامعة هي نفسها سواء استوردتها باستخدام import أو | إن القواعد الحاكمة للشيفرات الجامعة هي نفسها سواء استوردتها باستخدام <code>[[Twig/import|import]]</code> أو <code>[[Twig/from|from]]</code>، فالشيفرات الجامعة المستوردة تكون دائمًا محلية للقالب الحالي، وهذا يعني أنها متاحة في جميع الكتل والشيفرات الجامعة الأخرى المعرَّفة في القالب الحالي لكنها تكون غير متاحة في القوالب المدرَجة أو الفرعية، بل تحتاج إلى إعادة استيرادها صراحة إلى كل قالب منها. كذلك لا تكون الشيفرات الجامعة المستوردة متاحة في متن وسوم <code>[[Twig/embed|embed]]</code>، بل تحتاج إلى إعادة استيرادها صراحة داخل الوسم. | ||
عند استدعاء <code>import</code> أو <code>from</code> من وسم <code>[[Twig/block|block]]</code> فإن الشيفرات الجامعة المستوردة تكون معرَّفة في الكتلة الحالية فقط، وتتخطى الشيفرات الجامعة المعرفة بنفس الأسماء على مستوى القالب. | عند استدعاء [[Twig/import|<code>import</code>]] أو [[Twig/from|<code>from</code>]] من وسم <code>[[Twig/block|block]]</code> فإن الشيفرات الجامعة المستوردة تكون معرَّفة في الكتلة الحالية فقط، وتتخطى الشيفرات الجامعة المعرفة بنفس الأسماء على مستوى القالب. | ||
== التحقق من تعريف شيفرة جامعة == | == التحقق من تعريف شيفرة جامعة == | ||
يمكن التحقق مما إذا كانت شيفرة جامعة معرفة أم لا باستخدام اختبار defined:<syntaxhighlight lang="twig"> | يمكن التحقق مما إذا كانت شيفرة جامعة معرفة أم لا باستخدام اختبار <code>[[Twig/defined|defined]]</code>:<syntaxhighlight lang="twig"> | ||
{% import "macros.twig" as macros %} | {% import "macros.twig" as macros %} | ||
| سطر 68: | سطر 69: | ||
== انظر أيضًا == | == انظر أيضًا == | ||
* [[Twig/intro|مقدمة عن محرك القوالب Twig | * [[Twig/intro|مقدمة عن محرك القوالب Twig]] | ||
* [[Twig/tags|الوسوم في Twig | * [[Twig/tags|الوسوم في Twig]] | ||
== المصادر == | == المصادر == | ||
[https://twig.symfony.com/doc/3.x/tags/macro.html#macros-scoping صفحة الوسم macro في توثيق Twig الرسمي | |||
* [https://twig.symfony.com/doc/3.x/tags/macro.html#macros-scoping صفحة الوسم macro في توثيق Twig الرسمي] | |||
[[تصنيف:Twig]] | [[تصنيف:Twig]] | ||
[[تصنيف:Twig Tags]] | [[تصنيف:Twig Tags]] | ||
مراجعة 16:05، 5 مايو 2021
إذا أردت فهم طبيعة الشيفرات الجامعة (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 %}