Customize the output of ACF Dynamic Tags

The ACF Dynamic Tags feature in the Greyd Plugin allows you to use Advanced Custom Fields (ACF) within the editor and customize their output using specific filters. This document provides examples for customization. There’s a separate article for the ACF Integration that explains how they’re integrated in the Greyd Plugin, as well as a full list of all available hooks that we provide.

Key Filters

greyd_acf_dynamic_tag

This filter allows you to customize the HTML output of an ACF dynamic tag. The tag is identified by its name (usually the ACF field name).

Parameters:

  • $html (string) – The HTML content of the tag.
  • $tagName (string) – The identifier of the dynamic tag, typically the ACF field name.
  • $post (WP_Post) – The post object.

Example:

PHP
add_filter( 'greyd_acf_dynamic_tag', function( $html, $tagName, $post ) {
    if ( $tagName === 'my_custom_field' ) {
        return '<div>' . esc_html( get_field( $tagName, $post->ID ) ) . '</div>';
    }
    return $html; // Always return the original HTML if no changes are made.
}, 10, 3 );

greyd_acf_dynamic_tag_rendered

This filter allows you to modify the rendered HTML after the initial processing.

Parameters:

  • $html (string) – The final HTML content of the tag.
  • $tagName (string) – The identifier of the dynamic tag.
  • $post (WP_Post) – The post object.

Example:

PHP
add_filter( 'greyd_acf_dynamic_tag_rendered', function( $html, $tagName, $post ) {
    if ( $tagName === 'my_custom_field' ) {
        return '<span class="custom-class">' . $html . '</span>';
    }
    return $html;
}, 10, 3 );

greyd_acf_dynamic_url

This filter customizes the URL generated by ACF dynamic tags.

Parameters:

  • $url (string) – The URL of the dynamic tag.
  • $tagName (string) – The identifier of the dynamic tag.
  • $post (WP_Post) – The post object.

Example:

PHP
add_filter( 'greyd_acf_dynamic_url', function( $url, $tagName, $post ) {
    if ( $tagName === 'external_link' ) {
        return esc_url( get_field( $tagName, $post->ID ) );
    }
    return $url;
}, 10, 3 );

Default Fallback Behavior

If no custom filter is applied, the plugin renders ACF fields using a fallback mechanism:

  • Grouped fields: Supports rendering subfields within field groups.
  • Single fields: Supports field types like url, image, file, true, false, and others with default rendering logic.

The fallback behavior can also be customized using the following filter:

greyd_acf_dynamic_tag_fallback

Modify the fallback HTML content for unsupported tags.

Example:

PHP
add_filter( 'greyd_acf_dynamic_tag_fallback', function( $html, $tagName, $post ) {
    if ( $tagName === 'unsupported_field' ) {
        return '<p>Custom fallback for ' . esc_html( $tagName ) . '</p>';
    }
    return $html;
}, 10, 3 );

Rendering Logic

The plugin handles the rendering of various ACF field types, including:

  • URLs and links: Converts to anchor tags.
  • Images: Renders img elements.
  • Files: Generates download links.
  • Taxonomies and relationships: Converts to linked terms or posts.

For custom ACF types or unique formatting, you can hook into the provided filters to extend the rendering logic.

Debugging

If a field cannot be rendered, logged-in users with editing permissions see an admin notice prompting them to use the appropriate filter.

Example Admin Notice: “The ACF field my_field could not be rendered. Use the filter greyd_acf_dynamic_tag to render the field.”

Notes

  • Ensure that the ACF plugin is active and the get_field function is available before using these filters.
  • Always sanitize and escape output to maintain security.

With these tools and examples, you can fully customize how ACF fields appear in your dynamic content!

Last updated: