ACF Blocks: Usage Guide

With ACF Blocks, the powerful feature of the Advanced Custom Fields plugin, you can extend the functionality of your website by adding unique content blocks tailored to your specific needs.

It's important to mention, that the blocks feature is a part of the ACF Pro version, so available only for users of ACF Pro.

The block's approach in WordPress offers several important advantages over traditional methods like meta fields and page builders. Let's explore the main benefits of using blocks:

• Reusable and Flexible
  One of the standout advantages is its reusability. Blocks can be easily used across pages or even on the same page. This flexibility allows you to create consistent content elements that maintain the same design and functionality throughout your website. It saves time and ensures a smooth user experience for your visitors.
• Improved Performance
  Blocks provide a more efficient way to manage assets and resources. Unlike traditional approaches, where all resources are loaded globally, block assets are only loaded where the block is used. This optimized loading mechanism leads to faster page load times and reduces unnecessary resource overload. As a result, your website becomes more responsive, especially for mobile users, and performs better in search engine rankings.
• Missing style conflicts
  In the past, style conflicts were a common problem when working with custom meta fields and theme templates. The block's modular nature significantly reduces the chances of style conflicts. Each block has its own separate set of styles and scripts, minimizing the possibility of clashes with other elements on the page. This isolation ensures a more stable and predictable layout and enhances the overall development experience.

So, the block's approach in WordPress presents a modern and powerful way to design and manage content. With its reusability, improved performance, and elimination of conflicts, blocks have become the preferred method for many WordPress users and developers.

Before we dive into ACF Blocks, let's also briefly touch upon the native Gutenberg blocks.

Gutenberg is the default WordPress block editor that provides a basic set of blocks like paragraphs, headings, images, and more. While these built-in blocks are useful, they have some limitations when it comes to customizing the layout and adding advanced functionality.

Drawbacks of the Native Blocks:

• Limited customization options
• Inability to create complex block layouts
• No intuitive way to include custom fields for more advanced content

It's essential to note that it is possible to create custom Gutenberg blocks without extra plugins. However, this process demands a good understanding of React, the JavaScript library that powers Gutenberg. It also requires a considerable investment of time and effort to develop custom blocks.

Challenges of Creating Custom Gutenberg Blocks:

• React Knowledge Required
  Developing custom Gutenberg blocks involves working with React components, which demands a certain level of expertise in JavaScript and React development.
• Time-Consuming
  Crafting custom blocks from scratch can be time-consuming, especially for those who are new to React or WordPress development.
• Complexity
  Custom block development often involves managing states, and handling dynamic content.
• Maintenance
  As the WordPress core evolves, custom blocks may require updates and adjustments to remain compatible, adding to the maintenance burden.

In contrast, ACF Blocks offer a more approachable and user-friendly way to create custom blocks without the need to delve into complex React development. ACF provides an intuitive interface for adding fields and defining layouts, enabling users of all skill levels to build advanced blocks quickly and efficiently.

The ACF blocks feature allows us to create blocks, and attach any groups of fields to them. Then ACF takes care of everything, renders the fields in the admin UI, and saves them. So we can have multiple fields of different types in our block, including complex fields, like gallery and repeater, without extensive coding.

But for developers, it's important to know, not only how to create the ACF blocks, but also how the feature works behind the scenes. Let's take a peek behind the curtain to understand the magic that powers these versatile blocks and how they seamlessly integrate with the native Gutenberg editor.

The great news is that inside, ACF blocks work and act just like other native Gutenberg blocks, e.g. paragraphs. If you have ever seen the Gutenberg blocks code, you'll notice that they're rendered into plain HTML, and saved into the post_content field. For example, the core paragraph field looks like this:

<!-- wp:paragraph -->
<p>Your text</p>
<!-- /wp:paragraph -->

And the heading block looks like this:

<!-- wp:heading -->
<h2 class="wp-block-heading">Your heading</h2>
<!-- /wp:heading -->

As you see, those are plain HTML and are extended by WP comments. Which allows developers to parse blocks later.

So, ACF follows this approach and creates similar blocks. The main difference is that fields are saved as JSON in the HTML comment, and the block doesn't contain the HTML code itself.

