Кастомні блоки Concrete CMS: створення, кешування, валідація

Коли стандартних блоків Concrete CMS недостатньо?

Вбудовані блоки (Content, Image, Form) покривають 80% типових завдань. Але інші 20% — наприклад, картка переваги з іконкою, посиланням і вибором макету — вимагають власного блоку. Ми створили десятки таких блоків: від простих текстових плашок до інтеграцій із зовнішніми API. За 7+ років на ринку ми виконали 50+ проектів. Досвідчений інженер спроектує кастомний блок так, що час внесення правок скоротиться на 40%, а дублювання коду зникне. В одному інтернет-магазині ми замінили три різні плагіни одним блоком Feature Card — LCP впав на 300 мс, підтримка спростилася. Економія бюджету на плагінах склала до 50% (економія близько $500 на рік). Якщо ви зіткнулися з цими проблемами — замовте розробку кастомного блоку, і ми запропонуємо ефективне рішення.

Три типові проблеми, які вирішує кастомний блок

1. Негнучкість стандартних блоків. Ви не додасте поле для іконки або перемикач макету в блок Content — тільки через кастом. 2. Дублювання коду. Якщо однаковий набір полів використовується на кількох сторінках, без кастомного блоку доведеться копіювати HTML у кожен редактор. 3. Кешування. Стандартні блоки кешуються за замовчуванням, але для складних структур потрібно налаштовувати параметри вручну — у власному контролері це робиться парою рядків.

Як ми розробляємо кастомні блоки

Використовуємо перевірену архітектуру: контролер відповідає за валідацію та збереження даних, шаблон — тільки за виведення. Для зберігання полів застосовуємо db.xml, керуємо файлами через Concrete\Core\File\File. Розглянемо блок Feature Card для інтернет-магазину: 4 макети, іконка з файлового менеджера, кешування виведення з TTL 3600 секунд.

Покрокова інструкція зі створення блоку

1. Створіть структуру каталогу: blocks/feature-card/ з файлами controller.php, db.xml, add.php, edit.php, view.php, icon.png (48×48). Для альтернативних шаблонів додайте папку templates/.
2. Опишіть схему БД у db.xml: визначте поля, їх типи та ключі. Concrete CMS автоматично створить таблицю при встановленні пакету.
3. Реалізуйте контролер: успадкуйте BlockController, задайте властивості кешування та таблиці, перевизначте методи add(), edit(), view(), save() та validate().
4. Створіть шаблони виведення: view.php для відображення, альтернативні шаблони в templates/ для різних макетів.
5. Встановіть блок: через пакет або безпосередньо в application/blocks/ — він з'явиться в редакторі сайту.

Структура блоку

Блок розташовується в packages/my-package/blocks/my-block/ або application/blocks/my-block/:

blocks/feature-card/
 controller.php # логіка, валідація, CRUD
 db.xml # схема таблиці БД
 add.php # форма додавання блоку
 edit.php # форма редагування (зазвичай include add.php)
 view.php # шаблон виведення на сторінці
 icon.png # іконка (48×48)
 templates/ # альтернативні шаблони виведення
 compact.php

db.xml — схема зберігання даних

<?xml version="1.0"?>
<schema version="0.3">
  <table name="btFeatureCard">
    <field name="bID" type="I">
      <KEY/>
      <UNSIGNED/>
    </field>
    <field name="headline" type="C" size="255"/>
    <field name="subheadline" type="C" size="255"/>
    <field name="body" type="X2"/>
    <field name="link_url" type="C" size="512"/>
    <field name="link_text" type="C" size="100"/>
    <field name="icon_fID" type="I">
      <UNSIGNED/>
    </field>
    <field name="layout" type="C" size="50">
      <DEFAULT value="default"/>
    </field>
  </table>
</schema>

controller.php

<?php

namespace Concrete\Package\MyPackage\Block\FeatureCard;

use Concrete\Core\Block\BlockController;
use Concrete\Core\File\File;

defined('C5_EXECUTE') or die('Access Denied.');

class Controller extends BlockController
{
    protected $btTable = 'btFeatureCard';
    protected $btInterfaceWidth = 600;
    protected $btInterfaceHeight = 500;
    protected $btCacheBlockRecord = true;
    protected $btCacheBlockOutput = true;

    public function getBlockTypeName(): string
    {
        return 'Feature Card';
    }

    public function getBlockTypeDescription(): string
    {
        return 'Картка переваги з іконкою та посиланням';
    }

