Built with Chinaski

Block Types

Every block in Chinaski — from a call-to-action strip to a pricing table — belongs to a type, the vocabulary that tells the system which fields it takes and how it renders. This page covers the type registry itself: the built-in types that ship, how to register your own, and the rules that keep the two in step.

The registry

Block types live in a managed table — the single source of truth for which types exist. What the registry decides:

  • Whether a block of that type can be created (creating a block requires its type to be registered — switching an existing block to an unregistered type is rejected).
  • What appears in the Blocks editor, the Library screens, and the authoring type dropdown(s) elsewhere in the admin.
  • Which block types a block-import file may reference.

At startup, the registry is kept in sync with the software’s shipped vocabulary: standard types are re-inserted, passing any edits you’ve made to their labels or descriptions. The shipped set — included alphabetically on the Block Types screen — is deliberately broad:

accordion, audio, button_group, callout, citations, code_block, columns, cta, divider, embed, faq, feature_grid, form, gallery, grid, heading, hero, image, logo_bar, newsletter, page_list, pricing_table, promo, quote, spacer, stat, table, team, testimonial, text, timeline, video

Creating a custom block type (the form)

On the Block Types screen (Administrators only), the Register Custom Block Type form takes three fields:

  • Name — lowercase letters, digits, hyphens, and underscores only; this becomes the identifier of the type (what lives in the type column and forms).
  • Label — the human-readable name used in lists (defaults to the uppercase short form; you can override it).
  • Description — optional free text.

Submitting registers the type instantly — there are no rendering files to add server-side. The system’s flash messages do the rest:

  • “Block type registered” if both required files already exist (see below).
  • The flash message tells you precisely which file paths are missing. The registered type stays in the registry — it simply won’t render or show its admin form until those two files exist.

What a custom type needs

Two files, placed by you:

  • builder/block_templates/<type>.tt — the builder template: this is what gets rendered into the site (see Blocks in Themes for the variable contract).

  • templates/admin/blocks/types/<type>.html.ep — the admin form: which fields the block’s editor exposes (which often means its flat fields, or a JSON-row editor for grid/gallery/columns-style repeating data).

  • Blocks aren’t moved by the registry. The type determines which fields appear in the admin form; the builder template decides rendering — and the block’s name, not its type, is what {{block:name​}} references.

  • Custom types don’t get scaffolding. The registration form tells you which two file paths to create, but never manufactures the templates for you.

Deleting a type

Two kinds of block types are on the screen, and the two categories behave differently:

  • Built-in types cannot be deleted. The startup process re-seeds the standard list every boot, and existing content of a built-in type can’t become editable-less.
  • Custom types can be deleted — but only empty. Any block still in the type blocks deletion with an error (“blocks of this type still exist”); you must trash or destroy every block of that type first (then, from the Blocks screen, only registered custom types can be deleted/removed from the registry).

The registry screen therefore stays clean: every entry on it is either an active type that admin forms reference, or a custom one ready to delete once emptied.

Adding a type without coding blocks from scratch

Creating a variant of an existing type — sharing the same fields but a different name and styling intent — is legitimate:

  1. Register the new name on the Block Types screen.
  2. Copy the builder block template (<name>.tt) and admin form partial (<type>.html.ep) of the type closest to what you need; these two copied files are the same contract.
  3. Adjust form fields and template HTML as needed.

The same care applies coming from outside the built-in set (see the Blocks page section on which fields accept HTML vs. auto-escaping).

The short version

Built-in types are the fixed vocabulary that block templates and admin forms are built to render; the registry decides which types exist; admins can register their own (copying two template files by hand), and a custom type can be deleted once emptied — while built-ins stay perpetual because the seed runs them at every startup.