# Gutenberg Blocks

WordPress 5 introduces a new content creation experience with its new editor called Gutenberg (opens new window).

Gutenberg is a block-based editor that provides a better and more natural way for creating new content on your website. With Carbon Fields v3 we got you covered and you can start creating stunning blocks for your website.

In order to create a new Gutenberg Block you can still use the already familiar developer-friendly way just like you'd register any other container.

<?php

use Carbon_Fields\Block;
use Carbon_Fields\Field;

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_render_callback( function ( $fields, $attributes, $inner_blocks ) {
		?>

		<div class="block">
			<div class="block__heading">
				<h1><?php echo esc_html( $fields['heading'] ); ?></h1>
			</div><!-- /.block__heading -->

			<div class="block__image">
				<?php echo wp_get_attachment_image( $fields['image'], 'full' ); ?>
			</div><!-- /.block__image -->

			<div class="block__content">
				<?php echo apply_filters( 'the_content', $fields['content'] ); ?>
			</div><!-- /.block__content -->
		</div><!-- /.block -->

		<?php
	} );

Notice the ->set_render_callback() method. This allows you to set the output that will be generated from this block both in Preview mode and on the frontend.

->set_render_callback() accepts a callback, which should output the HTML markup for the block. The callback function will be called with the following arguments:

$fields, an array with the entered data in the block.
$attributes, an array with the attributes of the block like custom CSS class, alignment, etc.
$inner_blocks, a string with the content of all nested blocks.

# Config Methods

# `set_description( $description )`

This method allows you to set a short text that describes the block. The description is shown in the Block inspector sidebar once you focus on the Block.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_description( __( 'A simple block consisting of a heading, an image and a text content.' ) )
	->set_render_callback( function () {
		// ..
	} );

# `set_category( $slug, $title = null, $icon = null )`

Gutenberg blocks can be grouped in different categories. By default, the following come registered out of the box:

common
formatting
layout
widgets
embed

If you don't specify a category, the block will be assigned to common.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_category( 'layout' )
	->set_render_callback( function () {
		// ..
	} );

However, if you need to, you can register a new category for your blocks.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_category( 'custom-category', __( 'Custom Category' ), 'smiley' )
	->set_render_callback( function () {
		// ..
	} );

The $icon argument accepts the slug of a WordPress Dashicon (opens new window)

# `set_icon( $icon )`

In addition to setting an icon to block categories, you can set an icon to the block itself.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_icon( 'heart' )
	->set_render_callback( function () {
		// ..
	} );

# `set_keywords( $keywords = [] )`

This method allows you to set the aliases that help users discover it while searching.

!> You are only allowed to add as much as 3 keywords per block.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_keywords( [ __( 'block' ), __( 'image' ), __( 'content' ) ] )
	->set_render_callback( function () {
		// ..
	} );

# `set_mode( $mode = 'edit' )`

This method sets the block mode to 'edit' or 'both'.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_mode( 'edit' )
	->set_render_callback( function () {
		// ..
	} );

!> The nested blocks aren't affected by this method. Only their parent can enter in a preview mode.

# `set_editor_style( $handle )`

You can set a custom stylesheet specific for your block, which will be loaded in the editor in the administration panel.

wp_register_style(
	'crb-my-shiny-gutenberg-block-stylesheet',
	get_stylesheet_directory_uri() . '/css/gutenberg/my-shiny-gutenberg-block.css'
);

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_editor_style( 'crb-my-shiny-gutenberg-block-stylesheet' )
	->set_render_callback( function () {
		// ..
	} );

# `set_style( $handle )`

This method is the same as the set_editor_style, however, it will load the stylesheet on the frontend as well.

wp_register_style(
	'crb-my-shiny-gutenberg-block-stylesheet',
	get_stylesheet_directory_uri() . '/css/gutenberg/my-shiny-gutenberg-block.css'
);

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		Field::make( 'text', 'heading', __( 'Block Heading' ) ),
		Field::make( 'image', 'image', __( 'Block Image' ) ),
		Field::make( 'rich_text', 'content', __( 'Block Content' ) ),
	) )
	->set_style( 'crb-my-shiny-gutenberg-block-stylesheet' )
	->set_render_callback( function () {
		// ..
	} );

# `set_inner_blocks( $inner_blocks = true )`

This method controls the ability of the block to contain nested blocks.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_render_callback( function () {
		// ..
	} );

# `set_inner_blocks_position( $position = 'above' )`

This method sets the position at which the inner blocks will render. The possible values are: above and below.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_inner_blocks_position( 'below' )
	->set_render_callback( function () {
		// ..
	} );

# `set_inner_blocks_template( $template = null )`

This method allows you to set a template of blocks which every new instance of your block will contain. The possible values are: array and null.

See Gutenberg > Templates (opens new window) for more details.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_inner_blocks_template( array(
		array( 'core/heading' ),
		array( 'core/paragraph' )
	) )
	->set_render_callback( function () {
		// ..
	} );

# `set_inner_blocks_template_lock( $lock = null )`

This method allows you to lock the area that contains the nested blocks. The possible values are:

all - prevents all operations. It is not possible to insert new blocks. Move existing blocks or delete them.
insert - prevents inserting or removing blocks, but allows moving existing ones.
false - prevents locking from being applied to the nested blocks area even if a parent block contains locking.
null - disables any locks applied to the area.

See Gutenberg > Templates (opens new window) and Gutenberg > Inner Blocks (opens new window) for more details.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_inner_blocks_template( array(
		array( 'core/heading' ),
		array( 'core/paragraph' )
	) )
	->set_inner_blocks_template_lock( 'insert' )
	->set_render_callback( function () {
		// ..
	} );

# `set_parent( $parent = null )`

This method allows you to restrict the block to be inserted to specific block types. The possible values are - string, array or null.

See Gutenberg > Block Registration (opens new window) for more details.

Block::make( __( 'Product' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_render_callback( function () {
		// ..
	} );

Block::make( __( 'Product Description' ) )
	->add_fields( array(
		// ...
	) )
	->set_parent( 'carbon-fields/product' )
	->set_render_callback( function () {
		// ..
	} );

# `set_allowed_inner_blocks( $blocks = null )`

This method allows you to restrict the type of blocks that can be inserted in the nested blocks area. The possible values are - array or null.

See Gutenberg > Inner Blocks (opens new window) for more details.

!> If an empty array is passed then only the blocks that have your block as parent can be inserted. See the set_parent method.

Block::make( __( 'My Shiny Gutenberg Block' ) )
	->add_fields( array(
		// ...
	) )
	->set_inner_blocks( true )
	->set_allowed_inner_blocks( array(
		'core/paragraph',
		'core/list'
	) )
	->set_render_callback( function () {
		// ..
	} );

← Comment Meta Nav Menu Item →

# Gutenberg Blocks

# Config Methods

# set_description( $description )

# set_category( $slug, $title = null, $icon = null )

# set_icon( $icon )

# set_keywords( $keywords = [] )

# set_mode( $mode = 'edit' )

# set_editor_style( $handle )

# set_style( $handle )

# set_inner_blocks( $inner_blocks = true )

# set_inner_blocks_position( $position = 'above' )

# set_inner_blocks_template( $template = null )

# set_inner_blocks_template_lock( $lock = null )

# set_parent( $parent = null )

# set_allowed_inner_blocks( $blocks = null )