<!-- wp:acf/org-wplake-website-blocks-codesnippet-theme-classic-codesnippetthemeclassic 
{"name":"acf/org-wplake-website-blocks-codesnippet-theme-classic-codesnippetthemeclassic",
"data":{"local_code-snippet__code-snippet":"\u003c?php\r\necho 'hello world';",
"local_code-snippet__language":"php"},"mode":"edit"} /-->

It's important to understand this principle, but you shouldn't worry about the implementation. ACF takes care of it all by itself.

Tip: Storing block fields as json in the post_content is much better for performance, compared to the meta fields approach. Which means pages built using ACF blocks will sometimes load faster than the page, which uses plain templates and meta fields.

In the Behind the Scenes chapter we've shown how the ACF blocks feature works. But what about styles and scripts? Should you add them globally, as you'd normally do? You can, but fortunately, there is a better solution.

ACF Block handles styles and scripts in a modular and efficient manner. Each block has its own CSS and JavaScript, loaded only when that specific block appears on a page. This approach enhances performance by avoiding unnecessary resource loading, leading to faster page load times and a smoother user experience.

Tip: If you're familiar with the BEM methodology, you may have the idea, that ACF Blocks is a great place to use the method and you'd be one hundred percent correct. Using the BEM method with ACF Blocks will organize your CSS and markup, ensuring better code re-usability and maintainability.

ACF simplifies our lives by handling the rendering and saving of fields. However, this feature still entails fetching fields and creating markup, which can be time-consuming. That's why we share two methods below for adding ACF blocks to your Gutenberg library: using an addon or doing it manually.

Whatever you've chosen, initially, we must create a field group for the block. Let's do it right now. In our example, we'll create a 'Banner' block, so we'll give the same name to the group.

ACF is famous for its add-ons.

Let us introduce the ACF Views addon.

ACF Views provides smart templates for effortless content display. It comes with built-in post queries and automated template generation, enabling rapid development while maintaining flexibility.

Let's first clarify what we mean by 'templates' in the context of this plugin: ACF Views templates are built on the Twig engine. You might be thinking, 'Not bad, but it still requires fetching fields via PHP and writing markup from scratch, not to mention reading Twig documentation'.

Here's where the plugin shines: "Smart templates". This means we don't have to fetch fields or create markup manually from scratch. The plugin provides a solid foundation that covers most use cases. If we require something specific, we can easily customize it. Isn't that nice?

Now, let's take a basic look at how it works.

The plugin introduces two new Custom Post Types (CPTs): ACF View and ACF Card.

• View for post data and Advanced Custom Fields
  We create a View and assign one or more post fields, the plugin then generates a shortcode that we'll use to display the field values to users. We can style the output with the CSS field included in every View.
• Card for post selections
  We create a Card and assign posts (or CPT items), choose a View (that will be used to display each item) and the plugin generates a shortcode that we'll use to display the set of posts. The list of posts can be assigned manually or dynamically with filters.

The plugin offers us the convenience of working with familiar WordPress CPTs while taking care of querying and automatically generating Twig markup templates. You can find more information about the plugin's benefits here.

Now, let's delve into the topic of blocks. In addition to the features mentioned above, the ACF Views plugin offers a Pro version. With the Pro version, we can create and utilize a Gutenberg block (with a straightforward checkbox toggle) instead of using shortcodes. This is precisely what we've been searching for.

To get started, you'll need to acquire and install the Pro version of the plugin. If you'd like to explore the plugin's functionality beforehand, you can install the Basic version before making a purchase. This will allow you to experiment with the plugin, understand its workings, and ensure that it aligns with your requirements.

So, now we're ready to create our first block. Below we've attached a video tutorial, that will guide you. Don't forget to enter the full-screen mode to see everything in detail.

In summary, you need to repeat the following steps:

1. Create an ACF group, and add target fields
2. Create a View, select the target fields from the first step, and publish the View.
3. In the View settings, switch on the ‘With Gutenberg Block’ checkbox.
4. Click ‘Update’ to save your View.
5. Edit your Post, Page or CPT item using the Gutenberg editor.
   Note: It’s important to use the Gutenberg editor and not the Classic editor or page builder element, as the block generated is only available in the Gutenberg blocks library.
