Contents
Introduction
Advanced Custom Fields (ACF) has revolutionized WordPress development by providing an intuitive way to add custom data. With the release of ACF 5.8, developers gained the ability to create fully custom Gutenberg blocks, marrying ACF’s field-building power with the block editor’s flexibility. This article walks through every step of implementing custom ACF blocks: from environment setup to best practices for performance and internationalization.
Prerequisites
- WordPress ≥ 5.0 with Gutenberg enabled
- ACF Pro ≥ 5.8 (ACF Blocks documentation)
- Basic familiarity with PHP, JavaScript (ES6 ), and WP theme/plugin structure
- Node.js npm (for build tools, optional but recommended)
Why Choose ACF Blocks
Gutenberg’s block-based approach offers unprecedented editorial freedom. But coding custom React blocks from scratch can be time-consuming. ACF Blocks simplify:
- Rapid field configuration: Define ACF fields via GUI or PHP.
- Seamless PHP rendering: No need to write a React component unless required.
- Consistent UI: Leverage ACF’s field styling inside the editor.
1. Environment Setup
- Install and activate ACF Pro plugin.
- Create a theme or custom plugin folder (e.g.,
my-acf-blocks). - Ensure your
functions.php(or plugin main file) includes an autoloader or direct includes. - (Optional) Initialize
package.jsonand install build tools (npm install --save-dev @wordpress/scripts).
2. Registering a Custom Block
ACF Blocks leverage acf_register_block_type() or a block.json file. We’ll focus on block.json for modularity.
block.json Example
{
name: acf/hero-banner,
title: Hero Banner,
description: A full-width hero banner with image, title, and button.,
category: layout,
icon: cover-image,
mode: edit,
keywords: [banner,hero,cta],
supports: {
align: [full,wide],
anchor: true,
mode: true,
multiple: true,
jsx: true
},
acf: {
renderTemplate: template-parts/blocks/hero-banner.php
},
enqueueStyle: css/hero-banner.css,
enqueueScript: js/hero-banner.js
}3. block.json Field Reference
| Field | Description |
|---|---|
| name | Unique block namespace (must start with vendor/). |
| title | Human-readable label. |
| category | Block category (e.g., layout, widgets). |
| supports | Editor UI features toggles. |
| acf.renderTemplate | Path to PHP template. |
| enqueueStyle / enqueueScript | Front-end editor assets. |
4. Loading block.json
In your theme’s functions.php or plugin main file, add:
5. Creating the Render Template
Inside template-parts/blocks/hero-banner.php:
6. Enqueueing Assets
ACF automatically enqueues enqueueStyle and enqueueScript from block.json. For advanced setups, manually register:
7. Styling the Block
Keep CSS minimal and BEM-friendly:
.hero-banner {
position: relative
padding: 100px 0
background-size: cover
background-position: center
}
.hero-banner .hero-content {
max-width: 600px
margin: auto
text-align: center
color: #fff
}
.hero-banner .hero-button {
display: inline-block
padding: 10px 20px
background: rgba(0,0,0,0.5)
color: #fff
text-decoration: none
border-radius: 4px
}8. Dynamic vs Static Blocks
- Static (JS/JSX): All rendering in the editor good for highly interactive blocks.
- Dynamic (PHP): Render on server best for content-driven, SEO-friendly blocks.
9. Internationalization
Wrap strings in __() or esc_html__(), and load text domain:
// In plugin or theme bootstrap
add_action(init, function() {
load_theme_textdomain(my-theme, get_template_directory() . /languages)
})Use title in block.json as __(Hero Banner,my-theme) when registering via PHP.
10. Conditional Logic Advanced Fields
ACF fields support conditional logic. Define in the GUI or via PHP acf_add_local_field_group():
group_hero,
title => Hero Banner Fields,
fields => array(
array(
key => field_btn_text,
label => Button Text,
name => button_text,
type => text,
conditional_logic => array(
array(
array(field => field_has_button, operator => ==, value => 1),
),
),
)
),
location => array(
array(
array(param => block, operator => ==, value => acf/hero-banner),
),
),
)) 11. Performance Best Practices
- Minimize asset size: compile and minify CSS/JS (@wordpress/scripts).
- Lazy-load images or use
loading=lazy. - Cache dynamic markup if heavy database queries are involved.
- Namespace CSS classes to avoid collisions.
12. Debugging Troubleshooting
- Use
WP_DEBUGandacf/settings/show_adminto expose ACF errors. - Inspect block HTML classes (
wp-block-acf-) to target editor styles. - Check console for JS errors if using React/JSX mode.
13. Security Considerations
- Sanitize user inputs:
esc_html(),esc_url(),wp_kses_post(). - Validate URLs and email fields strictly.
- Escape attributes in HTML to prevent XSS.
Conclusion
Implementing custom ACF blocks provides a rapid, maintainable way to extend Gutenberg with PHP-centric workflows. By dividing configuration (block.json), templating (PHP), styling (CSS), and logic (conditional ACF fields), you maintain a clear separation of concerns, boost performance, and empower editors with bespoke content modules.
For further reading:
|
|
Acepto donaciones de BAT's mediante el navegador Brave 🙂 |