Разработка кастомного блока Concrete CMS

Разработка кастомного блока Concrete CMS

Блок (Block) — базовый строительный элемент контента в Concrete CMS. Встроенные блоки (Content, Image, Form) покрывают типовые задачи, но нестандартный функционал требует разработки собственных блоков. Кастомный блок — это PHP-класс с формой редактирования, шаблоном вывода и схемой хранения данных.

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

Блок располагается в 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>

Concrete CMS автоматически создаёт и обновляет таблицы при установке/обновлении пакета.

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;
    }
}

add.php / edit.php

<?php defined('C5_EXECUTE') or die('Access Denied.'); ?>

<div class="ccm-ui">
    <div class="form-group">
        <label><?= t('Заголовок') ?> *</label>
        <?= $form->text('headline', $headline ?? '', ['class' => 'form-control', 'maxlength' => 255]) ?>
    </div>

    <div class="form-group">
        <label><?= t('Подзаголовок') ?></label>
        <?= $form->text('subheadline', $subheadline ?? '', ['class' => 'form-control']) ?>
    </div>

    <div class="form-group">
        <label><?= t('Текст') ?></label>
        <?= $form->textarea('body', $body ?? '', ['class' => 'form-control', 'rows' => 4]) ?>
    </div>

    <div class="form-group">
        <label><?= t('Иконка') ?></label>
        <?php
        $bf = $this->app->make(\Concrete\Core\Form\Service\Widget\FilePicker::class);
        echo $bf->image('icon_fID', 'icon_fID', t('Выбрать иконку'), $icon_file ?? null);
        ?>
    </div>

    <div class="form-group">
        <label><?= t('URL ссылки') ?></label>
        <?= $form->url('link_url', $link_url ?? '', ['class' => 'form-control']) ?>
    </div>

    <div class="form-group">
        <label><?= t('Текст ссылки') ?></label>
        <?= $form->text('link_text', $link_text ?? '', ['class' => 'form-control']) ?>
    </div>

    <div class="form-group">
        <label><?= t('Макет') ?></label>
        <?= $form->select('layout', $layout_options, $layout ?? 'default', ['class' => 'form-select']) ?>
    </div>
</div>

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>

Кэширование блока

Параметры кэша задаются в контроллере:

protected $btCacheBlockRecord        = true;  // кэш записи из БД
protected $btCacheBlockOutput        = true;  // кэш HTML-вывода
protected $btCacheBlockOutputLifetime = 3600; // TTL в секундах
// При наличии редактируемого контента:
protected $btCacheBlockOutputOnPost = false;  // не кэшировать после POST

Блок с несколькими записями (btRecordContent)

Для блоков типа «список элементов» используется btExportTables и дочерняя таблица:

// В controller.php
protected $btExportTables  = ['btFeatureList', 'btFeatureListItems'];
protected $btExportContent = ['icon_fID']; // поля с файлами для экспорта

// Сохранение дочерних записей
public function save(array $args): void {
    parent::save($args);
    $db = $this->app->make('database')->connection();
    $db->delete('btFeatureListItems', ['bID' => $this->bID]);
    foreach ($args['items'] as $item) {
        $db->insert('btFeatureListItems', [
            'bID'  => $this->bID,
            'sort' => (int)$item['sort'],
            'text' => strip_tags($item['text']),
        ]);
    }
}

Сроки разработки блока