|
|
سطر 1: |
سطر 1: |
− | <noinclude>{{DISPLAYTITLE: الفلتر default في Twig}}</noinclude> | + | <noinclude>{{DISPLAYTITLE: المرشح default في Twig}}</noinclude> |
− | يع{{DISPLAYTITLE: الفلتر default في Twig}}يد المرشح default القيمة الافتراضية الممررة إليه إذا كانت غير معرفة أو فارغة، وإلا فإنه يعيد قيمة المتغير:<syntaxhighlight lang="twig">
| + | يعيد المرشح default القيمة الافتراضية الممررة إليه إذا كانت غير معرفة أو فارغة، وإلا فإنه يعيد قيمة المتغير: |
| + | <syntaxhighlight lang="twig"> |
| {{ var|default('var is not defined') }} | | {{ var|default('var is not defined') }} |
| | | |
سطر 8: |
سطر 9: |
| | | |
| {{ ''|default('passed var is empty') }} | | {{ ''|default('passed var is empty') }} |
− | </syntaxhighlight>إذا استُخدم default على تعبير يستخدم المتغيرات في بعض استدعاءات التوابع فتأكد أن تستخدمه في كل حالة يكون المتغير فيها غير معرف:<syntaxhighlight lang="twig"> | + | </syntaxhighlight> |
| + | إذا استُخدم <code>default</code>على تعبير يستخدم المتغيرات في بعض استدعاءات التوابع فتأكد أن تستخدمه في كل حالة يكون المتغير فيها غير معرف: |
| + | <syntaxhighlight lang="twig"> |
| {{ var.method(foo|default('foo'))|default('foo') }} | | {{ var.method(foo|default('foo'))|default('foo') }} |
− | | + | </syntaxhighlight> |
− | </syntaxhighlight>قد يطلِق استخدام المرشح <code>default</code> على قيمة بوليانية سلوكًا غير متوقع، وذلك لأن <code>false</code> تعامَل كقيمة فارغة، وعندئذ استخدم <code>??</code>:<syntaxhighlight lang="twig"> | + | قد يطلِق استخدام المرشح <code>default</code> على قيمة بوليانية سلوكًا غير متوقع، وذلك لأن <code>false</code> تعامَل كقيمة فارغة، وعندئذ استخدم <code>??</code>: |
| + | <syntaxhighlight lang="twig"> |
| {% set foo = false %} | | {% set foo = false %} |
| {{ foo|default(true) }} {# true #} | | {{ foo|default(true) }} {# true #} |
| {{ foo ?? true }} {# false #} | | {{ foo ?? true }} {# false #} |
| </syntaxhighlight> | | </syntaxhighlight> |
| + | ==الوسائط== |
| + | * <code>default</code>: القيمة الافتراضية. |
| | | |
− | == الوسائط == | + | == انظر أيضًا == |
− | default: القيمة الافتراضية
| + | * [[Twig/intro|مقدمة عن محرك القوالب Twig.]] |
− | ----
| + | * [[Twig/advanced|توسيع Twig.]] |
− | | + | * [[Twig/internals|المكونات الداخلية لـ Twig.]] |
| + | * [[Twig/tags|الوسوم في Twig]] |
| + | * [[ Twig/filters|المرشحات في Twig]] |
| + | == المصادر == |
| + | * [https://twig.symfony.com/doc/3.x/filters/default.html صفحة المرشح default في توثيق Twig الرسمي]. |
| | | |
− | <nowiki><noinclude>{{DISPLAYTITLE: المرشح escape في Twig}}</nowiki><nowiki></noinclude></nowiki>
| + | [[تصنيف:Twig]] |
− | | + | [[تصنيف:Twig Filters]] |
− | يهرِّب المرشح escape سلسلة نصية باستخدام خطط تعتمد على السياق، وهي تستخدم خطة تهريب HTML افتراضيًا:<syntaxhighlight lang="twig">
| |
− | <p>
| |
− | {{ user.username|escape }}
| |
− | </p>
| |
− | </syntaxhighlight>يعرَّف المرشح باسم بديل هو <code>e</code> من أجل التيسير وتوفير الوقت:<syntaxhighlight lang="twig">
| |
− | <p>
| |
− | {{ user.username|e }}
| |
− | </p>
| |
− | </syntaxhighlight>يمكن استخدام المرشح escape في سياقات أخرى كذلك غير HTML مستفيدين من وسيط اختياري يعرّف خطة التهريب التي يجب استخدامها:<syntaxhighlight lang="twig">
| |
− | {{ user.username|e }}
| |
− | {# يكافئ #}
| |
− | {{ user.username|e('html') }}
| |
− | </syntaxhighlight>انظر كيف يمكن تهريب المتغيرات المدرَجة في شيفرة جافاسكربت:<syntaxhighlight lang="twig">
| |
− | {{ user.username|escape('js') }}
| |
− | {{ user.username|e('js') }}
| |
− | | |
− | </syntaxhighlight>يدعم المرشح escape خطط التهريب التالية لمستندات HTML:
| |
− | | |
− | * <code>html</code>: يهرب سلسلة نصية لسياق '''متن HTML.'''
| |
− | * <code>js</code>: تهرب سلسلة نصية لسياق '''جافاسكربت'''.
| |
− | * <code>css</code>: تهرب سلسلة نصية لسياق CSS. يمكن تطبيق تهريب css على أي سلسلة نصية تُدخل في CSS، وتهرِّب كل شيء عدا الأحرف والأرقام.
| |
− | * <code>url</code>: تهرب سلسلة نصية لمحدد الموارد الموحد (URI)، ولا يُدخل إلا مكونٌ فرعي.
| |
− | * <code>html_attr</code>: تهرب سلسلة نصية لسياق '''سمة HTML.'''
| |
− | | |
− | لاحظ أن التهريب السياقي في مستندات HTML يصعب تنفيذه، ويتوقف اختيار خطة التهريب المناسبة على عوامل كثيرة، فانظر توثيقًا مثل [https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.md the OWASP prevention cheat sheet] لتعلم المزيد عن الأمر.<blockquote>لاحظ أن المرشح escape يستخدم دالة [https://secure.php.net/htmlspecialchars htmlspecialchars] الخاصة بلغة PHP من أجل خطة تهريب HTML. </blockquote>انتبه عند استخدام التهريب التلقائي إذ أن Twig يحاول ألا يهرب متغيرًا تهريبًا مضاعفًا (double-escape) إذا كانت خطة التهريب التلقائية هي نفسها التي يستخدمها مرشح escape، لكن ذلك لا يعمل عند استخدام متغير ما كخطة تهريب:<syntaxhighlight lang="twig">
| |
− | {% set strategy = 'html' %}
| |
− | | |
− | {% autoescape 'html' %}
| |
− | {{ var|escape('html') }} {# لن يهرَّب تهريبًا مضاعفًا #}
| |
− | {{ var|escape(strategy) }} {# سيهرَّب تهريبًا مضاعفًا #}
| |
− | {% endautoescape %}
| |
− | </syntaxhighlight>التهريب التلقائي يجب أن يعطَّل عند استخدام متغير كخطة تهريب:<syntaxhighlight lang="twig">
| |
− | {% set strategy = 'html' %}
| |
− | | |
− | {% autoescape 'html' %}
| |
− | {{ var|escape(strategy)|raw }} {# won't be double-escaped #}
| |
− | {% endautoescape %}
| |
− | </syntaxhighlight>
| |
− | | |
− | == المهرِّبات الخاصة ==
| |
− | تستطيع تعريف مهربات خاصة باستدعاء التابع <code>setEscaper()</code> على نسخة توسيع المهرب، ويجب أن يكون أول وسيط هو اسم المهرب ليستَخدم في استدعاء escape، والثاني يجب أن يكون نوع بيانات PHP قابل للاستدعاء "callable":<syntaxhighlight lang="twig">
| |
− | $twig = new \Twig\Environment($loader);
| |
− | $twig->getExtension(\Twig\Extension\EscaperExtension::class)->setEscaper('csv', 'csv_escaper');
| |
− | </syntaxhighlight>عند استدعاء Twig لنوع البيانات callable فإن الأخير يستلم نسخة من بيئة Twig والسلسلة النصية التي يجب تهريبها، ومجموعة محارف (charset).<blockquote>لاحظ أن المهربات لا يمكن تخطيها لأنها تُعد التطبيق الأخير، وكذا من أجل تحسين الأداء.</blockquote>
| |
− | | |
− | == الوسائط ==
| |
− | <code>strategy</code>: خطة التهريب.
| |
− | | |
− | <code>charset</code>: مجموعة محارف السلسلة النصية.
| |
− | | |
− | | |
− | ---
| |
− | | |
− | <nowiki><noinclude>{{DISPLAYTITLE: المرشح filter في Twig}}</nowiki><nowiki></noinclude></nowiki>
| |
− | | |
− | المرشح <code>filter</code> يرشح العناصر من تسلسل أو ربط (mapping) باستخدام دالة سهمية تستقبل القيمة من ذلك التسلسل أو الربط:<syntaxhighlight lang="twig">
| |
− | {% set sizes = [34, 36, 38, 40, 42] %}
| |
− | | |
− | {{ sizes|filter(v => v > 38)|join(', ') }}
| |
− | {# output 40, 42 #}
| |
− | | |
− | </syntaxhighlight>وهو يسمح -مع الوسم <code>for</code>- بترشيح العناصر التي يراد التكرار عليها:<syntaxhighlight lang="twig">
| |
− | {% for v in sizes|filter(v => v > 38) -%}
| |
− | {{ v }}
| |
− | {% endfor %}
| |
− | {# output 40 42 #}
| |
− | </syntaxhighlight>كما يعمل مع الربط أيضًا:<syntaxhighlight lang="twig">
| |
− | {% set sizes = {
| |
− | xs: 34,
| |
− | s: 36,
| |
− | m: 38,
| |
− | l: 40,
| |
− | xl: 42,
| |
− | } %}
| |
− | | |
− | {% for k, v in sizes|filter(v => v > 38) -%}
| |
− | {{ k }} = {{ v }}
| |
− | {% endfor %}
| |
− | {# output l = 40 xl = 42 #}
| |
− | </syntaxhighlight>تستقبل الدالة السهمية المفتاح كوسيط ثاني:<syntaxhighlight lang="twig">
| |
− | {% for k, v in sizes|filter((v, k) => v > 38 and k != "xl") -%}
| |
− | {{ k }} = {{ v }}
| |
− | {% endfor %}
| |
− | {# output l = 40 #}
| |
− | </syntaxhighlight>لاحظ أن الدالة السهمية لها وصول إلى السياق الحالي.
| |
− | | |
− | == الوسائط ==
| |
− | <code>array</code>: التسلسل أو الربط.
| |
− | | |
− | <code>arrow</code>: الدالة السهمية.
| |
− | | |
− | | |
− | ---
| |
− | | |
− | <nowiki><noinclude>{{DISPLAYTITLE: المرشح first في Twig}}</nowiki><nowiki></noinclude></nowiki>
| |
− | | |
− | يعيد المرشح first أول عنصر في تسلسل أو ربط (mapping) أو سلسلة نصية:<syntaxhighlight lang="twig">
| |
− | {{ [1, 2, 3, 4]|first }}
| |
− | {# outputs 1 #}
| |
− | | |
− | {{ { a: 1, b: 2, c: 3, d: 4 }|first }}
| |
− | {# outputs 1 #}
| |
− | | |
− | {{ '1234'|first }}
| |
− | {# outputs 1 #}
| |
− | | |
− | </syntaxhighlight>لاحظ أن هذا المرشح يعمل مع الكائنات التي تستخدم واجهة [https://secure.php.net/manual/en/class.traversable.phphttps://secure.php.net/manual/en/class.traversable.php Traversable].
| |
− | | |
− | | |
− | <nowiki>----</nowiki>
| |
− | | |
− | <nowiki><noinclude>{{DISPLAYTITLE: المرشح format في Twig}}</nowiki><nowiki></noinclude></nowiki>
| |
− | | |
− | يهيئ المرشح format السلسلة النصية باستبدال العناصر النائبة (placeholders) التي تتبع ترميز [https://secure.php.net/sprintf sprintf]. انظر المثال التالي الذي يطبع "I like foo and bar" إذا كان معامِل foo مساويًا لسلسلة foo النصية:<syntaxhighlight lang="twig">
| |
− | {{ "I like %s and %s."|format(foo, "bar") }}
| |
− | | |
− | | |
− | </syntaxhighlight>
| |
− | | |
− | | |
− | ---
| |
− | | |
− | <nowiki><noinclude>{{DISPLAYTITLE: المرشح format_currency في Twig}}</nowiki><nowiki></noinclude></nowiki>
| |
− | | |
− | يهيئ المرشح format_currency العدد ليكون على صيغة العملة:<syntaxhighlight lang="twig">
| |
− | {# €1,000,000.00 #}
| |
− | {{ '1000000'|format_currency('EUR') }}
| |
− | </syntaxhighlight>يمكن تمرير سمات (attributes) من أجل تعديل الخرج:<syntaxhighlight lang="twig">
| |
− | {# €12.34 #}
| |
− | {{ '12.345'|format_currency('EUR', {rounding_mode: 'floor'}) }}
| |
− | | |
− | {# €1,000,000.0000 #}
| |
− | {{ '1000000'|format_currency('EUR', {fraction_digit: 4}) }}
| |
− | </syntaxhighlight>القائمة التالية تحتوي على الخيارات المدعومة:
| |
− | | |
− | * <code>grouping_used</code>.
| |
− | * <code>decimal_always_shown</code>.
| |
− | * <code>max_integer_digit</code>.
| |
− | * <code>min_integer_digit</code>.
| |
− | * <code>integer_digit</code>.
| |
− | * <code>max_fraction_digit</code>.
| |
− | * <code>min_fraction_digit</code>.
| |
− | * <code>fraction_digit</code>.
| |
− | * <code>multiplier</code>.
| |
− | * <code>grouping_size</code>.
| |
− | * <code>rounding_mode</code>.
| |
− | * <code>rounding_increment</code>.
| |
− | * <code>format_width</code>.
| |
− | * <code>padding_position</code>.
| |
− | * <code>secondary_grouping_size</code>.
| |
− | * <code>significant_digits_used</code>.
| |
− | * <code>min_significant_digits_used</code>.
| |
− | * <code>max_significant_digits_used</code>.
| |
− | * <code>lenient_parse</code>.
| |
− | | |
− | يستخدم المرشح الإعدادات المحلية افتراضيًا، ويمكن تمريرها صراحة إليه:<syntaxhighlight lang="twig">
| |
− | {# 1.000.000,00 £ #}
| |
− | {{ '1000000'|format_currency('EGP', locale='eg') }}
| |
− | | |
− | </syntaxhighlight>
| |
− | | |
− | لاحظ أن المرشح <code>format_currency</code> جزء من <code>IntlExtension</code> وهذا لا يكون مثبتًا افتراضيًا، لذا ثبته أولًا:
| |
− | <syntaxhighlight lang="twig">
| |
− | $ composer require twig/intl-extra
| |
− | </syntaxhighlight>
| |
− | ثم ثبت <code>twig/extra-bundle</code> في حالة مشاريع Symfony:
| |
− | <syntaxhighlight lang="twig">
| |
− | $ composer require twig/extra-bundle
| |
− | </syntaxhighlight>
| |
− | أما غير ذلك فأضف التوسيع صراحة إلى بيئة Twig:
| |
− | <syntaxhighlight lang="twig">
| |
− | use Twig\Extra\Intl\IntlExtension;
| |
− | | |
− | $twig = new \Twig\Environment(...);
| |
− | $twig->addExtension(new IntlExtension());
| |
− | </syntaxhighlight>
| |