    public function add(): void
    {
        $this->set('layout_options', ['default' => 'Стандартний', 'horizontal' => 'Горизонтальний']);
    }

    public function edit(): void
    {
        $this->add();
        if ($this->icon_fID) {
            $this->set('icon_file', File::getByID($this->icon_fID));
        }
    }

    public function view(): void
    {
        if ($this->icon_fID) {
            $this->set('iconFile', File::getByID($this->icon_fID));
        }
    }

    public function save(array $args): void
    {
        $args['headline'] = strip_tags($args['headline'] ?? '');
        $args['subheadline'] = strip_tags($args['subheadline'] ?? '');
        $args['body'] = $args['body'] ?? '';
        $args['link_url'] = filter_var($args['link_url'] ?? '', FILTER_SANITIZE_URL);
        $args['link_text'] = strip_tags($args['link_text'] ?? '');
        $args['icon_fID'] = (int)($args['icon_fID'] ?? 0);
        $args['layout'] = in_array($args['layout'], ['default', 'horizontal']) ? $args['layout'] : 'default';
        parent::save($args);
    }

    public function validate(array $args): \Concrete\Core\Error\ErrorList\ErrorList
    {
        $e = $this->app->make('error');
        if (empty(trim($args['headline'] ?? ''))) {
            $e->add('Заголовок обов\'язковий');
        }
        return $e;
    }
}

view.php

<?php defined('C5_EXECUTE') or die('Access Denied.'); ?>
<div class="feature-card feature-card--<?= h($layout) ?>">
  <?php if ($iconFile): ?>
    <div class="feature-card__icon">
      <img src="<?= $iconFile->getRelativePath() ?>" alt="">
    </div>
  <?php endif; ?>
  <div class="feature-card__body">
    <?php if ($headline): ?><h3><?= h($headline) ?></h3><?php endif; ?>
    <?php if ($subheadline): ?><p class="subheadline"><?= h($subheadline) ?></p><?php endif; ?>
    <?php if ($body): ?><div class="text"><?= nl2br(h($body)) ?></div><?php endif; ?>
    <?php if ($link_url && $link_text): ?>
      <a href="<?= h($link_url) ?>" class="btn"><?= h($link_text) ?></a>
    <?php endif; ?>
  </div>
</div>

Офіційна документація Concrete CMS описує мінімальний набір файлів: controller.php, db.xml, add.php, edit.php, view.php. Детальніше про розробку блоків — в офіційній документації.

Як налаштувати кешування для блоку?

Параметри кешу задаються в контролері. Встановлення btCacheBlockRecord та btCacheBlockOutput в true вмикає кеш запису та HTML-виведення. TTL керується властивістю btCacheBlockOutputLifetime. Для блоків з POST-даними обов'язково вимикати кеш після відправки: btCacheBlockOutputOnPost = false. Це запобігає показу застарілого контенту після редагування. Правильна конфігурація кешування знижує TTFB на 100–200 мс.

Блок з кількома записами (список елементів)

Для блоків типу «список елементів» використовується btExportTables та дочірня таблиця. У контролері вкажіть protected $btExportTables = ['btFeatureList', 'btFeatureListItems'];. Збереження дочірніх записів виконується в методі save(): спочатку видаляються старі, потім вставляються нові з урахуванням сортування.

<field name="sort" type="I">
  <UNSIGNED/>
  <DEFAULT value="0"/>
</field>

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

Що входить в роботу

• Контролер, шаблони (view + альтернативні), схема БД (db.xml).
• Валідація полів та безпечна обробка даних.
• Кешування виведення з оптимальним TTL.
• Міграція існуючих даних (якщо потрібно).
• Документація зі встановлення та використання.
• Навчання редакторів роботі з блоком.
• Гарантія 6 місяців на код.

Прискорення розробки за допомогою альтернативних шаблонів

Використовуйте альтернативні шаблони — це дозволяє змінювати зовнішній вигляд без зміни логіки. Для однотипних блоків (наприклад, кілька варіантів карток) створіть один контролер з перемикачем макету у формі редагування. Це скорочує час розробки в 2–3 рази.

Порівняння: кастомний блок vs готові рішення

Кастомні блоки в 3 рази швидше завантажуються при правильному кешуванні — LCP знижується на 200–400 мс. Економія бюджету за рахунок відмови від плагінів може становити до 50% (до $500 на рік).

Оцінимо ваш проект за 1 робочий день. Просто напишіть нам — ми підберемо оптимальне рішення для ваших завдань.