How to Build a Custom Block Type in Concrete CMS 9

Custom blocks are one of the most useful extension points in Concrete CMS. They let editors add structured, reusable content without turning every page into a one-off template.

In this guide we will build a simple feature card block. The same pattern works for callouts, hero sections, product teasers, FAQs, and other content types that should stay consistent across a site.

Start with a clear package structure

Keep the block inside your package so it can be versioned, installed, and moved between environments predictably. A small block still benefits from a tidy directory layout.

/packages/site_tools/
  controller.php
  blocks/
    feature_card/
      controller.php
      add.php
      edit.php
      view.php
      db.xml
      templates/
        compact.php

Create the block controller

The controller defines the block name, description, database table, and validation rules. Keep business logic here light; the controller should prepare data for the view and protect editors from invalid input.

Build forms for editors, not developers

The add and edit forms should make the expected content obvious. Group related fields, use helpful labels, and avoid exposing implementation details that editors do not need to understand.

A good block form makes the correct content shape feel natural.

For repeatable data, consider Express entities or a custom dashboard page. For simple fields, a block table with db.xml is usually enough.

Add custom templates when presentation varies

Custom templates are ideal when the same data should appear in multiple visual treatments. In this example, the default view can show a full card while templates/compact.php renders a smaller row layout.

Keep markup semantic and move reusable styling into the theme stylesheet. That way the block stays portable and the site design remains consistent.

Final checklist before launch

• Validate required fields before saving.
• Escape output in views unless HTML is intentionally allowed.
• Test add, edit, duplicate, delete, and version rollback flows.
• Confirm the block works inside stacks and different page themes.
• Add a useful thumbnail or icon for easier dashboard scanning.