رویدادهای داخلی قالب

فینچ مجموعه‌ای از متغیرهای داخلی و توابع کمکی را به هر قالب Jinja تزریق می‌کند. این‌ها از طریق پیشوندهای خاص، در کنار داده‌های خودتان که با addParam() اضافه کرده‌اید، در دسترس‌اند.

متغیرهای سراسری

{{ isLocalDebug }}   {# true وقتی برنامه در حالت دیباگ اجرا می‌شود #}
{{ data }}          {# map تمام پارامترهای اضافه‌شده از طریق rq.addParam() #}
{{ session }}       {# map سشن سمت سرور #}
{{ $rq }}           {# شیء Request #}

کمک‌کننده‌های asset

{{ assets.js() }}      {# تمام تگ‌های <script> اضافه‌شده از طریق rq.addAsset() را رندر می‌کند #}
{{ assets.css() }}     {# تمام تگ‌های <link> را رندر می‌کند #}
{{ assets.dataJs() }}  {# data attributeها را برای دسترسی JS رندر می‌کند #}

کمک‌کننده‌های route و URL ($e)

{{ $e.route }}                              {# مسیر رندرشده‌ی route منطبق‌شده، مثلاً '/users/42' — همان path/extraPath خاصی که با این درخواست مطابقت داشته #}
{{ $e.routePath }}                          {# الگوی کامل و متعارف path این route، مثلاً '/users/{id}' (همیشه از طریق `path` اصلی، حتی اگر یک `extraPath` مطابقت داده باشد) #}
{{ $e.routeKey }}                           {# `key` این route، مثلاً 'users.show' — با $e.route یکسان نیست #}
{{ $e.isKey('root.panel') }}                {# true اگر کلید route جاری مطابقت داشته باشد #}
{{ $e.hasKey(['root.panel', 'root.form']) }} {# true اگر کلید route جاری یکی از این کلیدها باشد #}

{{ $e.routeUrl('key') }}                           {# URL برای یک route نام‌گذاری‌شده #}
{{ $e.routeUrl('users.show', {'id': '42'}) }}       {# URL با پارامترهای path #}
{{ $e.routeUrl('search', {}, {'q': 'hello'}) }}     {# URL با پارامترهای query #}

{{ $e.uri }}            {# URI کامل درخواست، به‌صورت percent-encoded و در قالب یک رشته #}
{{ $e.uriString }}      {# URI کامل درخواست، بدون encode شدن #}
{{ $e.path }}           {# فقط path درخواست، به‌صورت percent-encoded و در قالب یک رشته #}
{{ $e.pathString }}     {# فقط path درخواست، بدون encode شدن #}
{{ $e.isPath('/example/form') }}  {# true اگر path جاری مطابقت داشته باشد #}
{{ $e.endpoint }}       {# مسیر endpoint منطبق‌شده #}

{{ $e.url('/about') }}                    {# ساخت یک URL مطلق از یک path #}
{{ $e.urlParam('/users', {'id': '5'}) }}   {# URL با پارامترهای query الحاق‌شده #}
{{ $e.urlToLanguage('fa') }}              {# URL جاری که به زبان دیگری تغییر کرده #}

برخلاف نامشان، $e.uri/$e.path رشته‌های percent-encoded هستند، نه یک شیء Uri در Dart و نه فهرستی از بخش‌های path — وقتی به مقدار خام و رمزگشایی‌نشده نیاز دارید، از $e.uriString/$e.pathString استفاده کنید.

کمک‌کننده‌های کوکی

{{ $e.getCookie('theme', 'light') }}  {# خواندن یک کوکی با مقدار پیش‌فرض؛ همیشه یک خواندن ساده (رمزگذاری‌نشده) است #}

کمک‌کننده‌های زبان

{{ $e.ln }}            {# کد زبان جاری، مثلاً 'en' #}
{{ $e.langs }}         {# فهرست تمام زبان‌های پیکربندی‌شده: [{code, label, contry}] #}

فیلدهای $e.dir و label/contry درون هر ورودی $e.langs، از یک کلید ساده‌ی "dir" در فایل زبان شما خوانده نمی‌شوند — آن‌ها به‌دنبال کلیدهای ترجمه‌ی اختصاصی با نام‌های language.<code>_dir، language.<code>_label و language.<code>_contry می‌گردند (توجه: contry، نه country — این یک ایراد املایی واقعی در خودِ فریمورک است، نه یک غلط تایپی در این سند). اگر این کلیدها در فایل‌های زبان شما وجود نداشته باشند، .tr.write() به‌طور خاموش (silently) خودِ کلید را بازمی‌گرداند، بنابراین {{ $e.dir }} عیناً متن language.en_dir را به‌جای ltr رندر خواهد کرد.

فایل‌های زبانِ خودِ پروژه‌ی نمونه‌ی فینچ فقط یک کلید ساده‌ی "dir" را تعریف می‌کنند و این کلیدهای language.* را تعریف نمی‌کنند، بنابراین $e.dir/$e.langs[].label/$e.langs[].contry به‌صورت پیش‌فرض حل‌نشده (unresolved) رندر می‌شوند. layout خودِ پروژه‌ی نمونه با استفاده از {{ $t('dir') }} به‌جای آن این مشکل را دور می‌زند (یک جستجوی مستقیم روی همان کلید ساده‌ی "dir") — به مثال کامل Templates مراجعه کنید. یا کلیدهای language.<code>_dir/_label/_contry را خودتان به هر فایل زبان اضافه کنید، یا به‌جای $e.dir و فیلدهای label/contry در $e.langs، از $t('dir') یا کلیدهای ترجمه‌ی خودتان استفاده کنید.

کمک‌کننده‌های کاربردی

{{ $e.widgetPath('partials/nav') }}   {# پسوند پیکربندی‌شده‌ی widget را به یک path اضافه می‌کند، مثلاً 'partials/nav.j2.html' — widgetsPath را در ابتدای آن اضافه نمی‌کند #}
{{ $e.randomString(8) }}             {# رشته‌ی تصادفی با ۸ کاراکتر (طول پیش‌فرض در صورت حذف آرگومان، ۴ است) #}
{{ $e.toString(value) }}             {# هر مقداری را به رشته تبدیل می‌کند #}

ترجمه

{{ $t('logo.title') }}                          {# ترجمه‌ی یک کلید #}
{{ $t('greeting', {'name': user.name}) }}       {# ترجمه به‌همراه پارامتر #}

پیمایش داده‌ی تودرتو

{{ $n('user/address/city', 'Unknown') }}  {# پیمایش امن پارامترهای تودرتو #}

دامپ دیباگ

{{ dump(data) }}   {# دامپ بصری هر متغیری در مرورگر (فقط در حالت دیباگ) #}

رویدادهای محلی سفارشی

توابع سراسری خودتان را در app.dart با استفاده از Request.localEvents تعریف کنید:

Request.localEvents.addAll({
  'currentYear': () => DateTime.now().year,
  'appName': () => 'My App',
});

آن‌ها را در قالب‌ها با پیشوند $l. در دسترس داشته باشید:

<footer>© {{ $l.currentYear() }} {{ $l.appName() }}</footer>