Hooks for changing what a dynamic tag outputs, which blocks and HTML can use tags, and how tags are previewed in the editor. To register your own tag, see Registering dynamic tags. For who can use dynamic tags and how meta is read, see Dynamic tags: meta access and security.
Jump to
- Changing a tag’s value
- Allowed blocks and HTML
- The editor preview
- Advanced Custom Fields
- Editor (JavaScript)
Changing a tag’s value
Tags are resolved in this order: the tag finds its ID (generateblocks_dynamic_tag_id), the tag’s own callback returns a value and runs its string options such as truncate and case (generateblocks_dynamic_tag_output), then the result is filtered once more as a replacement (generateblocks_dynamic_tag_replacement), and finally substituted into the content (generateblocks_before_dynamic_tag_replace).
generateblocks_dynamic_tag_id
GB Free
The generateblocks_dynamic_tag_id filter changes the ID a tag uses to look up its post, user or term.
Parameters: $id (int, the current ID), $options (array, the tag options), $instance (object, the block instance that holds the tag; an empty stdClass when there isn’t one). Default: the tag’s id option if it has one. Otherwise the current user’s ID for user tags, the queried object’s ID for term tags, or get_the_ID() for everything else.
add_filter( 'generateblocks_dynamic_tag_id', function( $id, $options, $instance ) {
// Use the parent post when the tag doesn't set its own id.
if ( ! isset( $options['id'] ) ) {
$parent_id = wp_get_post_parent_id( $id );
return $parent_id ? $parent_id : $id;
}
return $id;
}, 10, 3 );Related: generateblocks_dynamic_tag_replacement Guide: Dynamic Tags
generateblocks_dynamic_tag_replacement
GB Free — since GenerateBlocks 2.0.
The generateblocks_dynamic_tag_replacement filter changes the value a single tag is replaced with. It runs once for each tag found in the content, before the check that drops a required tag with no value.
Parameters: $replacement (string, the value the tag resolved to), $data (array with the keys tag, full_tag, content, block, instance, options and supports). Default: the value returned by the tag’s own callback.
add_filter( 'generateblocks_dynamic_tag_replacement', function( $replacement, $data ) {
if ( 'post_title' === $data['tag'] ) {
return strtoupper( $replacement );
}
return $replacement;
}, 10, 2 );Related: generateblocks_dynamic_tag_output, generateblocks_before_dynamic_tag_replace Guide: Dynamic Tags
generateblocks_before_dynamic_tag_replace
GB Free — since GenerateBlocks 2.0.
The generateblocks_before_dynamic_tag_replace filter changes the content string once for each tag found, before the resolved values are substituted into it.
Parameters: $content (string, the content being processed), $data (array with the keys full_tag, tag, replacement, og_replacement, block, instance, options and supports). og_replacement is the value before generateblocks_dynamic_tag_replacement ran. Default: $content unchanged.
add_filter( 'generateblocks_before_dynamic_tag_replace', function( $content, $data ) {
// Remove the tag from the content when it resolved to nothing.
if ( '' === (string) $data['replacement'] ) {
return str_replace( $data['full_tag'], '', $content );
}
return $content;
}, 10, 2 );Related: generateblocks_dynamic_tag_replacement Guide: Dynamic Tags
generateblocks_dynamic_tag_output
GB Free
The generateblocks_dynamic_tag_output filter changes the output of a dynamic tag after its built-in string options (truncate, replace, trim, case, auto paragraphs and link) have run.
Parameters: $output (string, the returned output), $options (array, the tag options; the tag’s name is in $options['tag_name']), $raw_output (string, the output before the string options ran). Default: the tag’s output after the built-in options.
Example 1: a basic filter.
add_filter( 'generateblocks_dynamic_tag_output', function( $output, $options ) {
// Do something to output here.
return $output;
}, 10, 2 );Example 2: filtering a specific tag, for example {{post_title}}. The tag_name is saved in $options['tag_name'].
add_filter( 'generateblocks_dynamic_tag_output', function( $output, $options ) {
$tag_name = $options['tag_name'] ?? '';
if ( 'post_title' === $tag_name ) {
// do something to the `{{post_title}}` tag name.
}
return $output;
}, 10, 2 );Example 3: filtering with a custom tag. You can define your own option for a tag, for example {{the_tag my_custom_option:true}}, then filter the $output where that option is set.
add_filter( 'generateblocks_dynamic_tag_output', function( $output, $options ) {
if ( ! isset( $options['my_custom_option'] ) ) {
return $output;
}
// This is my_custom_option do something to the output.
return $output;
}, 10, 2 );Related: generateblocks_dynamic_tag_replacement, Registering dynamic tags Guide: Dynamic Tags
generateblocks_dynamic_excerpt_more_link
GB Free
The generateblocks_dynamic_excerpt_more_link filter changes the “read more” markup that the Post excerpt tag adds to the end of an excerpt. It only runs when the tag has a read more text and isn’t set to use the theme’s read more.
Parameters: $html (string, the read more markup). Default: the text from the tag’s pre option, followed by a link with the class gb-dynamic-read-more that goes to the post, has an aria-label of “More on {post title}”, and uses the tag’s readMore option as its text.
add_filter( 'generateblocks_dynamic_excerpt_more_link', function( $html ) {
return str_replace( 'gb-dynamic-read-more', 'gb-dynamic-read-more my-read-more', $html );
} );Related: generateblocks_dynamic_tag_output Guide: Dynamic Tags
Allowed blocks and HTML
generateblocks_dynamic_tags_allowed_blocks
GB Free — GenerateBlocks Pro adds its own blocks to the list.
The generateblocks_dynamic_tags_allowed_blocks filter lets dynamic tags work in other blocks.
Parameters: $blocks (array of block names). Default: generateblocks/element, generateblocks/loop-item, generateblocks/looper, generateblocks/media, generateblocks/query, generateblocks/query-page-numbers, generateblocks/shape and generateblocks/text. With GenerateBlocks Pro, the accordion (accordion, accordion-content, accordion-item, accordion-toggle, accordion-toggle-icon) and tabs (tabs, tabs-menu, tab-menu-item, tab-items, tab-item) blocks are added, each with the generateblocks-pro/ prefix.
add_filter( 'generateblocks_dynamic_tags_allowed_blocks', function( $blocks ) {
$blocks[] = 'yourprefix/block-name';
return $blocks;
} );Related: generateblocks_dynamic_tags_allowed_html Guide: Dynamic Tags
generateblocks_dynamic_tags_allowed_html
GB Free
The generateblocks_dynamic_tags_allowed_html filter changes the HTML tags and attributes that dynamic tag output may contain. It runs inside WordPress’s wp_kses_allowed_html filter, and only while GenerateBlocks is processing dynamic tag content.
Parameters: $tags (array, allowed tags and attributes in wp_kses format), $context (string, the wp_kses context, such as post). Default: the WordPress allowed tags for the context, plus an iframe that allows the src, height, width, frameborder, allowfullscreen and title attributes.
add_filter( 'generateblocks_dynamic_tags_allowed_html', function( $tags, $context ) {
$tags['video'] = [
'src' => true,
'controls' => true,
'poster' => true,
'width' => true,
'height' => true,
];
return $tags;
}, 10, 2 );Related: generateblocks_dynamic_tags_allowed_blocks Guide: Dynamic Tags
The editor preview
The block editor previews tags by asking the server to resolve them. These hooks control that preview.
generateblocks_dynamic_tags_preview
GB Free — since GenerateBlocks 2.3.
The generateblocks_dynamic_tags_preview filter turns the dynamic tag preview in the editor on or off.
Parameters: $enabled (bool). Default: true. The preview is also off for users who can’t author dynamic data, whatever this filter returns.
add_filter( 'generateblocks_dynamic_tags_preview', '__return_false' )Related: generateblocks_dynamic_tags_replacement_cache_duration, generateblocks_user_can_author_dynamic_data Guide: Dynamic Tags
generateblocks_dynamic_tags_replacement_cache_duration
GB Free — since GenerateBlocks 2.0.
The generateblocks_dynamic_tags_replacement_cache_duration filter sets how long the editor’s resolved tag previews are cached. Only users who can author dynamic data use the cache.
Parameters: $cache_duration (int, seconds), $content (string, the editor content), $context (the request context), $request (the WP_REST_Request). Default: 3600 (one hour). The cache lives in the generateblocks_dynamic_tags object cache group, so it only lasts beyond a request when your site has a persistent object cache.
add_filter( 'generateblocks_dynamic_tags_replacement_cache_duration', function( $cache_duration ) {
return 300;
} );Related: generateblocks_dynamic_tags_preview Guide: Dynamic Tags
generateblocks_dynamic_tags_post_record_response
GB Free — since GenerateBlocks 2.0.
The generateblocks_dynamic_tags_post_record_response filter adds to or changes the post record the editor receives when it previews a post tag.
Parameters: $response (the post object; meta, comments and terms are added when the editor asks for them), $id (int, the post ID), $load (string[], the extra data requested, such as post, comments and terms), $options (array, extra lookup options such as taxonomy). Default: the post object with the requested data added. After this filter runs, GenerateBlocks always removes post_password, guid and post_content_filtered, and for password-protected posts it removes the content, excerpt and meta unless the user can see them.
add_filter( 'generateblocks_dynamic_tags_post_record_response', function( $response, $id, $load, $options ) {
$response->my_custom_value = get_post_meta( $id, 'my_custom_key', true );
return $response;
}, 10, 4 );Related: generateblocks_dynamic_tags_user_record_response Guide: Dynamic Tags
generateblocks_dynamic_tags_user_record_response
GB Free — since GenerateBlocks 2.0.
The generateblocks_dynamic_tags_user_record_response filter adds to or changes the user record the editor receives when it previews a user tag. The filtered response is returned as it is, so don’t add data that editors shouldn’t see.
Parameters: $response (the user data object, with meta added), $id (int, the user ID). Default: the user data object. Non-admins don’t receive user_login or user_email.
add_filter( 'generateblocks_dynamic_tags_user_record_response', function( $response, $id ) {
$response->my_custom_value = get_user_meta( $id, 'my_custom_key', true );
return $response;
}, 10, 2 );Related: generateblocks_dynamic_tags_post_record_response Guide: Dynamic Tags
Advanced Custom Fields
generateblocks_pro_dynamic_tags_is_acf_field
GB Pro
The generateblocks_pro_dynamic_tags_is_acf_field filter decides whether a meta key is read as an Advanced Custom Fields field.
Parameters: $is_acf_field (bool), $acf_id (string|int, the ACF ID for the post, option for options), $acf_keys (array, the ACF keys for that ID), $args (array, positional: the current meta value, the object ID, the meta key and the meta type). Default: true when the first part of the key matches an ACF field for that ID, or an ACF option field.
add_filter( 'generateblocks_pro_dynamic_tags_is_acf_field', function( $is_acf_field, $acf_id, $acf_keys, $args ) {
list( $value, $id, $key, $type ) = $args;
if ( ! $is_acf_field && 'my_acf_field' === $key ) {
return true;
}
return $is_acf_field;
}, 10, 4 );Related: generateblocks_get_meta_value Guide: Dynamic Tags
Editor (JavaScript)
These are wp.hooks filters. Add them with wp.hooks.addFilter() in a script that loads in the block editor, after wp-hooks and the GenerateBlocks editor scripts.
generateblocks.dynamicTags.sourceOptions
GB Free
The generateblocks.dynamicTags.sourceOptions filter changes the choices in the Source select of the dynamic tag modal.
Parameters: options (array of { label, value }), context (object with dynamicTagType, which is post, term or user). Default: current and specific post, term or user, depending on the tag type. For example, post tags get Current Post (current) and Specific Post (post).
wp.hooks.addFilter(
'generateblocks.dynamicTags.sourceOptions',
'my-plugin/source-options',
( options, { dynamicTagType } ) => {
if ( 'post' === dynamicTagType ) {
return [ ...options, { label: 'My Source', value: 'my-source' } ];
}
return options;
}
);Related: generateblocks.dynamicTags.sourcesInOptions Guide: Dynamic Tags
generateblocks.dynamicTags.sourcesInOptions
GB Free
The generateblocks.dynamicTags.sourcesInOptions filter lists source values that are saved in the tag as a source option. A source in this list is written as source:{value}, and read back from that option when you edit the tag.
Parameters: sources (array of strings). Default: an empty array.
wp.hooks.addFilter(
'generateblocks.dynamicTags.sourcesInOptions',
'my-plugin/sources-in-options',
( sources ) => [ ...sources, 'my-source' ]
);Related: generateblocks.dynamicTags.sourceOptions Guide: Dynamic Tags
generateblocks.editor.dynamicTags.termRecord
GB Free
The generateblocks.editor.dynamicTags.termRecord filter changes the term record the editor loads for a term tag.
Parameters: record (the term record from the core data store, or undefined while it loads). Default: the record unchanged.
wp.hooks.addFilter(
'generateblocks.editor.dynamicTags.termRecord',
'my-plugin/term-record',
( record ) => ( record ? { ...record, my_value: 'example' } : record )
);Related: generateblocks.editor.dynamicTags.term-request-params Guide: Dynamic Tags
generateblocks.editor.dynamicTags.term-request-params
GB Free
The generateblocks.editor.dynamicTags.term-request-params filter changes the arguments the editor passes to getEntityRecord() when it loads a term.
Parameters: params (array of [ 'taxonomy', taxonomy, termId ]). Default: [ 'taxonomy', taxonomy, termId ].
wp.hooks.addFilter(
'generateblocks.editor.dynamicTags.term-request-params',
'my-plugin/term-request-params',
( params ) => [ ...params, { context: 'edit' } ]
);Related: generateblocks.editor.dynamicTags.termRecord Guide: Dynamic Tags
generateblocks.editor.tagSpecificControls
GB Free
The generateblocks.editor.tagSpecificControls filter changes the control shown for each option of a tag in the dynamic tag modal. It runs once for every option the selected tag defines.
Parameters: control (the control element for one option), options (the whole options definition of the selected tag, as registered with the tag: each option’s type, label, help, options and placeholder), context (object with state, the current option values, and setState, which updates them). Default: the control element unchanged.
wp.hooks.addFilter(
'generateblocks.editor.tagSpecificControls',
'my-plugin/tag-controls',
( control, options, { state, setState } ) => control
);Related: Registering dynamic tags Guide: Dynamic Tags