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, schedule, 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, 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.