Розробка кастомного шаблону Kirby (PHP)

Розробка користувацького шаблону Kirby (PHP)

Шаблон в Kirby — звичайний PHP-файл. Без рушія шаблонизації, без компіляції, без абстракцій. Файл templates/article.php рендериться, коли сторінка має тип article (назва файлу контенту article.txt). Змінні $page, $site, $kirby доступні автоматично, інші передаються через контроллер.

Снипети — будівельні блоки

Снипети — це include-файли з можливістю передачі даних:

<?php snippet('header', ['title' => $page->title()]) ?>

<main>
    <?php snippet('hero', ['page' => $page]) ?>
    <?php snippet('content-blocks', compact('page')) ?>
</main>

<?php snippet('footer') ?>

<?php
// site/snippets/hero.php
/** @var \Kirby\Cms\Page $page */
?>
<section class="hero" style="--bg: url('<?= $page->cover()->toFile()?->url() ?>')">
    <div class="hero__inner">
        <h1 class="hero__title"><?= $page->title()->html() ?></h1>
        <?php if ($page->subtitle()->isNotEmpty()): ?>
            <p class="hero__subtitle"><?= $page->subtitle()->html() ?></p>
        <?php endif ?>
    </div>
</section>

Робота з полями

Kirby повертає об'єкт поля, а не рядок. Методи можна ланцюжити:

// текст
$page->title()->html()
$page->title()->upper()
$page->title()->slug()
$page->title()->or('Без назви')->html()

// дата
$page->date()->toDate('d.m.Y')
$page->date()->toDate('U') // Unix timestamp
$page->date()->isNotEmpty()

// Markdown → HTML
$page->text()->kirbytext()

// обрізка тексту
$page->text()->excerpt(150, true, '...')

// числа
$page->price()->toFloat()
$page->count()->toInt()

// boolean-поля
$page->featured()->isTrue()
$page->active()->toBool()

Складний шаблон: список з фільтрацією

<?php
// site/templates/products.php
/** @var \Kirby\Cms\Page $page */
/** @var \Kirby\Cms\Pages $products */
/** @var \Kirby\Cms\Pagination $pagination */
/** @var string $activeCategory */

snippet('header');
?>

<div class="products-page">
    <aside class="filters">
        <nav>
            <a href="<?= $page->url() ?>"
               class="<?= $activeCategory ? '' : 'active' ?>">
                Всі
            </a>
            <?php foreach ($categories as $cat): ?>
                <a href="<?= $page->url(['params' => ['category' => $cat]]) ?>"
                   class="<?= $activeCategory === $cat ? 'active' : '' ?>">
                    <?= html($cat) ?>
                </a>
            <?php endforeach ?>
        </nav>
    </aside>

    <section class="products-grid">
        <?php foreach ($products as $product): ?>
            <?php snippet('product-card', compact('product')) ?>
        <?php endforeach ?>

        <?php if ($products->isEmpty()): ?>
            <p class="empty-state">Нічого не знайдено</p>
        <?php endif ?>
    </section>

    <?php if ($pagination->hasPages()): ?>
        <nav class="pagination">
            <?php if ($pagination->hasPrevPage()): ?>
                <a href="<?= $pagination->prevPageURL() ?>">← Назад</a>
            <?php endif ?>
            <span><?= $pagination->page() ?> / <?= $pagination->pages() ?></span>
            <?php if ($pagination->hasNextPage()): ?>
                <a href="<?= $pagination->nextPageURL() ?>">Вперід →</a>
            <?php endif ?>
        </nav>
    <?php endif ?>
</div>

<?php snippet('footer') ?>

Вкладені структури (structure field)

Структурне поле в Blueprint:

gallery:
    type: structure
    label: Галерея
    fields:
        image:
            type: files
            max: 1
        caption:
            type: text
        alt:
            type: text

Вивід у шаблоні:

<?php if ($page->gallery()->isNotEmpty()): ?>
<div class="gallery">
    <?php foreach ($page->gallery()->toStructure() as $item): ?>
        <?php $img = $item->image()->toFile() ?>
        <?php if ($img): ?>
        <figure>
            <img
                src="<?= $img->crop(600, 400)->url() ?>"
                alt="<?= $item->alt()->or($img->alt())->html() ?>"
            >
            <?php if ($item->caption()->isNotEmpty()): ?>
                <figcaption><?= $item->caption()->html() ?></figcaption>
            <?php endif ?>
        </figure>
        <?php endif ?>
    <?php endforeach ?>
</div>
<?php endif ?>

Блочний редактор (blocks field)

Kirby Blocks — аналог Gutenberg. Кожний блок рендериться окремим снипетом:

// templates/article.php
<?= $page->text()->toBlocks() ?>

Користувацький блок callout:

# site/blueprints/blocks/callout.yml
name: Callout
icon: alert
fields:
    type:
        type: select
        options:
            info: Інформація
            warning: Попередження
            danger: Небезпека
    text:
        type: writer

<?php
// site/snippets/blocks/callout.php
/** @var \Kirby\CMS\Block $block */
?>
<div class="callout callout--<?= $block->type()->html() ?>">
    <?= $block->text()->kirbytext() ?>
</div>

Хелпери та глобальні функції

// вивід з екрануванням
html($string)
esc($string, 'attr')
esc($string, 'url')

// URL
url('blog/first-post')
url('/', ['params' => ['page' => 2]])

// зображення
thumb($image, ['width' => 800, 'quality' => 85])

// переклад
t('read.more') // з site/languages/*.php
tt('items.count', $count) // з числом для склонення

Умовні шаблони

Kirby дозволяє створювати варіантні шаблони за суфіксом:

• templates/article.php — основний
• templates/article.preview.php — режим предпросмотру
• templates/article.rss.php — RSS-версія

Переключення: $page->render(['template' => 'article.rss']).

Терміни розробки

Шаблон для одного типу сторінок з блочним редактором та галереєю: 2–3 дні. Повний комплект шаблонів для корпоративного сайту (головна, послуги, блог, контакти, 404): 1–2 тижні з урахуванням верстки.