قالب‌ها

وقتی وبلاگ درخواستی دریافت می‌کند، ابتدا مسیر درخواست با مسیر مناسب تطبیق داده می‌شود (برای مثال مسیر post برای /hello-world). سپس داده‌های موردنیاز دریافت و فایل قالب Twig تعیین‌شده برای آن مسیر (post.twig) رندر می‌شود.

در این فایل می‌توانید قالب‌های دیگر را وارد کنید یا از وراثت قالب‌ها استفاده کنید. همچنین برای دریافت داده‌های بیشتر می‌توانید Data API را فراخوانی کنید.

Twig

ما از Twig 3.0 برای قالب بندی استفاده می کنیم. این یک زبان قدرتمند با تعداد زیادی برچسب، فیلتر و توابع داخلی است. Twig همچنین دارای اسناد خوب و آسان برای دنبال کردن است، که یکی از دلایلی بود که ما Twig را نسبت به سایر زبان‌های قالب انتخاب کردیم. اگر تا به حال از آن استفاده نکرده اید، به صفحه Twig برای طراحان قالب مراجعه کنید، و ایده ای از نحوه کار آن خواهید داشت. در اصل، HTML با قدرت های فوق العاده است.

قالب‌ها

این پوشه حاوی فایل های قالب است. انواع مختلفی از فایل های قالب وجود دارد

نوع
توضیحات
مثال
اصلی
این فایل های قالب به طور مستقیم رندر می شوند.
index.twig post.twig
جزئی
این الگوها مستقیماً رندر نمی شوند بلکه در فایل های قالب اصلی گنجانده شده اند. آنها با یک خط زیر شروع می شوند (_)
_footer.twig
مسیر
از این الگوها برای تعریف مسیرهای سفارشی برای وبلاگ استفاده می شود. نام فایل با شروع می شود route-. ببینید مسیرهای سفارشی زیر
route-authors.twig
کامپوننت
از این قالب ها برای تعریف جدید استفاده می شود HTML ساختارهایی برای اجزای پیچیده مانند پیش نمایش پیوندها. ببینید نشانک پیوند.
component-rich-link.twig

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

  • توسعه دهنده پوسته (شما) آن را ایجاد می کند پوسته
  • وبلاگ نویس محتوا را ایجاد می کند (داده)
  • HB ترکیبی از پوسته و داده ها و وبلاگ را ایجاد می کند

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

4 شیء اصلی در HB وجود دارد: Blog ، Post ، Tag ، و Author. این اشیاء در صفحه Data API توضیح داده شده است.

نام متغیر
مسیرهای موجود
توضیحات
_blog
(همه)
یک شی بلاگ، که شامل تمام داده ها/تنظیمات در سطح وبلاگ است.
_lang
(همه)
یک شیء زبان برای زبان فعلی . همچنین باید در آن قرار داده شود <html lang="{{ _lang.code }}">
_config
(همه)
پیکربندی پوسته (config.yaml) به عنوان یک شی
_route
(همه)
فعلی مسیر نام
_posts
(همه)
آرایه ای از اشیاء Post، فیلتر شده توسط مسیر ، مقدار فیلتر
_featured_post
index
آرایه ای از اشیاء Posts (همه پست های برجسته)
_post
پست و صفحه
یک شیء پست
_tag
tag
یک شیء برچسب (برچسب فعلی)
_author
author
یک شی نویسنده (نویسنده فعلی)
_branding
همه
بولی، نشان دادن نام تجاری ویترو بلاگ .

هر مسیر دارای متغیرهای مختلفی است. ما هر متغیر را با _ پیشوند می کنیم تا با متغیرهایی که در داخل فایل های پوسته تعریف می کنید در تضاد نباشد (بدیهی است که نباید متغیرهای خود را در قالب Twig پیشوند _ قرار دهید)

متغیرهای جای‌نگهدار

از شما خواسته می‌شود که چند متغیر در پوسته خود قرار دهید تا چند چیز کار کنند.

متغیر جای‌نگهدار
محدوده ها
توضیحات
_head
(همه)
محل قبل از </head>. ما به طور خودکار برچسب های SEO، پیوند styles.css و code_head را که توسط وبلاگ نویس تنظیم شده است اضافه می کنیم.
_foot
(همه)
محل قبل از </body>. ما مجموعه code_foot توسط وبلاگ نویس را قرار می دهیم
_comments
پست و صفحه
برای تعبیه سیستم نظردهی
_comment_count (اختیاری)
پست و صفحه
برای ارائه تعداد نظرات آن صفحه. به عنوان مثال، برخی از پوسته ها دارای تعداد نظرات در بالا با پیوند به بخش نظرات هستند تا نظرات بیشتری را تشویق کنند.
_newsletter
پست و صفحه
برای جاسازی فرم اشتراک خبرنامه

ارسال همه متغیرها (به جز _lang) از طریق فیلتر template برای نمایش آنها به عنوان الگو کاملاً ضروری است.

{{ _head | template }}

{{ _head | template }} برابر است با {{ include(template_from_string(_head)) }} در Twig. ما فیلتر سفارشی template را تعریف کردیم تا نوشتن آن را برای شما آسان‌تر کنیم، زیرا اغلب در قالب‌های HB استفاده می‌شود.

