Key Concepts

Documentation ACF Blocks Key Concepts

Last updated Jul 8, 2024

Overview

ACF Blocks allows you to build on top of the WordPress blocks system introduced in WordPress 5.0 “Bebo”, giving you access to many of the same features available to core blocks, but with the output rendered from a PHP template. ACF Blocks are highly flexible, allowing you to define attributes, block styles, and block variations. You can then compose your ACF Blocks into patterns, templates and template parts, save them as synced patterns, and extend them to incorporate WordPress styles.

A thorough understanding of the Block Editor Handbook will greatly expand what you can build with ACF Blocks, but you don’t have to read the whole thing to get started. Below we highlight some of the key points to remember when working with blocks.

Key Terminology

Here are some common terms we’ll use to help distinguish between WordPress core block APIs and ACF Blocks APIs when necessary:

• ACF Block(s): Represents the ACF product’s API extensions, which mostly leverage and are scaffolded on top of WordPress core block’s APIs.
• WordPress core block(s): Refers to WordPress’s native and core APIs for blocks, which most of ACF Blocks is built upon. WordPress core blocks are mostly written in React.
• Block(s) or block(s): When used without the prefix “ACF” or “WordPress core”, this refers to the general concept and lower-level APIs used by both WordPress core blocks and ACF Blocks, as well as the end output from the block.

Points to Remember

• Block data is saved within the post_content database table as serialized HTML. This makes them unique to meta boxes that save data to the postmeta table.
• Every block in WordPress requires a block.json file to register its properties. This is the entry point for every new block type.
• Native WordPress blocks can be static or dynamic. ACF Blocks are a custom type of dynamic block, rendered by ACF on the server and allowing for PHP logic.

Elements of ACF Blocks

There are three essential elements when it comes to ACF Blocks: a block.json file, a PHP file, and a CSS file. In fact, the CSS file is optional as your block may inherit styles from your theme, but you’ll need it to incorporate any unique styling. Most ACF Blocks also have an ACF field group associated with them, allowing the ACF Block to pull data from the fields. However, this is not actually essential to creating an ACF Block.

ACF Blocks and block.json

Both WordPress core blocks and ACF Blocks register their properties in a file called block.json to define their settings, styles, and metadata. The process is very similar to the one used for WordPress core blocks, but with the addition of the acf configuration key.

Block Variables (or Parameters for Callbacks) in PHP

You have access to data about your block by default when creating an ACF Block, either by variables made available in your template or passed into your callback as parameters. New parameters are defined in exactly the same way as any other PHP template file.

• $block (array) The block settings and attributes.
• $content (string) The block inner HTML (empty).
• $is_preview (boolean) True during backend preview render, i.e., when rendering inside the block editor’s content, or rendered inside the block editor when adding a new block, showing a preview when hovering over the new block. This variable is only set to true when is_admin() and current screen is_block_editor() both return true.
• $post_id (integer) The Post ID of the current context. This will be the page/post a block is saved against, or if the block is used in a template, synced pattern or query loop block, it will be the post_id of the currently displayed item.
• $context (array) The context provided to the block by the post or its parent block.

For render callbacks, the parameters are provided in the following order:

callback_function( $block, $content, $is_preview, $post_id, $wp_block, $context );

---

Next: Create Your First ACF Block

---