6. Insert a new block, selecting your View’s block from the list. It’ll have your View name for the block name.
7. Fill the fields in the block you’ve just inserted.
8. Click on ‘Publish’ to save your post, page or CPT item.
9. Visit the page to see the result.

ACF Views automatically generates the markup, so you don't need to worry about field types and their return formats. Now, you can style the output by adding some CSS rules. You can easily add them, using the 'Advanced' tab of your View.

This approach gives your more flexibility compared to the plugin but requires more effort.

Note: below is the actual guide for ACF v6+. We'll show the new and recommended way to add blocks (using JSON). The old way, with a php function was deprecated with the release of v6.

You need to create a JSON declaration for every block. The declaration is a plain .json file that contains the necessary info about the block. You can place this file wherever you want, inside your theme or plugin.

{
    "name": "acf/banner",
    "title": "Banner",
    "description": "A custom banner block.",
    "style": [ "file:./banner.css" ],
    "category": "formatting",
    "icon": "admin-comments",
    "keywords": ["banner"],
    "acf": {
        "mode": "preview",
        "renderTemplate": "banner.php"
    }
}

Now we need to let WordPress know about the block, using the following snippet:

<?php
add_action( 'init',function (){
    // fixme your path here to the folder with the JSON file
    register_block_type( __DIR__ . '/blocks/testimonial' );
} );

In this step, the block is already registered, and we need to attach our ACF Group to the block. Open the group that we created initially, and choose the Block option in the location rules select. Then, choose your Block in the select drop down and update the group.

Tip: If you don't see your Block's name in the select, make sure you've added the PHP code from Step 2, and uploaded the file.

Now everything is ready to create the block's template. The PHP template will return the HTML markup of the block, based on the field values. You need to check your field names, types, and return formats in the ACF Group, to create the proper code.

Below is the template code for our Banner block. You need to add it to the PHP file, that you've declared in the renderTemplate section in the JSON declaration in the first step.

<?php
/**
 * Banner Block Template.
 *
 * @param array $block The block settings and attributes.
 * @param string $content The block inner HTML (empty).
 * @param bool $is_preview True during backend preview render.
 * @param int $post_id The post ID the block is rendering content against.
 *          This is either the post ID currently being displayed inside a query loop,
 *          or the post ID of the post hosting this block.
 * @param array $context The context provided to the block by the post or it's parent block.
 */


$title = get_field('title') ?: '';
$description = get_field('description') ?: '';
$image = get_field('image') ?: 0;
$linkData = get_field('link');
$link = '';

$image = $image ?
    wp_get_attachment_image($image, 'full', false, [
        'class' => 'banner__image',
    ]) :
    '';

if ($linkData) {
    // if the 'target' is presented, it's a bool. We've to convert it into the HTML format
    $target = isset($linkData['target']) && $linkData['target'] ?
        '_blank' :
        '_self';
    // Each %s in the string will be replaced with the related argument
    $link = sprintf(
        "<a class='banner__link' href='%s' target='%s'>%s</a>",
        esc_url($linkData['url']),
        esc_html($target),
        esc_attr($linkData['title'])
    );
}

?>
<div class="banner">
    <p class="banner__title"><?php
        echo esc_html($title); ?></p>

    <?php
    echo $image; ?>

    <div class="banner__description"><?php
        echo esc_html($description); ?></div>
    
    <?php
    echo $link ?>
</div>

This was the last step, now you can open the Gutenberg editor, find the new block in your library and add it in the target place. Then fill in the fields, and press the 'Update' button to save the page.

Visit the page to see to result.

To get additional information, watch the video below and read the official ACF article.

ACF Blocks, part of the Advanced Custom Fields plugin, empower you to extend your WordPress website's functionality by creating custom content blocks tailored to your needs. They offer flexibility and user-friendliness, eliminating the complexity of React development.

Understanding how ACF Blocks work behind the scenes is crucial for developers, as they store data within the post_content, resulting in faster page loading times. You can leverage the ACF Views plugin to create ACF Blocks effortlessly or use the manual approach.

Whether you're a professional developer or a WordPress enthusiast, ACF Blocks elevate your content creation and deliver an engaging website experience. Unlock the full potential of your WordPress site with ACF Blocks today!