Custom Gutenberg Blocks with ACF
Josh Lee
- Developer since ~2006
- WordPress developer since ~2010
- Co-organizer for the Burlington WordPress Meetup
- Co-founder at Zana Digital
Find Me
What is Gutenberg?
What is Gutenberg?
- The new editor experience for WordPress, released in late 2018.
- Also called “The Block Editor”
- Replaces TinyMCE with a drag-and-drop “block” system
- Includes over 40 built-in block types (e.g. Paragraph, Heading, Media)
What is a Gutenberg Block?
- Each block type has a specific admin (“editor”) experience powered by Javascript.
- Block content is “rendered” into post content as a combination of structured data and plain HTML.
- Block types can be re-used by admins throughout the site*.
Don't Reinvent the Wheel
Block Libraries
- Many recent themes and plugins include their own libraries of block types.
- My favorite is Atomic Blocks
- Try not to go too crazy here...
DIY: Creating your own Block Types
DIY: Custom Block Types
- Under the hood, the Gutenberg editor experience uses React.js
- WordPress provides new Javascript APIs for registering block types and integrating them with the editor
DIY: Custom Block Types
Learn more about this at a future talk...
Stepping back: Why Custom?
- Integration with existing brand site or style guide
- Dynamic blocks based on custom post types
Advanced
Custom
Fields
What is Advanced Custom Fields?
A drag-and-drop editor to create “Field Groups” — sets of form fields that appear within specific areas of the WordPress Admin
Field Group Editor
Author Experience
Using your fields
- Custom field data is stored as post meta
- Use `the_field()` and `get_field()` functions in template files
Template w/ Custom Fields
<?php
// e.g. /wp-content/themes/my-custom-theme/single.php
if ( have_posts() ) :
while ( have_posts() ) : the_post();
the_title();
the_content();
the_field( 'my-custom-field-slug' );
endwhile;
endif;
?>What about Gutenberg?
Register a Custom ACF Block Type
<?php
//e.g. wp-content/themes/my-theme/functions.php
acf_register_block_type(array(
'name' => 'my-block',
'title' => __('My Block'),
'description' => __('A custom block type.'),
'render_template' => 'hello.php',
));<?php
//e.g. wp-content/themes/my-theme/hello.php
echo '<h1>Hello</h1>';Create a Field Group
Use your fields
<?php
//e.g. wp-content/themes/my-theme/hello.php
echo '<h1>Hello ' . get_field( 'person' ) . '</h1>';Block Type Options
Block Type Options
- `supports` - enable built-in editor features such as alignment options.
- `category` - sort blocks into existing categories, or create your own
- `enqueue_script` / `enqueue_style` / `enqueue_assets`
- More...
Block Type Options
<?php
acf_register_block_type(array(
'name' => 'custom-block',
'title' => __('Custom Block'),
'description' => __('A custom block.'),
'category' => 'layout',
'icon' => 'slides',
'keywords' => array( 'slide' ),
'align' => 'full',
'supports' => array(
'align' => array( 'center', 'wide', 'full' ),
)
));Tips & Tricks
Using a Render Callback
- Define your own function used to render custom blocks.
- Useful for any functionality shared between blocks, especially "wrapper" or "container" markup.
Using a Render Callback
<?php
acf_register_block_type(array(
'name' => 'custom-block',
'title' => __('Custom Block'),
'description' => __('A custom block.'),
'render_callback' => 'my_render_function',
));
function my_render_function($block, $content = '', $is_preview = false) {
$block_name = explode('/', $block['name'])[1];
echo '<div class="wp-block wp-block-' . $block_name . '">';
include( __DIR__ . 'template-parts/blocks/' . $block_name . '.php' );
echo '</div>';
}Enqueue Editor Assets
- Got custom styles or Javascript only needed for the editor?
- Use the `enqueue_block_editor_assets` hook.
function my_enqueue_editor_assets() {
wp_enqueue_style( 'editor-styles', get_stylesheet_directory_uri() . '/editor.css' );
}
add_action( 'enqueue_block_editor_assets', 'my_enqueue_editor_assets' );
Fetch Blocks for a Page
- Useful if you need to modify a page template based on the content of the page or specific blocks.
<?php
global $post
$blocks = parse_blocks( $post->post_content );
$table_of_contents = array();
foreach($blocks as $block) {
$table_of_contents[] = $block['blockName'];
}