الوسم include في Twig
تتضمن تعليمة include قالبًا وتخرِج المحتوى المصيَّر (rendered) لذلك الملف:
{% include 'header.html' %}
Body
{% include 'footer.html' %}
لاحظ أنه يُنصح باستخدام دالة include بما أنها توفر نفس المزايا مع مرونة أكبر، وذلك لما يلي:
- دالة
includeهي أصح دلاليًا، إذ أن تضمين قالب يخرج محتوياته المصيَّرة في النطاق الحالي، أما الوسم فيجب ألا يعرض شيئًا. - دالة
includeأكثر قابلية للتركيب (composable):
{# خزن قالبًا مصيَّرًا في متغير #}
{% set content %}
{% include 'template.html' %}
{% endset %}
{# vs #}
{% set content = include('template.html') %}
{# طبق الفلتر على قالبٍ مصيَّر #}
{% apply upper %}
{% include 'template.html' %}
{% endapply %}
{# vs #}
{{ include('template.html')|upper }}
- لا تقترح دالة
includeأي ترتيب للوسائط وذلك بسبب الوسائط المسماة (named arguments).
تستطيع القوالب المضمنّة أن تصل إلى متغيرات السياق النشط، وإذا كنت تستخدم محمِّل نظام الملفات فإن القوالب التي يُبحث عنها في المسارات التي يعرّفها، كذلك تستطيع إضافة متغيرات إضافية من خلال تمريرها بعد كلمة with المفتاحية:
{# وصول إلى المتغيرات التي في السياق الحالي template.html سيكون لملف
والسياقات الإضافية المتوفرة #}
{% include 'template.html' with {'foo': 'bar'} %}
{% set vars = {'foo': 'bar'} %}
{% include 'template.html' with vars %}
كلمة only المفتاحية تعطل الوصول إلى السياق:
{# foo لن يوصَل إلا إلى المتغير #}
{% include 'template.html' with {'foo': 'bar'} only %}
{# لا يمكن الوصول إلى أي متغير #}
{% include 'template.html' only %}
يجب أن تضع القالب المنشأ بواسطة مستخدم آخر داخل صندوق اختبار أولًا قبل إدراجه، انظر صفحة Twig للمطورين في هذا، وتوثيق وسم sandbox. اسم القالب يمكن أن يكون أي تعبير Twig صالح:
{% include some_var %}
{% include ajax ? 'ajax.html' : 'not_ajax.html' %}
إذا كان التعبير يقيَّم إلى \Twig\Template أو إلى نسخة من \Twig\TemplateWrapper فإن Twig سيستخدمه مباشرة:
// {% include template %}
$template = $twig->load('some_template.twig');
$twig->display('template.twig', ['template' => $template]);
يمكن تمييز الإدراج باستخدام ignore missing التي تجعل Twig يهمل التعليمة إذ كان القالب الذي سيدرَج غير موجود، ويجب أن توضع بعد اسم القالب، انظر:
{% include 'sidebar.html' ignore missing %}
{% include 'sidebar.html' ignore missing with {'foo': 'bar'} %}
{% include 'sidebar.html' ignore missing only %}
كما يمكن توفير قائمة من القوالب التي يُتحقق من تواجدها قبل الإدراج، ويُدرَج أول قالب موجود:
{% include ['page_detailed.html', 'page.html'] %}
إذا أضفنا ignore missing إلى تعليمة include فلن يصيّر شيئًا إذا لم يكن ثمة قوالب موجودة ولن تعرض شيئًا، أما إذا لم نضفه فسيُرفع اعتراض عند عدم وجود قالب.