The ACF Dynamic Tags feature in the Greyd.Suite plugin allows you to use Advanced Custom Fields (ACF) within the editor and customize their output using specific filters. This document explains how the feature works and provides examples for customization.
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:
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:
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:
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:
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!