پوسته و اجزای تشکیل دهنده

بعد از انجام تمام تنظیمات و تولید محتوا، مطمینا نیازمند خروجی برای محتوای تولید شده خواهیم بود، قالب یا template یا همان پوسته‌های خروجی، به ما برای ساختن ظاهر خروجی مطابق سلیقه و نیازهایمان کمک خواهند کرد.

هر قالب یک دایرکتوری است در شاخه‌ی template از شاخه‌ی اصلی. برای استفاده از قالب ها نام این دایرکتوری را در فایل تنظیمات در مقابل فیلد template وارد کنید.

اجزای اصلی تشکیل دهنده هر قالب، این پنج فایل هستند

/template/THEME/
.
├── archive.tt2
├── atom.tt2
├── index.tt2
├── main.tt2
└── post.tt2

همچنین دایرکتوری به نام include هم در شاخه‌ی پوسته، هنگام پردازش نهایی دیده میشود و اگر بخواهید ماژول‌هایی مانند header یا sidebar در نظر داشته باشید میتوانید در این شاخه آن‌ها را ذخیره کنید.

/template/THEME/
.
├── archive.tt2
├── atom.tt2
├── include
│   ├── footer
│   ├── header
│   ├── navbar
│   ├── sidebar
│   ├── some
│   ├── thing
│   └── else
├── index.tt2
├── main.tt2
└── post.tt2

در کل همان پنج فایل با پسوند tt2 اجزای اصلی تشکیل دهنده یک پوسته هستند و وجودشان الزامیست، تنها باید به این نکته اشاره کرد که آرشیو و post را میتوان به هر تعداد نام دیگر که بخواهید تکثیر کنید، که در ادامه در این مورد هم خواهیم خواند.

اما این پنج فایل چه هستند و چه میکنند؟

main

الگویی است که صفحه‌ی مشترک بین تمام طبقات براساس آن ساخته میشود، یا همان صفحه اصلی که زمان باز کردن سایت در شاخه‌ی پیش فرض دیده میشود. اگر در فایل config.yml مقدار url را برابر SITE.com قرارداده باشید و root را مساوی / تنظیم کنید، main در این صفحه تشکیل میشود:

SITE.com/index.html

index

الگوی سازنده‌ی صفحات اول هر طبقه و صفحات ادامه‌ی صفحه‌ی اصلی، در root هر طبقه ساخته خواهد شد
اگر root در فایل config/blog.yml مساوی با /blog تنظیم شده باشد، index.tt2 الگوی سازنده‌ی این صفحات است

Site.com/blog/
Site.com/blog/page/2/
Site.com/blog/page/3/
Site.com/blog/page/...

archive

الگوی عمومی برای ساختن صفحات آرشیو

آرشیو زمانی و هر نوع آرشیو دیگری که در فیلد lists در فایل تنظیمات مشخص کرده باشید بر اساس این فایل ساخته می‌شوند. برای مثال اگر در سربرگ نوشته‌هایتان فیلد date موجود باشد و در فایل تنظیمات این آرشیو‌ها را مشخص کرده باشید

lists:
 - categories
 - tags
 - author

این الگو این صفحات را خواهد ساخت

Site.com/blog/archive/2017
Site.com/blog/archive/2017/01/
Site.com/blog/archive/2017/02/
Site.com/blog/archive/...

Site.com/blog/author/kiavash/
Site.com/blog/author/...

Site.com/blog/categories/CAT1/
Site.com/blog/categories/CAT2/
Site.com/blog/categories/CAT3/
Site.com/blog/categories/....

Site.com/blog/tagss/TAG1/
Site.com/blog/tagss/TAG2/
Site.com/blog/tagss/TAG3/
Site.com/blog/tagss/...

