Concrete CMS Custom Block Development

Concrete CMS Custom Block Development

A block is the basic building element of content in Concrete CMS. Built-in blocks (Content, Image, Form) cover typical tasks, but non-standard functionality requires developing your own blocks. Custom block is a PHP class with editing form, output template, and database schema.

Block Structure

Block located in packages/my-package/blocks/my-block/ or application/blocks/my-block/:

blocks/feature-card/
  controller.php     # logic, validation, CRUD
  db.xml             # DB table schema
  add.php            # block add form
  edit.php           # edit form (usually include add.php)
  view.php           # output template on page
  icon.png           # icon (48×48)
  templates/         # alternative output templates
    compact.php

db.xml — Data Storage Schema

<?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 automatically creates and updates tables on package install/update.

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 'Advantage card with icon and link'; }

    public function add(): void {
        $this->set('layout_options', ['default' => 'Standard', 'horizontal' => '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('Title is required');
        }
        return $e;
    }
}

add.php / edit.php

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

<div class="ccm-ui">
    <div class="form-group">
        <label><?= t('Title') ?> *</label>
        <?= $form->text('headline', $headline ?? '', ['class' => 'form-control', 'maxlength' => 255]) ?>
    </div>

    <div class="form-group">
        <label><?= t('Subtitle') ?></label>
        <?= $form->text('subheadline', $subheadline ?? '', ['class' => 'form-control']) ?>
    </div>

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

    <div class="form-group">
        <label><?= t('Icon') ?></label>
        <?php
        $bf = $this->app->make(\Concrete\Core\Form\Service\Widget\FilePicker::class);
        echo $bf->image('icon_fID', 'icon_fID', t('Select icon'), $icon_file ?? null);
        ?>
    </div>

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

    <div class="form-group">
        <label><?= t('Link Text') ?></label>
        <?= $form->text('link_text', $link_text ?? '', ['class' => 'form-control']) ?>
    </div>

    <div class="form-group">
        <label><?= t('Layout') ?></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>

Block Caching

Cache parameters set in controller:

protected $btCacheBlockRecord        = true;  // cache DB record
protected $btCacheBlockOutput        = true;  // cache HTML output
protected $btCacheBlockOutputLifetime = 3600; // TTL in seconds
// For editable content:
protected $btCacheBlockOutputOnPost = false;  // don't cache after POST

Development Timeline