ابزارهای کمکی Twig

ما چند توابع و فیلترهای سفارشی Twig را برای سهولت نوشتن الگوها ارائه می دهیم.

توابع

  • data - تابعی برای فراخوانی Data API. واکشی داده‌ها را در زیر ببینید.
{% set posts = data(endpoint="posts", filter="author.slug=user") %}
  • icon - تابعی برای دریافت نماد.
{{ icon('bootstrap', 'arrow-down', 20, 20) }}

تعریف عملکرد: icon(iconLibrary, iconName, width, height)

  • همه نام نمادها با حروف کوچک هستند و کلمات با - (arrow-down) از هم جدا می شوند.
  • این کتابخانه های نماد پشتیبانی می شوند
  • بوت استرپ
  • فونت فوق العادهفقط نمادهای رایگان
    • -regular را به نمادهای معمولی اضافه کنید (calendar-regular)
    • -solid را به نمادهای جامد اضافه کنید (calendar-solid)
    • چیزی برای نمادهای برند اضافه نکنید (github)
  • آیونیکون
  • قهرمانان
    • -solid را به نمادهای جامد اضافه کنید (archive-solid)
    • -outline را به طرح کلی نمادها اضافه کنید (archive-outline)
  • اکتیون ها
  • css.gg

    • در زیر هود، ما از کتابخانه منبع باز php-svg-icons استفاده می کنیم. اگر نیاز به افزودن کتابخانه‌های نمادهای بیشتری دارید، لطفاً یک PR به آنجا ارسال کنید.

فیلترها

  • asset_url - فیلتری برای پیوند دارایی ها
    • نام فایل دارایی را به URL مطلق آن تبدیل می کند.
    • آخرین مُهر زمان به‌روزرسانی‌شده را به‌عنوان پارامتر پرس و جو اضافه می‌کند (برای دور زدن حافظه پنهان مرورگر در به‌روزرسانی‌ها)
      • {{ 'script.js' | asset_url }}
      <script src="{{ 'script.js' | asset_url }}"></script>

// changes to:

<script src="https://blog.example.com/assets/script.js?v=12931923993"></script>
  • asset - فیلتری برای چاپ مستقیم دارایی ها (فقط برای دارایی های متنی مانند SVG)
    • {{ 'beauty.svg' | asset }}
  • pagination_page_url - فیلتری برای تبدیل شماره صفحه به کامل URL
    • <a href="{{ _pagination.page_prev | pagination_page_url }}">Previous Page</a>
  • lang - فیلتری برای ترجمه ها. بیشتر بدانید در بین المللی شدن.
  • lang_by_number - ببینید رشته های شرطی بر اساس یک عدد.
  • language_variant_url - ببینید تغییر زبان
  • toc - فیلتری برای تولید فهرست مطالب از رشته HTML . 
    {{ _post.content | toc }}

    به طور پیش فرض، تمام عناوین در فهرست مطالب گنجانده شده است. شما می توانید سطوح را به صورت زیر تنظیم کنید:

    {{ _post.content | toc('2,3') }}

تفاوت بین توابع و فیلترها می تواند در Twig کاملاً گیج کننده باشد. قانون کلی ما استفاده از توابع برای محاسبه چیزها (data و icon) و استفاده از فیلترها هنگام اعمال تبدیل است (asset_url ، asset ، و غیره).

دریافت داده‌ها

از تابع data برای واکشی داده ها از Data APIاستفاده کنید.

<!-- Fetch data -->
{% set recent_posts = data(endpoint="posts", sort="published_at DESC", limit="5") %}

<!-- Render UI -->
<div id="recent-posts">
	{% for post in recent_posts.data %} {% include '_recent-post-card.twig' with post %} {% endfor %}
</div>

از آرگومان با نام endpoint برای تنظیم نقطه پایانی API استفاده کنید. شما می توانید تمام پارامترهای دیگر را فقط با ارسال آنها به عنوان آرگومان های نامگذاری شده به تابع data Twig تنظیم کنید (مثلاً: sort="published_at DESC").

مسیرهای سفارشی

دو راه برای اضافه کردن مسیرهای سفارشی وجود دارد:

  • وبلاگ نویس می تواند مسیرهای سفارشی را از کنسول اضافه کند (به اسنادمراجعه کنید).
  • توسعه دهندگان پوسته می توانند با افزودن فایل هایی به نام route-{route}.twig به پوشه templates مسیرهای سفارشی را تعریف کنند.

گزینه اول قوی‌تر است و راه آسان‌تری را برای تنظیم خودکار متغیرهای ورودی _posts (با فیلتر کردن)، _tag ، _author و غیره ارائه می‌کند تا بتوانید بدون تماس با Data API به آنها دسترسی داشته باشید. اما، به عنوان یک توسعه دهنده پوسته، باید از گزینه دوم استفاده کنید.

برای مثال، فرض کنید تصمیم گرفتید که پوسته شما صفحه‌ای را می‌خواهد که همه نویسندگان وبلاگ را فهرست کند. می توانید یک route-authors.twig را به پوشه templates اضافه کنید. اگر وبلاگ درخواستی به /authors دریافت کند، این الگو به صورت خودکار ارائه می شود.