قبلا گفته شد که صفحات آرشیو را به هر تعداد که بخواهید میتوانید تکثیر کنید
اگر بخواهید هر کدام از آرشیو‌هایی که دارید، قالب متفاوتی داشته باشد، میتوانید هم‌نام آن آرشیو مثل categories یا هر چیز دیگری، یک فایل با پسوند tt2 در شاخه‌ی پوسته در کنار ساید فایل‌های tt2 قرار دهید، چیزی مثل این:

template/THEME/categories.tt2

از این به بعد آرشیو موضوعی categories به جای archive.tt2 از الگویی که در categories.tt2 تنظیم کرده‌اید برای ساختن خروجی استفاده خواهد کرد.

post

هر فایل محتوایی که میسازید یک آدرس ثابت و ایستا برای خود دارد، که خروجی آن بر اساس این الگو تولید میشود.
برای مثال ممحتوایی در طبقه blog با این مشخصه ها را در نظر داشته باشید:

_index: 5start hotels
_permalink: :year/:title

خروجی آن در این آدرس تولید میشود

/blog/2017/5star-hotels/

تمام آدرس‌های ثابت محتوای تولید شده از الگویی که در فایل post.tt2 تعریف کرده‌اید برای ساخت استفاده میکنند

یک قابلیت آزمایشی
در صورتیکه در سربرگ پست، فیلد _layout را با نام یک فایل معتبر در شاخه‌ی قالب مقدار دهی کنید، به جای post.tt2 آن پست با استفاده از فایل جدید تولید میشود

_layout: custom_page.tt2

اگر در شاخه‌ی قالب فایل custom.tt2 موجود باشد، به جای post.tt2 از آن استفاده خواهد شد.

atom

فید یا همان feed.xml با استفاده از این الگو ساخته میشود، از آنجا که نحوه‌ی تولید فیدها از یک استاندارد مشخص پیروی میکنند، معمولا نیازی به تغییر ندارد، مگر اینکه بخواهید برای خروجی‌های متفاوتی مثل پادکست یا از این دست آن را بهینه سازی کنید.

برچسب‌های مورد استفاده در پوسته

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

برچسب‌های موجود

هر یک از این برچسب ها برای لود شدن باید بین دوآکولاد باز و بسته شوند:

{{ ROOT }}
{{ TITLE }}
{{ SomeThingElse }}
...

MainTITLE

تیتر اصلی سایت ذخیره شده در فایل تنظیمات مرکزی یا همان config.yml نحوه‌ استفاده:

{{ MainTITLE }}

MainDESCRIPTION

توضیحات اصلی سایت ذخیره شده در فایل تنظیمات مرکزی یا همان config.yml نحوه‌ استفاده:

{{ MainDESCRIPTION }}

MainURL

آدرس اصلی سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: YOURSITE.com نحوه‌ استفاده:

{{ MainURL }}

MainROOT

ریشه اصلی سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: / نحوه‌ استفاده:

{{ MainROOT }}

MainSTATIC

شاخه فایل‌های ثابت سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: /statics نحوه‌ استفاده:

{{ MainSTATIC }}

MainIMAGEURL

شاخه فایل‌های ثابت سایت ذخیره شده در فایل تنظیمات مرکزی مقدار بازگشتی برای مثال: /statics/images نحوه‌ استفاده:

{{ MainIMAGEURL }}

MainAUTHOR

نام نویسنده ذخیره شده در فایل تنظیمات مرکزی نحوه‌ استفاده:

{{ MainAUTHOR }}

MainEMAIL

ایمیل نویسنده نحوه‌ استفاده:

{{ MainEMAIL }}

PageTITLE

تیتر صفحه، در صورتیکه از ماژولی شبیه به header برای لود کردن قسمت بالایی صفحات html به شکل ثابت در تمام صفحات استفاده کنید این برچسب کمک بسیاری برای تگ <title> خواهد کرد، برای مثال در main.tt2 مقداری برابر TITLE و در index.tt2 مساوی FloorTITLE خواهد داشت نحوه‌ استفاده:

{{ PageTitle }}

FLOORS

