Кастомные блоки Concrete CMS: разработка от контроллера до кэширования

Когда стандартных блоков Concrete CMS недостаточно?

Встроенные блоки (Content, Image, Form) покрывают 80% типовых задач. Но остальные 20% — например, карточка преимущества с иконкой, ссылкой и выбором макета — требуют собственного блока. Мы создали десятки таких блоков: от простых текстовых плашек до интеграций с внешними API. Опытный инженер спроектирует кастомный блок так, что время внесения правок сократится на 40%, а дублирование кода исчезнет. В одном интернет-магазине мы заменили три разных плагина одним блоком Feature Card — LCP упал на 300 мс, поддержка упростилась. Если вы столкнулись с этими проблемами — закажите разработку кастомного блока, и мы предложим эффективное решение.

Три типичные проблемы, которые решает кастомный блок

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%.

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