مستندات قالب‌ها

آخرین تغییر: ۱۰ مرداد ۱۳۹۶

آشنایی

بلاگی قالب‌ها را توسط موتور Twig تفسیر می‌کند. از امکانات Twig می‌توان سینتکس ساده و قابل فهم، فیلترهای متعدد و سرعت بالا را نام برد.

شروع کار با Twig

کار با Twig بسیار آسان بوده و به شما امکان مدیریت کامل قالب وبلاگ را می‌دهد.

نمایش متغیرها

برای نمایش متغیر در Twig از دستور زیر استفاده می‌شود:

{{ variable_name }}

تمامی متغیرها هنگام چاپ شدن به صورت خودکار escape می‌شوند.

برای دسترسی به بخش‌های مختلف یک آرایه از دستورات زیر می‌توان استفاده نمود:

{{ foo.bar }}
{{ foo['bar'] }}

اگر آیتمی از آرایه شامل علامات خاص (مانند - که با علامت منفی اشتباه گرفته می‌شود)، برای نمایش آن از تابع attribute استفاده کنید:

{# equivalent to the non-working foo.data-foo #}
{{ attribute(foo, 'data-foo') }}

تعریف کردن متغیر

با استفاده از تگ set می‌توانید درون کد قالب خود متغیر جدید تعریف کنید:

{% set foo = 'foo' %}
{% set foo = [1, 2] %}
{% set foo = {'foo': 'bar'} %}

شرط‌ها

از تگ if برای عبارات شرطی استفاده می‌شود:

{% if users|length > 0 %}
    <ul>
        {% for user in users %}
            <li>{{ user.username|e }}</li>
        {% endfor %}
    </ul>
{% endif %}

کامنت‌ها

برای کامنت کردن بخشی از کد، از سینتکس {# ... #} استفاده کنید. این کار باعث آسان شدن فرایند عیب‌یابی و افزایش خوانایی کد می‌شود:

{# note: disabled template because we no longer use this
    {% for user in users %}
        ...
    {% endfor %}
#}

مدیریت فضای خالی

از تگ spaceless برای حذف فضاهای خالی بین تگ‌های HTML استفاده می‌شود:

{% spaceless %}
    <div>
        <strong>foo bar</strong>
    </div>
{% endspaceless %}

{# output will be <div><strong>foo bar</strong></div> #}

تگ‌ها

autoescape

با استفاده از تگ autoescape می‌توانید مشخص کنید که چه بخش‌هایی از قالب به صورت خودکار escape شوند:

{% autoescape %}
    Everything will be automatically escaped in this block
    using the HTML strategy
{% endautoescape %}

{% autoescape 'html' %}
    Everything will be automatically escaped in this block
    using the HTML strategy
{% endautoescape %}

{% autoescape 'js' %}
    Everything will be automatically escaped in this block
    using the js escaping strategy
{% endautoescape %}

{% autoescape false %}
    Everything will be outputted as is in this block
{% endautoescape %}

هنگامی که escape خودکار فعال باشد، با استفاده از فیلتر raw می‌توانید متغیر را بدون escape شدن نمایش دهید:

{% autoescape %}
    {{ safe_value|raw }}
{% endautoescape %}

توجه

عبارات ثابت هیچ گاه escape نمی‌شوند:

{% set hello = "<strong>Hello</strong>" %}
{{ hello }}
{{ "<strong>world</strong>" }}

نتیجه‌ی کد بالا "<strong>Hello</strong> world" خواهد بود.

do

تگ do همان کار عبارت معمولی متغیر ({{ ... }}) را انجام می‌دهد، با این تفاوت که چیزی را نمایش نمی‌دهد:

{% do 1 + 2 %}

filter

تگ filter امکان اعمال فیلتر بر روی بخش‌هایی از کد را به شما می‌دهد:

{% filter upper %}
    This text becomes uppercase
{% endfilter %}

همچنین می‌توانید فیلترها را به صورت زنجیره‌ای اعمال کنید:

{% filter lower|escape %}
    <strong>SOME TEXT</strong>
{% endfilter %}

{# outputs "&lt;strong&gt;some text&lt;/strong&gt;" #}

for

تگ for به ازای هر آیتم موجود در آرایه، کدهای درونش را اجرا می‌کند:

<h1>Members</h1>
<ul>
    {% for user in users %}
        <li>{{ user.username|e }}</li>
    {% endfor %}
</ul>

نکته

آیتم‌های درون آرایه می‌توانند آرایه یا آبجکت‌های قابل سیر نیز باشند.


اگر می‌خواهید حقله در دنباله‌ای از اعداد ایجاد شود، از عملگر .. استفاده کنید:

{% for i in 0..10 %}
    * {{ i }}
{% endfor %}

مثال بالا تمامی اعداد ۰ تا ۱۰ را چاپ می‌کند.


از این عملگر برای حروف نیز می‌توان استفاده نمود:

{% for letter in 'a'..'z' %}
    * {{ letter }}
{% endfor %}

عملگر .. می‌تواند هر عبارتی را در هر دو طرف دریافت کند:

{% for letter in 'a'|upper..'z'|upper %}
    * {{ letter }}
{% endfor %}

متغیر loop

درون حلقه‌ی for می‌توان به متغیرهای خاصی دسترسی پیدا کرد:

متغیر توضیحات
loop.index موقعیت فعلی حلقه (شروع از ۱)
loop.index0 موقعیت فعلی حلقه (شروع از ۰)
loop.revindex معکوس موقعیت فعلی حلقه (شروع از ۱)
loop.revindex0 معکوس موقعیت فعلی حلقه (شروع از ۰)
loop.first صحیح اگر حلقه در اولین مرحله باشد
loop.last صحیح اگر حلقه در آخرین مرحله باشد
loop.length تعداد آیتم‌های موجود در حلقه
loop.parent محتوای parent

افزودن شرط

بر خلاف زبان‌های برنامه‌نویسی، امکان استفاده از break و continue در حلقه وجود ندارد. شما باید به دوره‌ی گردش حلقه شرط خود را اضافه کنید تا آیتم‌هایی که نمی‌خواهید رد شوند.


توجه

متغیر loop.last در حلقه‌های شرطی تعریف نمی‌شود.

شرط else

اگر آرایه‌ی مورد نظر برای گردش خالی باشد، با استفاده از else می‌توان کدی دیگر را اجرا نمود:

<ul>
    {% for user in users %}
        <li>{{ user.username|e }}</li>
    {% else %}
        <li><em>no user found</em></li>
    {% endfor %}
</ul>

گردش در نام و مقدار آیتم‌ها

در حلقه می‌توان به نام آیتم‌ها نیز دسترسی داشت:

<h1>Members</h1>
<ul>
    {% for key, user in users %}
        <li>{{ key }}: {{ user.username|e }}</li>
    {% endfor %}
</ul>

if

از تگ if برای ایجاد شرط استفاده می‌شود. نحوه‌ی استفاده از آن شبیه به سایر زبان‌های برنامه‌نویسی است.

{% if online == false %}
    <p>Our website is in maintenance mode. Please, come back later.</p>
{% endif %}

مثال زیر بررسی می‌کند که آیا آرایه خالی است یا خیر:

{% if users %}
    <ul>
        {% for user in users %}
            <li>{{ user.username|e }}</li>
        {% endfor %}
    </ul>
{% endif %}

خوب است بدانید

اگر می‌خواهید چک کنید که آیا متغیر تعریف شده است یا نه، از if variable_name is defined استفاده کنید.


اگر می‌خواهید شرط در صورت عدم برقرار بودن انجام شود، از not استفاده کنید:

{% if not user.subscribed %}
    <p>You are not subscribed to our mailing list.</p>
{% endif %}

برای عبارات چندشرطی می‌توان از and و or استفاده نمود:

{% if temperature > 18 and temperature < 27 %}
    <p>It's a nice day for a walk in the park.</p>
{% endif %}

برای چندشاخه کردن شرط‌ها می‌توان از elseif و else استفاده نمود:

{% if kenny.sick %}
    Kenny is sick.
{% elseif kenny.dead %}
    You killed Kenny! You bastard!!!
{% else %}
    Kenny looks okay --- so far
{% endif %}

خوب است بدانید

شرایط true یا false بودن یک عبارت:

مقدار ارزیابی Boolean
رشته‌ی خالی false
صفر عددی false
رشته‌ی فقط شامل فضای خالی true
آرایه‌ی خالی false
null false
آرایه‌ی غیر خالی true
آبجکت true

set

از تگ set برای تعریف کردن متغیر جدید در کد استفاده می‌شود:

{% set foo = 'bar' %}

پس از تعریف کردن متغیر، می‌توان از آن در قالب قابل استفاده است:

{# displays bar #}
{{ foo }}

مقداری که به متغیر داده می‌شود می‌تواند هر کدام از عبارات Twig نیز باشد:

{% set foo = [1, 2] %}
{% set foo = {'foo': 'bar'} %}
{% set foo = 'foo' ~ 'bar' %}

چندین متغیر می‌توانند به صورت یکجا در یک بلوک تعریف شوند:

{% set foo, bar = 'foo', 'bar' %}

{# is equivalent to #}

{% set foo = 'foo' %}
{% set bar = 'bar' %}

همچنین تگ set می‌تواند بخش بزرگی از یک متن را در بر گیرد:

{% set foo %}
    <div id="pagination">
        ...
    </div>
{% endset %}

توجه

اگر متغیری درون حلقه‌ی for تعریف شود، در بیرون از آن حلقه قابل دسترسی نیست:

{% for item in list %}
    {% set foo = item %}
{% endfor %}

{# foo is NOT available #}

برای دسترسی به متغیر، آن را قبل از حلقه تعریف نکید:

{% set foo = "" %}
{% for item in list %}
    {% set foo = item %}
{% endfor %}

{# foo is available #}

spaceless

از تگ spaceless برای حذف فضاهای خالی بین تگ‌های HTML استفاده می‌شود. فضاهای خالی بین متن‌ها یا درون تگ‌های HTML حذف نخواهند شد:

{% spaceless %}
    <div>
        <strong>foo</strong>
    </div>
{% endspaceless %}

{# output will be <div><strong>foo</strong></div> #}

این به معنای بهینه‌سازی حجم HTML خروجی نیست، بلکه باعث جلوگیری از ایجاد اختلال در پردازش مرورگر در شرایط خاص می‌شود.


نکته

اگر می‌خواهید حجم محتوای HTML خروجی را بهینه‌سازی کنید، از فشرده‌سازی GZip استفاده کنید.

verbatim

تگ verbatim باعث می‌شود تا بخشی از کد به عنوان متن خام در نظر گرفته شود و توسط Twig پردازش نشود. برای مثال اگر می‌خواهید نمونه‌ای از کد Twig را درون قالب خود نمایش دهید، از این تگ استفاده کنید:

{% verbatim %}
    <ul>
    {% for item in seq %}
        <li>{{ item }}</li>
    {% endfor %}
    </ul>
{% endverbatim %}

with

با استفاده از تگ with می‌توانید محدوده‌ی داخلی جدیدی را تعریف کنید. متغیرهایی که درون این محدوده تعریف می‌شوند، در بیرون از محدوده قابل دسترسی نیستند:

{% with %}
    {% set foo = 42 %}
    {{ foo }}           foo is 42 here
{% endwith %}
foo is not visible here any longer

به جای تعریف کردن متغیرها در ابتدای محدوده، می‌توانید متغیرها را همراه با تگ with تعریف نمایید. مثال قبل معادل مثال زیر است:

{% with { foo: 42 } %}
    {{ foo }}           foo is 42 here
{% endwith %}
foo is not visible here any longer

{# it works with any expression that resolves to a hash #}
{% set vars = { foo: 42 } %}
{% with vars %}
    ...
{% endwith %}

در حالت پیش‌فرض، محدوده‌ی داخلی به متغیرهای محدوده‌ی خارجی دسترسی دارد. اگر می‌خواهید چنین اتفاقی نیافتد، از کلمه‌ی کلیدی only استفاده کنید:

{% set bar = 'bar' %}
{% with { foo: 42 } only %}
    {# only foo is defined #}
    {# bar is not defined #}
{% endwith %}

فیلترها

محتوای درون متغیرها می‌تواننید توسط فیلترها تغییر کنند. فیلترها توسط خط عمودی (|) از متغیرها جدا می‌شوند. برخی از فیلترها چندین آرگومان در پرانتز دریافت می‌کنند. می‌توان چندین فیلتر را به صورت زنجیره‌ای بر روی یک متغیر اعمال کرد.

مثال زیر تمامی تگ‌های HTML را از name حذف کرده و آن را به حالت تیتر در می‌آورد:

{{ name|striptags|title }}

abs

فیلتر abs قدر مطلق عدد را برمی‌گرداند:

{# number = -5 #}

{{ number|abs }}

{# outputs 5 #}

batch

فیلتر batch آرایه را به چند آرایه با تعداد آیتم‌های داده شده تقسیم می‌کند. پارامتر دوم برای پر کردن مقادیر خالی به کار می‌رود:

{% set items = ['a', 'b', 'c', 'd', 'e', 'f', 'g'] %}

<table>
{% for row in items|batch(3, 'No item') %}
    <tr>
        {% for column in row %}
            <td>{{ column }}</td>
        {% endfor %}
    </tr>
{% endfor %}
</table>

خروجی کد بالا چنین خواهد بود:

<table>
    <tr>
        <td>a</td>
        <td>b</td>
        <td>c</td>
    </tr>
    <tr>
        <td>d</td>
        <td>e</td>
        <td>f</td>
    </tr>
    <tr>
        <td>g</td>
        <td>No item</td>
        <td>No item</td>
    </tr>
</table>

آرگومان‌ها

size: تعداد آیتم‌ها؛ اعداد غیرصحیح گرد خواهند شد

fill: برای پر کردن مقادیر خالی

capitalize

فیلتر capitalize اولین کاراکتر رشته را بزرگ می‌کند و بقیه را کوچک:

{{ 'my first car'|capitalize }}

{# outputs 'My first car' #}

convert_encoding

فیلتر convert_encoding کدبندی رشته را تغییر می‌دهد. آرگومان اول کدبندی خروجی و آرگومان دوم کدبندی ورودی می‌باشد:

{{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}

date

فیلتر date تاریخ را به فرمت داده شده قالب‌بندی می‌کند:

{{ post.published_at|date("m/d/Y") }}

فرمت‌هایی که توسط Twig پشتیبانی می‌شوند همانند تابع date در PHP هستند.

فیلتر date رشته‌هایی که توسط تابع strtotime در PHP پشتیبانی می‌شوند، نمونه‌های DateTime و نمونه‌های DateInterval را پشتیبانی می‌کند. برای نمایش تاریخ فعلی، از کلمه‌ی «now» استفاده کنید:

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

برای escape کردن کلمات و کاراکترها در تاریخ، از \\ در قبل از آن‌ها استفاده کنید:

{{ post.published_at|date("F jS \\a\\t g:ia") }}

اگر مقداری که به فیلتر date داده می‌شود null باشد، تاریخ فعلی به صورت پیش‌فرض برگردانده می‌شود. اگر رشته‌ی خالی به جای تاریخ فعلی مد نظرتان است، از عملگر سه‌تایی استفاده کنید:

{{ post.published_at is empty ? "" : post.published_at|date("m/d/Y") }}

اگر فرمتی وارد نشود، Twig به صورت پیش‌فرض از فرمت F j, Y H:i استفاده می‌کند.


منقطه‌ی زمانی

به طور پیش‌فرض، منقطه‌ی زمانی آسیا/تهران در نظر گرفته می‌شود، اما می‌توان منقطه‌ی زمانی را مشخص کرد:

{{ post.published_at|date("m/d/Y", "Europe/Paris") }}

اگر تاریخ یک شیء از کلاس DateTime است و نمی‌خواهید منطقه‌ی زمانی آن در نظر گرفته شود، مقدار false را به جای منقطه‌ی زمانی وارد کنید

{{ post.published_at|date("m/d/Y", false) }}

آرگومان‌ها

format: فرمت تاریخ

timezone: منقطه‌ی زمانی

date_modify

فیلتر date_modify تاریخ داده شده را با استفاده از رشته‌ی تغییردهنده تغییر می‌دهد:

{{ post.published_at|date_modify("+1 day")|date("m/d/Y") }}

فیلتر date_modify رشته‌هایی که توسط تابع strtotime در PHP پشتیبانی می‌شوند و نمونه‌های DateTime را پشتیبانی می‌کند. همچنین می‌توانید این فیلتر را با فیلتر date ترکیب کنید.


آرگومان‌ها

modofier: تغییردهنده

default

فیلتر default مقدار دریافت‌شده را برمی‌گرداند، اگر متغیر خالی یا تعریف‌نشده باشد. در غیر این صورت مقدار متغیر را برمی‌گرداند:

{{ var|default('var is not defined') }}

{{ var.foo|default('foo item on var is not defined') }}

{{ var['foo']|default('foo item on var is not defined') }}

{{ ''|default('passed var is empty')  }}

آرگومان‌ها

default: مقدار پیش‌فرض

escape

فیلتر escape رشته را escape می‌کند تا بتوان خروجی را به صورت امن نمایش داد. این فیلتر استراتژی‌های مختلفی را بسته به نوع محتوا پشتیبانی می‌کند.

به طور پیش‌فرض، این فیلتر از استراتژی HTML escaping استفاده می‌کند:

{{ user.username|escape }}

همچنین می‌توان به اختصار از فیلتر e استفاده کرد:

{{ user.username|e }}

همچنین فیلتر escape می‌تواند در محتواهایی به غیر از HTML با دریافت آرگومان اختیاری که نوع escape کردن را مشخص می‌کند مورد استفاده قرار گیرد:

{{ user.username|e }}
{# is equivalent to #}
{{ user.username|e('html') }}

مثالی برای escape کردن کد جاوااسکریپت:

{{ user.username|escape('js') }}
{{ user.username|e('js') }}

فیلتر escape از استراتژی‌های html، js، css، url و html_attr پشتیبانی می‌کند.


توجه

هنگام استفاده از escape خودکار، Twig سعی می‌کند تا متغیرهایی که escape شده‌اند را دوباره escape نکند؛ اما اگر از یک متغیر به عنوان استراتژی escape کردن استفاده شود، متغیر دوباره escape می‌شود:

{% set strategy = 'html' %}

{% autoescape 'html' %}
    {{ var|escape('html') }}   {# won't be double-escaped #}
    {{ var|escape(strategy) }} {# will be double-escaped #}
{% endautoescape %}

هنگام استفاده از یک متغیر به عنوان استراتژی escape کردن، متغیر را بدون escape کردن به کار ببرید:

% set strategy = 'html' %}

{% autoescape 'html' %}
    {{ var|escape(strategy)|raw }} {# won't be double-escaped #}
{% endautoescape %}

آرگومان‌ها

strategy: استراتژی escape کردن

charset: کدبندی نویسه

first

فیلتر first اولین مقدار دوره، آرایه یا رشته را برمی‌گرداند:

{{ [1, 2, 3, 4]|first }}
{# outputs 1 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|first }}
{# outputs 1 #}

{{ '1234'|first }}
{# outputs 1 #}

format

فیلتر format مقادیر داده شده را جایگزین حفره‌ها می‌کند (حفره‌ها از نشانه‌گذاری تابع sprintf در PHP پیروی می‌کنند):

{{ "I like %s and %s."|format(foo, "bar") }}

{# outputs I like foo and bar
   if the foo parameter equals to the foo string. #}

join

فیلتر join مقادیر داخل آرایه را به هم می‌چسباند:

{{ [1, 2, 3]|join }}
{# returns 123 #}

همچنین می‌توان بین آن‌ها مقدار خاصی قرار داد:

{{ [1, 2, 3]|join('|') }}
{# outputs 1|2|3 #}

آرگومان‌ها

glue: جداکننده

json_encode

فیلتر json_encode مقدار را به صورت JSON برمی‌گرداند:

{{ data|json_encode() }}

آرگومان‌ها

options: همانند آپشن‌های تابع json_encode در PHP ({{ data|json_encode(constant('JSON_PRETTY_PRINT')) }})

keys

فیلتر keys کلیدهای آرایه را برمی‌گرداند:

{% for key in array|keys %}
    ...
{% endfor %}

last

فیلتر last آخرین مقدار دوره، آرایه یا رشته را برمی‌گرداند:

{{ [1, 2, 3, 4]|last }}
{# outputs 4 #}

{{ { a: 1, b: 2, c: 3, d: 4 }|last }}
{# outputs 4 #}

{{ '1234'|last }}
{# outputs 4 #}

length

فیلتر length تعداد آیتم‌های آرایه یا تعداد کاراکترهای رشته را برمی‌گرداند:

{% if users|length > 10 %}
    ...
{% endif %}

lower

فیلتر lower حروف رشته را کوچک می‌کند:

{{ 'WELCOME'|lower }}

{# outputs 'welcome' #}

merge

فیلتر merge دو آرایه را با یکدیگر ترکیب می‌کند:

{% set values = [1, 2] %}

{% set values = values|merge(['apple', 'orange']) %}

{# values now contains [1, 2, 'apple', 'orange'] #}

مقادیر جدید در انتهای آرایه اضافه می‌شوند.

فیلتر merge از آرایه‌های انجمنی نیز پشتیبانی می‌کند:

{% set items = { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'unknown' } %}

{% set items = items|merge({ 'peugeot': 'car', 'renault': 'car' }) %}

{# items now contains { 'apple': 'fruit', 'orange': 'fruit', 'peugeot': 'car', 'renault': 'car' } #}

برای آرایه‌های انجمنی، فرایند ترکیب بستگی به کلیدها دارد. اگر کلیدی وجود داشته باشد که در آرایه‌ی اصلی موجود نباشد، کلید همراه با مقدارش به آرایه‌ی اصلی اضافه می‌شود، اما اگر کلید در هر دو آرایه موجود باشد، مقدار جدید جایگزین مقدار موجود در آرایه‌ی اصلی می‌شود.

nl2br

فیلتر nl2br قبل از خطوط جدید یک شکست خط HTML اضافه می‌کند:

{{ "I like Twig.\nYou will like it too."|nl2br }}
{# outputs

    I like Twig.
You will like it too. #}

نکته

فیلتر nl2br قبل از انجام تبدیل ورودی را escape می‌کند.

number_format

فیلتر number_format اعداد را قالب‌بندی می‌کند. این فیلتر در واقع همان تابع number_format در PHP است:

{{ 200.35|number_format }}

شما می‌توانید محل اعشاری، علامت اعشار و علامت جداکننده‌ی هزارها را با استفاده از آرگومان‌های اضافه مشخص کنید:

{{ 9800.333|number_format(2, '.', ',') }}

برای قالب‌بندی اعداد منفی، عدد را بین پرانتز قرار دهید:

{{ -9800.333|number_format(2, '.', ',') }} {# outputs : -9 #}
{{ (-9800.333)|number_format(2, '.', ',') }} {# outputs : -9,800.33 #}

اگر آپشن‌های قالب‌بندی تعریف نشوند، Twig به صورت پیش‌فرض از مقادیر زیر استفاده می‌کند:

  • محل اعشاری ۰
  • . به عنوان علامت اعشار
  • , به عنوان جداکننده‌ی هزارها
  • آرگومان‌ها

    decimal: تعداد اعشارها برای نمایش

    decimal_point: علامت اعشار

    thousands_sep: علامت جداکننده‌ی هزارها

    raw

    فیلتر raw مقدار خام ورودی را برمی‌گرداند، یعنی اگر escape خودکار فعال باشد، آن مقدار escape نمی‌شود:

    {% autoescape %}
        {{ var|raw }} {# var won't be escaped #}
    {% endautoescape %}

    replace

    فیلتر replace رشته را با جایگزینی مقادیر موجود در آن قالب‌بندی می‌کند (حفره‌ها فرم خاصی ندارند):

    {{ "I like %this% and %that%."|replace({'%this%': foo, '%that%': "bar"}) }}
    
    {# outputs I like foo and bar
       if the foo parameter equals to the foo string. #}

    reverse

    فیلتر reverse آرایه را رشته را معکوس می‌کند:

    {% for user in users|reverse %}
        ...
    {% endfor %}
    
    {{ '1234'|reverse }}
    
    {# outputs 4321 #}

    round

    فیلتر round عدد را با خطای داده شده گرد می‌کند:

    {{ 42.55|round }}
    {# outputs 43 #}
    
    {{ 42.55|round(1, 'floor') }}
    {# outputs 42.5 #}

    فیلتر round دو آرگومان اختیاری دریافت می‌کند؛ اولی خطای گرد کردن را مشخص می‌کند (پیش‌فرض ۰) و دومی روش گرد کردن را مشخص می‌کند (پیش‌فرض common).

    common اگر اعشار بزرگ‌تر یا مساوی نیم باشد، عدد را به سمت بالا و در غیر این صورت، عدد را به سمت پایین گرد می‌کند.

    ceil همیشه عدد را رو به بالا گرد می‌کند.

    floor همیشه عدد را رو به پایین گرد می‌کند.

    slice

    فیلتر slice تکه‌ای از آرایه یا رشته را استخراج می‌کند:

    {% for i in [1, 2, 3, 4, 5]|slice(1, 2) %}
        {# will iterate over 2 and 3 #}
    {% endfor %}
    
    {{ '12345'|slice(1, 2) }}
    
    {# outputs 23 #}

    sort

    فیلتر sort آرایه را مرتب می‌کند:

    {% for user in users|sort %}
        ...
    {% endfor %}

    split

    فیلتر split رشته را توسط جداکننده‌ی داده شده به یک آرایه تبدیل می‌کند:

    {% set foo = "one,two,three"|split(',') %}
    {# foo contains ['one', 'two', 'three'] #}

    همچنین می‌توان آرگومان limit را وارد کرد:

  • اگر limit مثبت باشد، آرایه‌ای با حداکثر مقادیر محدودیت داده شده همراه با یک آیتم اضافی که شامل بقیه‌ی رشته می‌شود برگردانده می‌شود.
  • اگر limit منفی باش، آرایه‌ای با حداکثر مقادیر محدودیت داده شده برگردانده می‌شود.
  • اگر limit صفر باشد، ۱ در نظر گرفته می‌شود.

  • {% set foo = "one,two,three,four,five"|split(',', 3) %}
    {# foo contains ['one', 'two', 'three,four,five'] #}

    اگر delimiter یک رشته‌ی خالی باشد، مقادیر با یک طول مشخص از هم جدا می‌شوند. طول مقادیر در آرگومان limit می‌تواند مشخص شود:

    {% set foo = "123"|split('') %}
    {# foo contains ['1', '2', '3'] #}
    
    {% set bar = "aabbcc"|split('', 2) %}
    {# bar contains ['aa', 'bb', 'cc'] #}

    آرگومان‌ها

    delimiter: جداکننده

    limit: آرگومان محدودیت

    striptags

    فیلتر striptags تگ‌های SGML/XML را از رشته حذف کرده و فضای خالی مجاور را با یک اسپیس جایگزین می‌کند:

    {{ some_html|striptags }}

    همچنین می‌توان تگ‌هایی که نیاز به حذفشان نیست را مشخص نمود:

    {{ some_html|striptags('<br><p>') }}

    در مثال بالا، تگ‌های <br/>، <br>، <p> و <p/> از رشته حذف نمی‌شوند.

    title

    فیلتر title رشته را به حالت عنوان در می‌آورد، یعنی حروف اول کلمات را بزرگ و بقیه را کوچک می‌کند:

    {{ 'my first car'|title }}
    
    {# outputs 'My First Car' #}

    trim

    فیلتر trim فضای خالی قبل و بعد رشته را حذف می‌کند:

    {{ '  I like Twig.  '|trim }}
    
    {# outputs 'I like Twig.' #}
    
    {{ '  I like Twig.'|trim('.') }}
    
    {# outputs '  I like Twig' #}
    
    {{ '  I like Twig.  '|trim(side='left') }}
    
    {# outputs 'I like Twig.  ' #}
    
    {{ '  I like Twig.  '|trim(' ', 'right') }}
    
    {# outputs '  I like Twig.' #}

    upper

    فیلتر upper حروف رشته را بزرگ می‌کند:

    {{ 'welcome'|upper }}
    
    {# outputs 'WELCOME' #}

    url_encode

    فیلتر url_encode رشته‌ی داده شده را به بخشی از یک URL و یا آرایه‌ی داده شده را به یک رشته‌ی کوئری تبدیل می‌کند:

    {{ "path-seg*ment"|url_encode }}
    {# outputs "path-seg%2Ament" #}
    
    {{ "string with spaces"|url_encode }}
    {# outputs "string%20with%20spaces" #}
    
    {{ {'param': 'value', 'foo': 'bar'}|url_encode }}
    {# outputs "param=value&foo=bar" #}

    number_farsi

    فیلتر number_farsi اعداد انگلیسی موجود در رشته را به اعداد فارسی تبدیل می‌کند:

    {{ '1 2 3'|number_farsi }}
    
    {# outputs '۱ ۲ ۳' #}

    number_english

    فیلتر number_english اعداد فارسی موجود در رشته را به اعداد انگلیسی تبدیل می‌کند:

    {{ '۱ ۲ ۳'|number_english }}
    
    {# outputs '1 2 3' #}

    توابع

    از توابع برای تولید محتوا استفاده می‌شود. بعد از نام تابع پرانتز قرار می‌گیرد و ممکن است یک یا چندین آرگومان را دریافت کنند.

    برای مثال، تابع range یک آرایه‌ی متشکل از اعداد طبیعی صعودی را ایجاد می‌کند:

    {% for i in range(0, 3) %}
        {{ i }},
    {% endfor %}

    همچنین آرگومان‌ها را می‌توان نام‌گذاری کرد:

    {% for i in range(low=1, high=10, step=2) %}
        {{ i }},
    {% endfor %}

    نام‌گذاری آرگومان‌ها باعث افزایش خوانایی کد می‌شود:

    {{ data|convert_encoding('UTF-8', 'iso-2022-jp') }}
    
    {# versus #}
    
    {{ data|convert_encoding(from='iso-2022-jp', to='UTF-8') }}

    همچنین نام‌گذاری آرگومان‌ها این اجازه را به شما می‌دهد تا بتوانید آرگومان‌هایی را که نیاز به تغییرشان نیست را خالی بگذارید:

    {# the first argument is the date format, which defaults to the global date format if null is passed #}
    {{ "now"|date(null, "Europe/Paris") }}
    
    {# or skip the format value by using a named argument for the time zone #}
    {{ "now"|date(timezone="Europe/Paris") }}

    attribute

    از تابع attribute برای دسترسی به خاصیت پویای یک متغیر استفاده می‌شود:

    {{ attribute(object, method) }}
    {{ attribute(object, method, arguments) }}
    {{ attribute(array, item) }}

    constant

    تابع constant مقدار ثابت متغیر را برمی‌گرداند:

    {{ some_date|date(constant('DATE_W3C')) }}
    {{ constant('Namespace\\Classname::CONSTANT_NAME') }}

    cycle

    تابع cycle درون آرایه‌ای از مقادیر می‌چرخد:

    {% set start_year = date() | date('Y') %}
    {% set end_year = start_year + 5 %}
    
    {% for year in start_year..end_year %}
        {{ cycle(['odd', 'even'], loop.index0) }}
    {% endfor %}

    آرایه می‌تواند شامل هر تعداد مقادیری شود:

    {% set fruits = ['apple', 'orange', 'citrus'] %}
    
    {% for i in 0..10 %}
        {{ cycle(fruits, i) }}
    {% endfor %}

    آرگومان‌ها

    position: موقعیت چرخش

    date

    تابع date آرگومان را به یک تاریخ تبدیل می‌کند تا بتوان تاریخ را مقایسه کرد:

    {% if date(user.created_at) < date('-2days') %}
        {# do something #}
    {% endif %}

    آرگومان باید یکی از موارد پشتیبانی شده‌ی زمان و تاریخ در زبان PHP باشد.

    {% set fruits = ['apple', 'orange', 'citrus'] %}
    
    {% for i in 0..10 %}
        {{ cycle(fruits, i) }}
    {% endfor %}

    میتوان منطقه‌ی زمانی را به عنوان آرگومان دوم تعریف کرد:

    {% if date(user.created_at) < date('-2days', 'Europe/Paris') %}
        {# do something #}
    {% endif %}

    اگر آرگومانی تعریف نشود، تاریخ فعلی برگردانده خواهد شد:

    {% if date(user.created_at) < date() %}
        {# always! #}
    {% endif %}

    آرگومان‌ها

    date: تاریخ

    timezone: منقطه‌ی زمانی

    max

    تابع max بزرگ‌ترین مقدار بین مقادیر یک دوره یا آرایه را برمی‌گرداند:

    {{ max(1, 3, 2) }}
    {{ max([1, 3, 2]) }}

    اگر آرایه از نوع انجمنی باشد، کلیدها نادیده گرفته شده و فقط مقادیر مورد بررسی قرار می‌گیرند

    {{ max({2: "e", 1: "a", 3: "b", 5: "d", 4: "c"}) }}
    {# returns "e" #}

    min

    تابع min کوچک‌ترین مقدار بین مقادیر یک دوره یا آرایه را برمی‌گرداند:

    {{ max(1, 3, 2) }}
    {{ max([1, 3, 2]) }}

    اگر آرایه از نوع انجمنی باشد، کلیدها نادیده گرفته شده و فقط مقادیر مورد بررسی قرار می‌گیرند

    {{ max({2: "e", 1: "a", 3: "b", 5: "d", 4: "c"}) }}
    {# returns "a" #}

    random

    تابع random یک مقدار تصادفی را بسته به نوع ورودی برمی‌گرداند:

  • یک آیتم تصادفی از یک دوره یا آرایه
  • یک کاراکتر تصادفی از یک رشته
  • یک عدد تصادفی بین ۰ و عدد داده شده

  • {{ random(['apple', 'orange', 'citrus']) }} {# example output: orange #}
    {{ random('ABC') }}                         {# example output: C #}
    {{ random() }}                              {# example output: 15386094 (works as the native PHP mt_rand function) #}
    {{ random(5) }}                             {# example output: 3 #}

    آرگومان‌ها

    values: مقادیر

    range

    تابع range آرایه‌ای از تصاعد حسابی دو عدد را برمی‌گرداند:

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

    اگر گام تعریف شود (به عنوان پرامتر سوم)، این مقدار افزایش (یا کاهش برای مقادیر منفی) را مشخص می‌کند.


    توجه

    اگر مقدار شروع از پایان بزرگ‌تر باشد، range گام را -۱ در نظر خواهد گرفت:

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

    آرگومان‌ها

    low: اولین مقدار دوره

    high: آخرین مقدار دوره

    step: مقدار افزایش بین عناصر دوره

    عملگرها

    in

    از عملگر in برای آزمایش شامل شدن در متغیر استفاده می‌شود.

    اگر مقدار سمت چپ شامل مقدار سمت راست شود، این عملگر مقدار true را برمی‌گرداند:

    {# returns true #}
    
    {{ 1 in [1, 2, 3] }}
    
    {{ 'cd' in 'abcde' }}

    برای آزمایش مخالف شرط از عملگر not in استفاده می‌شود:

    {% if 1 not in [1, 2, 3] %}
    
    {# is equivalent to #}
    {% if not (1 in [1, 2, 3]) %}

    is

    از عملگر is برای انجام تست استفاده می‌شود.

    {# find out if a variable is odd #}
    
    {{ name is odd }}

    همچنین تست‌ها می‌توانند آرگومان دریافت کنند:

    {% if post.status is constant('Post::PUBLISHED') %}

    برای انجام مخالف تست، از عملگر is not استفاده کنید:

    {% if post.status is not constant('Post::PUBLISHED') %}
    
    {# is equivalent to #}
    {% if not (post.status is constant('Post::PUBLISHED')) %}

    ریاضی

    عملگرهای ریاضی به شما امکان انجام محاسبات ریاضی بر روی متغیرها را می‌دهند. Twig از عملگرهای ریاضی زیر پشتیبانی می‌کند:

  • +: مقادیر را با یکدیگر جمع می‌کند. {{ 1 + 1 }} برابر است با ۲.
  • -: مقدار دوم را از مقدار اول کم می‌کند. {{ 3 - 2 }} برابر است با ۱.
  • /: دو مقدار را تقسیم بر یکدیگر می‌کند. خروجی ممکن است عدد اعشاری باشد {{ 1 / 2 }} برابر است با ۰٫۵.
  • %: باقی‌مانده‌ی تقسیم دو عدد بر یکدیگر را محاسبه می‌کند. {{ 11 % 7 }} برابر است با ۴.
  • //: دو عدد را بر یکدیگر تقسیم کرده و جزء صحیح حاصل را محاسبه می‌کند. {{ 20 // 7 }} برابر است با ۲.
  • *: دو عدد را در هم ضرب می‌کند. {{ 2 * 2 }} برابر است با ۴.
  • **: عدد سمت چپ را به توان عدد سمت راست می‌رساند. {{ 2 ** 3 }} برابر است با ۸.
  • منطقی

    با استفاده از عملگرهای منقطی می‌توان چندین عبارت را با یکدیگر ترکیب کرد:

  • and: مقدار true را برمی‌گرداند اگر هر دو عبارت true باشند.
  • or: مقدار true را برمی‌گرداند اگر یکی از عبارات true باشد.
  • not: عبارت را منفی می‌کند.
  • (expr): عبارت را دسته‌بندی می‌کند.
  • مقایسه‌ای

    عملگرهای ==، !=، >، <، >= و <= در تمامی عبارات قابل استفاده هستند.

    همچنین می‌توان از عملگرهای starts with و ends with در عبارات مقایسه‌ای برای رشته‌ها استفاده نمود:

    {% if 'Fabien' starts with 'F' %}
    {% endif %}
    
    {% if 'Fabien' ends with 'n' %}
    {% endif %}

    خوب است بدانید

    برای مقایسه‌ی رشته‌ها به روش پیچیده، عملگر matches به شما امکان استفاده از عبارات باقاعده را می‌دهد:

    {% if phone matches '/^[\\d\\.]+$/' %}
    {% endif %}

    سایر عملگرها

    عملگرهای زیر در هیچ یک از دسته‌های قبلی قرار نمی‌گیرند:

  • |: فیلتر اعمال می‌کند.
  • ..: یک دوره بر اساس عملوند قبل و بعدش ایجاد می‌کند:
  • {{ 1..5 }}
    
    {# equivalent to #}
    {{ range(1, 5) }}

    توجه داشته باشید که اگر می‌خواهید فیلتری بر روی این عملگر اعمال کنید، آن را در پرانتز قرار دهید:

    (1..5)|join(', ')

  • ~: تمامی عملوندها را به رشته تبدیل کرده و آن‌ها را به یکدیگر می‌چسباند. {{ "Hello " ~ name ~ "!" }} مقدار Hello John! را برمی‌گرداند (با فرض این که مقدار name «John» است).
  • ., []: صفت شیء را دریافت می‌کند.
  • ?:: عملگر سه‌تایی:
  • {{ foo ? 'yes' : 'no' }}
    {{ foo ?: 'no' }} is the same as {{ foo ? foo : 'no' }}
    {{ foo ? 'yes' }} is the same as {{ foo ? 'yes' : '' }}

  • ??: عملگر ادغام‌کننده‌ی null:
  • {# returns the value of foo if it is defined and not null, 'no' otherwise #}
    {{ foo ?? 'no' }}

    تست‌ها

    constant

    constant چک می‌کند که آیا مقدار داده شده با مقدار ثابت برابر است یا خیر:

    {% if post.status is constant('Post::PUBLISHED') %}
        the status attribute is exactly the same as Post::PUBLISHED
    {% endif %}

    defined

    defined چک می‌کند که آیا آیا متغیر تعریف شده است یا خیر:

    {# defined works with variable names #}
    {% if foo is defined %}
        ...
    {% endif %}
    
    {# and attributes on variables names #}
    {% if foo.bar is defined %}
        ...
    {% endif %}
    
    {% if foo['bar'] is defined %}
        ...
    {% endif %}

    divisible by

    divisible by چک می‌کند که آیا متغیر بر مقدار داده شده بخش‌پذیر است یا خیر:

    {% if loop.index is divisible by(3) %}
        ...
    {% endif %}

    empty

    empty چک می‌کند که آیا متغیر یک رشته یا آرایه‌ی خالی، false یا null است یا خیر:

    {% if foo is empty %}
        ...
    {% endif %}

    even

    even مقدار true را برمی‌گرداند اگر عدد داده شده زوج باشد:

    {{ var is even }}

    iterable

    iterable مقدار true را برمی‌گرداند اگر مقدار داده شده آرایه باشد:

    {# evaluates to true if the foo variable is iterable #}
    {% if users is iterable %}
        {% for user in users %}
            Hello {{ user }}!
        {% endfor %}
    {% else %}
        {# users is probably a string #}
        Hello {{ users }}!
    {% endif %}

    null

    null مقدار true را برمی‌گرداند اگر مقدار داده شده null باشد:

    {{ var is null }}

    odd

    odd مقدار true را برمی‌گرداند اگر عدد داده شده فرد باشد:

    {{ var is odd }}

    same as

    same as مقدار true را برمی‌گرداند اگر متغیر با متغیر دیگری یکسان باشد:

    {% if foo.attribute is same as(false) %}
        the foo attribute really is the 'false' PHP value
    {% endif %}

    متغیرهای بلاگی

    به صورت پیش‌فرض، متغیرهای زیر در قالب وبلاگ تعریف شده‌اند:


  • blog: آرایه‌ای شامل اطلاعات مربوط به وبلاگ که شامل مقادیر زیر می‌باشد:
    • title: عنوان وبلاگ
    • description: متن توضیحات وبلاگ
    • about: متن درباره‌ی وبلاگ
    • footer_text: متن فوتر وبلاگ

  • title: عنوان صفحه

  • og_meta: رشته‌ای متشکل از تگ‌های متای OpenGlyph مربوط به صفحه

  • type: نوع صفحه‌ای که کاربر در آن قرار دارد. این متغیر یکی از مقادیر زیر را خواهد داشت:
    • index: صفحه‌ی اول وبلاگ و صفحات اصلی دیگر (مانند صفحه‌ی دوم نوشته‌ها)
    • category: صفحه‌ی نوشته‌های مربوط به یک دسته‌ی خاص
    • tag: صفحه‌ی نوشته‌های مربوط به یک برچسب خاص
    • post: صفحه‌ی مربوط به یک نوشته‌
    • page: صفحه‌ی مربوط به یک صفحه‌ی سفارشی

  • top_pages: آرایه‌ای متشکل از صفحات سفارشی‌ای که تیک «نمایش در بالای صفحه» برایشان فعال است که هر صفحه شامل مقادیر زیر می‌شود:
    • title: عنوان صفحه
    • permalink: نامک صفحه
    • date: آرایه‌ای متشکل از زمان ایجاد صفحه که شامل مقادیر زیر می‌باشد:
      • day: روز ایجاد صفحه به عدد
      • month: ماه ایجاد صفحه به عدد
      • month_name: نام ماه ایجاد صفحه
      • day: سال ایجاد صفحه به عدد
      • hour: ساعت ایجاد صفحه
      • minute: دقیقه‌ی ایجاد صفحه
      • second: ثانیه‌ی ایجاد صفحه
    • content: محتوای صفحه

  • اگر صفحه از نوع index، category یا tag باشد، آرایه‌ای به نام posts متشکل از نوشته‌ها تعریف می‌شود که هر نوشته شامل مقادیر زیر است:

    • title: عنوان نوشته
    • permalink: نامک نوشته
    • date: آرایه‌ای متشکل از زمان ایجاد نوشته که شامل مقادیر زیر می‌باشد:
      • day: روز ایجاد نوشته به عدد
      • month: ماه ایجاد نوشته به عدد
      • month_name: نام ماه ایجاد نوشته
      • day: سال ایجاد نوشته به عدد
      • hour: ساعت ایجاد نوشته
      • minute: دقیقه‌ی ایجاد نوشته
      • second: ثانیه‌ی ایجاد نوشته
    • preview: پیش‌نمایش نوشته
    • content: محتوای نوشته
    • categories: رشته‌ای متشکل از دسته‌های نوشته
    • tags: آرایه‌ای متشکل از برچسب‌های نوشته
    • meta: آرایه‌ای متشکل از اطلاعات متای نوشته که هر مورد شامل مقادیر زیر می‌باشد:
      • name: نام تگ متا
      • value: مقدار تگ متا

  • اگر صفحه از نوع category باشد، متغیری به نام category و با مقدار نام دسته تعریف می‌شود.


    اگر صفحه از نوع tag باشد، متغیری به نام tag و با مقدار نام برچسب تعریف می‌شود.


    اگر صفحه از نوع post باشد، آرایه‌ای به نام post متشکل از اطلاعات مربوط به نوشته تعریف می‌شود که شامل مقادیر زیر است:

    • title: عنوان نوشته
    • permalink: نامک نوشته
    • date: آرایه‌ای متشکل از زمان ایجاد نوشته که شامل مقادیر زیر می‌باشد:
      • day: روز ایجاد نوشته به عدد
      • month: ماه ایجاد نوشته به عدد
      • month_name: نام ماه ایجاد نوشته
      • day: سال ایجاد نوشته به عدد
      • hour: ساعت ایجاد نوشته
      • minute: دقیقه‌ی ایجاد نوشته
      • second: ثانیه‌ی ایجاد نوشته
    • preview: پیش‌نمایش نوشته
    • content: محتوای نوشته
    • categories: رشته‌ای متشکل از دسته‌های نوشته
    • tags: آرایه‌ای متشکل از برچسب‌های نوشته
    • meta: آرایه‌ای متشکل از اطلاعات متای نوشته که هر مورد شامل مقادیر زیر می‌باشد:
      • name: نام تگ متا
      • value: مقدار تگ متا

  • اگر صفحه از نوع page باشد، آرایه‌ای به نام page متشکل از اطلاعات مربوط به صفحه تعریف می‌شود که شامل مقادیر زیر است:

    • title: عنوان صفحه
    • permalink: نامک صفحه
    • date: آرایه‌ای متشکل از زمان ایجاد صفحه که شامل مقادیر زیر می‌باشد:
      • day: روز ایجاد صفحه به عدد
      • month: ماه ایجاد صفحه به عدد
      • month_name: نام ماه ایجاد صفحه
      • day: سال ایجاد صفحه به عدد
      • hour: ساعت ایجاد صفحه
      • minute: دقیقه‌ی ایجاد صفحه
      • second: ثانیه‌ی ایجاد صفحه
    • preview: پیش‌نمایش صفحه
    • content: محتوای صفحه
    • categories: رشته‌ای متشکل از دسته‌های نوشته
    • tags: آرایه‌ای متشکل از برچسب‌های نوشته
    • meta: آرایه‌ای متشکل از اطلاعات متای صفحه که هر مورد شامل مقادیر زیر می‌باشد:
      • name: نام تگ متا
      • value: مقدار تگ متا
  • pagination: نوار پیمایش صفحات (تحت چارچوب بوت‌استرپ)
  • pagination_foundation: نوار پیمایش صفحات (تحت چارچوب فاندیشن)
  • has_previous_page: اگر صفحه‌ی قبلی وجود داشته باشد true و در غیر این صورت false خواهد بود. در صورت وجود صفحه‌ی قبلی، متغیری با نام previous_page که مقدارش شماره‌ی صفحه‌ی قبلی است تعریف می‌شود.
  • has_next_page: اگر صفحه‌ی بعدی وجود داشته باشد true و در غیر این صورت false خواهد بود. در صورت وجود صفحه‌ی بعدی متغیری با نام next_page که مقدارش شماره‌ی صفحه‌ی بعدی است تعریف می‌شود.