نام تمام طبقات موجود در سایت به همراه توضیحاتشان و تعداد مشخصی از پست‌ها که در فیلد post_num در فایل تنظیمات مشخص کرده‌اید

مقادیر موجود در این برچسب:

name
description

posts (list)

ش posts شامل تعداد مشخص از آخرین ارسال‌های شماست، تعداد ارسال‌های موجود در این کلید از config.yml و فیلد post_num برداشت میشود.
تمام مقادیری که برای POSTS که در قسمت‌های بعد توضیح داده میشود در مورد لیست posts در Floors نیز قابل استفاده است

نحوه‌ استفاده:

{{ FOREACH FLOORS.values }}
  {{ name }}
  {{ description }}

  {{ FOREACH posts }}
    <h2><a href="{{ url }}">{{ title }}</a><h2>
    <h4>{{ CALENDAR.day }}-{{ CALENDAR.month_name }}-{{ CALENDAR.year }}</h4>
    <p>{{ body.less }}</p>
  {{ END }}

{{ END }}

ENTRIES

کلید-مقداری از تمام محتوای تولید شده در سایت، در مورد کارکرد این برچسب، توضیحات UTIDS را بخوانید

UTIDS

کلید نام تمام محتوای موجود در سایت مرتب شده بر اساس مقدار utid هر پست، برابر با utid هر پست، برای لود کردن محتوا در برچسب Entries قابل استفاده است.

این برچسب تنها مختص به main.tt2 میباشد

تمام مقادیر معتبر برای POSTS در زیر این برچسب با اضافه کردن ENTRIES.$id نیز قابل استفاده هستند نحوه‌ی استفاده به همراه ENTRIES

{{ FOREACH id IN UTIDS }}
   <h2><a href="{{ ENTRIES.$id.url }}">{{ ENTRIES.$id.title }}</a><h2>
   <h4>{{ ENTRIES.$id.CALENDAR.day }}-{{ ENTRIES.$id.CALENDAR.month_name }}-{{ ENTRIES.$id.CALENDAR.year }}</h4>
   <p>{{ ENTRIES.$id.body.less }}</p>
{{ END }}

TITLE

تیتر اصلی طبقه، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ TITLE }}

DESCRIPTION

توضیحات طبقه، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ DESCRIPTION }}

URL

آدرس سایتی که طبقه در آن منتشر میشود، ذخیره شده در فیلد url فایل تنظیمات طبقه.

نحوه‌ استفاده:

{{ URL }}

ROOT

آدرس شاخه‌ی ریشه، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ ROOT }}

AUTHOR

نام نویسنده، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ AUTHOR }}

EMAIL

نام نوسنده، ذخیره شده در فایل تنظیمات طبقه
نحوه‌ استفاده:

{{ EMAIL }}

BUILD

اطلاعات زمان ساختن آخرین نسخه از سایت، یا تاریخ زمانی که mira build را اجرا میکنید.

{{ BUILD.date }} : 2017-03-25 18:44:03
{{ BUILD.year }}
{{ BUILD.month }}
{{ BUILD.month_name }}
{{ BUILD.month_abbr }}
{{ BUILD.day }}
{{ BUILD.day_name }}
{{ BUILD.day_abbr }}
{{ BUILD.hour }}
{{ BUILD.minute }}
{{ BUILD.second }}

ARCHIVES

تمام آرشیوهای موجود در طبقه

در صورتیکه از یک پوسته یکسان برای چند طبقه که آرشیوهایی با فیلدها و نام‌های متفاوت دارند استفاده میکنید، میتوانید برای نمایش تمام آرشیو‌ها، بدون اهمیت اینکه چه نامی دارند از این برچسب استفاده کنید.

مقدار این برچسب چیزی شبیه به این است:

'categories' => {
          "CAT1" => {
                'name' => "CAT1",
                    'url' => "/FLOOR/categories/CAT1namespace/",
                    'posts' => [
                               '20170210173327',
                               '20170210173313',
                               '20170210174503',
                               '20170210172431',
                               '20170210173319'
                             ]
              },
          "CAT2" => {
                'name' => "CAT2",
                    'url' => "/FLOOR/categories/CAT2namespace/",
                    'posts' => [
                               '20170210173327',
                               '20170210173313',
                               '20170210174503',
                               '20170210172431',
                               '20170210173319'
                             ]
             }
},
'date' => {
      '201702' => {
              'year' => '2017',
              'month' => '02',
              'url' => '/fa/archive/2017/02/',
              'name' => 'February 2017',
              'number' => '2017 - 02',
              'posts' => [
                         '20170210173327',
                         '20170210173313',
                         '20170210174503',
                         '20170210172431',
                         '20170210173319'
                       ]
              }
}

با استفاده از IF میتوانید رفتار متفاوتی را برای هر نوع آرشیو در صورت وجود تعریف کنید

نحوه استفاده:

{{ FOREACH archive IN ARCHIVES.pairs }}
  {{ archive.key }} نام آرشیو
  <hr>
  {{ FOREACH item IN archive.value.values }}
    <a href="{{ item.url }}">{{ item.name }}</a>
    {{ IF (archive.key == 'categories') }}<br>{{ END }}
    {{ IF (archive.key == 'date') or (archive.key == 'jdate') }}<br>{{ END }}
    {{ IF (archive.key == 'author') }}<br>{{ END }}
    {{ IF (archive.key == 'tags') }}&nbsp;-&nbsp;{{ END }}
  {{- END }}
  <br>
{{- END }}

سایر برچسب‌ها برای آرشیو

میرا برای هر آرشیو، همنام با همان آرشیو، مقداری برای قالب تولید میکند، برای مثال اگر در فایل تنظیمات برای آرشیو ها فیلد categories را به عنوان آٰشیو مشخص کرده باشید، حلقه‌ای به نام CATEGORIES_ARCHIVE نیز در قالب قابل استفاده خواهد بود، یا برای tags، میتوانید از TAGS_ARCHIVE استفاده کنید.

اطلاعات موجود در هرکدام از این مقادیر، شبیه به این خواهند بود

CATEGORIES_ARCHIVE = [
          {
            'name' => "CAT1",
            'url' => "/FLOOR/categories/CAT1namespace/",
            'posts' => [
                         '20170210172431',
                         '20170210174503',
                         '20170210173327',
                         '20170210173313',
                         '20170210173319'
                       ]
          },
          {
            'name' => "CAT2",
            'url' => "/FLOOR/categories/CAT2namespace/",
            'posts' => [
                         '20170210172431',
                         '20170210174503',
                         '20170210173327',
                         '20170210173313',
                         '20170210173319'
                       ]
          },
        ]

برای استفاده از این برچسب‌ها باید در حلقه‌ای که با FOREACH تولید میکنید از آن‌ها استفاده کنید

نحوه استفاده برای فیلد فرضی categories

{{ FOREACH CATEGORIES_ARCHIVE.values }}
  <a href="{{ url }}">{{ name }}</a> - <small>{{ posts.size }}</small><br>
{{ END }}

یا

{{ FOREACH cat IN CATEGORIES_ARCHIVE.values }}
  <a href="{{ cat.url }}">{{ cat.name }}</a> - <small>{{ cat.posts.size }}</small><br>
{{ END }}

همانطور که مشخص است در posts، تمام utid ها برگشت داده شده، پس برای نمایش تک تک فایل‌های موجود در هر دسته میتوان از ENTRIES کمک گرفت

{{ FOREACH CATEGORIES_ARCHIVE.values }}
  <a href="{{ url }}">{{ name }}</a> - <small>{{ posts.size }}</small><br>
  {{ FOREACH id IN posts.sort }}
    <h5><a href="{{ ENTRIES.$id.url }}">{{ ENTRIES.$id.title }}</a></h5>
  {{ END }}
{{ END }}

مثلما به جای id و $id از هر نام دیگری که بخواهید میتوانید استفاده کنید.