Advanced Custom Fields

Barebones uses Advanced Custom Fields to support structured content and custom block fields. The theme does not install ACF. It provides a small amount of setup for working with ACF safely across environments.

ACF setup file

ACF-related theme setup lives in includes/acf.php.

The file is loaded from functions.php.

PHP
require_once get_template_directory() . '/includes/acf.php';

Admin visibility

Barebones hides the ACF admin interface outside development environments. This ensures that custom field groups are loaded from the .json files within /acf-json/ across staging and production environments to avoid conflicts with fields synced to the database. Database syncing is necessary on a local environment in order to make changes to field configuration through the ACF UI.

PHP
function acf_theme_setup() {
    if ( wp_get_environment_type() !== 'development' ) {
        add_filter( 'acf/settings/show_admin', '__return_false' );
    }
}

add_action( 'after_setup_theme', 'acf_theme_setup' );

Development environment

To edit field groups, WordPress should be running in development mode.

PHP
define( 'WP_ENVIRONMENT_TYPE', 'development' );

Local JSON

ACF field groups are stored in acf-json/.

This keeps field definitions version controlled with the theme.

The current theme includes a field group for the Split Content block in acf-json/group_6870f0d1f0412.json.

Block field groups

ACF field groups can be assigned to custom blocks.

The Split Content field group is assigned to custom-blocks/split-content.

This means the fields only appear when editing that block.

JSON
"location": [
    [
        {
            "param": "block",
            "operator": "==",
            "value": "custom-blocks/split-content"
        }
    ]
]

Using fields

Block render templates use normal ACF functions. The Split Content block uses fields for WYSIWYG content, an image, and content alignment.

PHP
$content   = get_field( 'content' );
$image     = get_field( 'image' );
$alignment = get_field( 'content_alignment' );

Image fields

Image fields should usually return an attachment ID.

This allows templates to use WordPress image helpers.

Use a named image size instead of full when the design has a known image requirement.

PHP
$image = get_field( 'image' );

if ( $image ) {
    echo wp_get_attachment_image( $image, 'full' );
}

Rich text fields

WYSIWYG fields should be rendered with an appropriate HTML allow-list.

Use esc_html() for plain text fields, not rich text fields that are intended to include markup.

PHP
$content = get_field( 'content' );

if ( $content ) {
    echo wp_kses_post( $content );
}