A visual editor for long-form text and modular pages
The Blocks field is the perfect solution for complex single-column layouts and long-form text.
You can add the Blocks field to any fields section in your Panel like this:
||-||Sets the focus on this field when the form loads. Only the first field with this property gets focus.|
||-||Default value for the field, which will be used when a page/file/user is created|
||-||If true, the field is no longer editable and will not be saved|
||-||Customize the default text when the blocks field is empty|
||-||Defines the allowed block types in the blocks field. See below.|
|help||-||Optional help text below the field|
|label||-||The field label can be set as string or associative array with translations|
||-||Maximum number of allowed blocks|
||-||Minimum number of required blocks|
||Saves pretty printed JSON in text files|
||If true, the field has to be filled in correctly to be saved.|
||If false, the field will be disabled in non-default languages and cannot be translated. This is only relevant in multi-language setups.|
|when||-||Conditions when the field will be shown (since 3.5.1)|
||The width of the field in the field grid. Available widths:
By default, the block selector shows a single list of available block types in alphabetical order.
However, you can fully customize the selector for new block types with sorted block types and groups.
To change the order of available blocks, list them manually with the
You can group block types in the block selector for a better overview of the available options. This is particularly useful when your blocks lists gets longer once your start creating your own custom blocks.
To create such groups, use the Blocks field's generic "group" block type:
By default, all groups are open. With very long list, you might want to close groups of blocks that are used less frequently with the
open: false option:
You can set default blocks/values for blocks fields which will prepopulate the field using the
default prop. The
type property is required, but default blocks can be empty or filled with example content.
Empty default block
Default block with content
Multiple block types
You can also set multiple default block entries:
Custom block types
You can create your own Block types for the Blocks field. Custom blocks are defined directly in the fieldsets list:
In the example above, we mix the default block types (heading and text) with our own custom block type to add a call to action button.
Custom block types don't have a visual preview by default. They show up with the icon and the name from your blueprint definition.
To edit a custom block type, editors can either double-tap on the block or click on the edit icon in the toolbar. The block drawer opens with the fields you've defined for the block.
You can also define tabs for your blocks when they have a lot of settings:
The tabs will then show up in the block drawer.
Global block types
For reuse in multiple places, custom block type definitions can be stored in a folder called
site/blueprints/blocks. In this case we would store it in
Now, we can use it in our fieldsets option for any blocks field.
This also works in groups:
Custom block type snippet
To render the HTML for your custom block type in the frontend, create a snippet in
/site/snippets/blocks. In this case we create a file called
You can turn your custom blocks into highly visual, interactive representations with a custom block preview plugin.
Read our plugin guide on how to create such previews.
Extending core blocks
You can take our core blocks as a starting point for your own custom blocks and extend them with your own fields, snippets and previews. Extending our core blocks works the same way as extending fields, tabs or sections in blueprints everywhere else.
Example: extending the heading block
Let's take the heading block and add a simple text field to add a custom ID for the heading
This will add the
customID field below the default fields of the block.
Extending existing fields
Instead of only adding new fields, you can also adjust the field settings for the default fields of the block.
Let's limit the number of heading levels for our heading block.
You can find all block fields and their settings in the docs for each block.
You can extend our core blocks with additional tabs. Be aware though that you need to recreate all default fields in this case, as tabs will replace the default fields.
Blocks in your templates
If you don't want to care about the HTML for each individual block, you can echo the entire blocks collection to render all blocks.
The HTML for each individual block is stored in its own block snippet. All our default block types bring their own snippets and can be overwritten. Block snippets are stored in
As an example, if you want to overwrite the snippet for our heading block, you would create a snippet file called
The default heading snippet
Your customized version
Looping through blocks
Looping through blocks to control their HTML can be very powerful. You can assign custom CSS classes, IDs for links and more.
You don't need to render the HTML for each individual block in the loop though. You can wrap the block with your custom HTML and then echo the
$block object to render the matching block snippet.
Manually loading snippets
Sometimes you might wish to customize the way block snippets are loaded. Maybe you want to inject more snippet variables.
… or load snippets from a different location …
You can configure the default setup of your Blocks field in your config.php
The Blocks field replaces the Builder field plugin. It comes with a built-in smart importer for Builder blocks. The migration should normally be effortless.
The only thing you have to change to upgrade from the Builder to the new Blocks field is to change the field type:
The Builder used a field method called
$page->blocks()->toBuilderBlocks(). This has to be replaced with
Your block snippets
Your old block snippets should work as expected, but a few things are deprecated and you should follow the new way of doing things in the snippets:
$block object replaces
$data You can still use
$data instead, but consider this deprecated. The following
$block object methods replace the old
The Blocks field also replaces our Editor field plugin. It has a built-in smart importer for Editor blocks. The migration should normally be mostly effortless. There are a couple block types that have changed though and you might need to update your editor block snippets.
The only thing you have to change to upgrade from the Editor to the new Blocks field is to change the field type:
The Editor used a field method called
$page->blocks()->blocks(). This has to be replaced with
The following block types have changed in the Blocks field and you need to move and rename your snippets if you have customized them in your installation.