Skip to content

Hooks

Filters and actions available for customizing pages, patterns, Site Templates, and the HTML parser.

Parser

blockstudio/block_tags/builders

Register block-array builders used by block tags and element-mapped custom blocks. The callback for each block receives an attributes array and raw inner content.

PHP
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
    $builders['acf/hero'] = function( array $attrs, string $inner_content ) {
        $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );

        return array(
            'blockName'    => 'acf/hero',
            'attrs'        => $attrs,
            'innerBlocks'  => $inner_blocks,
            'innerHTML'    => '',
            'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
        );
    };

    return $builders;
}, 10, 2 );

blockstudio/block_tags/renderers and blockstudio/parser/renderers receive the same registry. They run after blockstudio/block_tags/builders, in that order, and can replace an earlier builder for the same block.

blockstudio/parser/element_mapping

Override the default HTML element to block mapping. By default, standard HTML elements like <h1>, <p>, and <img> map to core WordPress blocks. Use this filter to point any element to a different block.

PHP
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
    $mapping['h1']  = 'custom/heading';
    $mapping['h2']  = 'custom/heading';
    $mapping['p']   = 'custom/paragraph';
    $mapping['img'] = 'custom/image';

    return $mapping;
}, 10, 2 );

If <p> maps to a registered non-core Blockstudio block with a content richtext attribute, its inner HTML is copied to that attribute, including inline tags such as code and img that are also element-mapped. A paragraph whose only child is an image becomes the block <img> maps to. Nested block tags or block-level HTML keep the normal inner-block parsing behavior.

Pages

blockstudio/pages/paths

Filter the directories scanned for page templates.

PHP
add_filter( 'blockstudio/pages/paths', function( $paths ) {
    $paths[] = get_template_directory() . '/custom-pages';
    $paths[] = MY_PLUGIN_DIR . '/pages';
    return $paths;
} );

blockstudio/pages/manifest_scan_interval

Filter the maximum age of a legacy pre-7.6.2 manifest cache that can seed the persisted collection runtime during an upgrade. Normal requests use the persisted collection configuration and do not periodically rescan page roots. Run wp bs pages sync or call Blockstudio\Pages::reconcile() after changing a collection manifest.

PHP
add_filter( 'blockstudio/pages/manifest_scan_interval', function() {
    return 10;
} );

blockstudio/pages/create_post_data

Filter post data before creating a new page.

PHP
add_filter( 'blockstudio/pages/create_post_data', function( $post_data, $page_data ) {
    $post_data['post_author'] = 1;
    return $post_data;
}, 10, 2 );

blockstudio/pages/update_post_data

Filter post data before updating an existing page.

PHP
add_filter( 'blockstudio/pages/update_post_data', function( $post_data, $post, $page_data ) {
    return $post_data;
}, 10, 3 );

blockstudio/pages/synced

Action fired after all pages have been synced.

PHP
add_action( 'blockstudio/pages/synced', function( $registry ) {
    // $registry is the Page_Registry instance
} );

blockstudio/pages/post_created

Action fired after a page post is created.

PHP
add_action( 'blockstudio/pages/post_created', function( $post_id, $page_data ) {
    // Do something after page creation
}, 10, 2 );

blockstudio/pages/post_updated

Action fired after a page post is updated.

PHP
add_action( 'blockstudio/pages/post_updated', function( $post_id, $page_data ) {
    // Do something after page update
}, 10, 2 );

Patterns

blockstudio/patterns/paths

Filter the directories scanned for pattern templates.

PHP
add_filter( 'blockstudio/patterns/paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/custom-patterns';
    $paths[] = MY_PLUGIN_PATH . '/patterns';
    return $paths;
} );

blockstudio/patterns/registered

Action fired after all patterns have been registered.

PHP
add_action( 'blockstudio/patterns/registered', function( $registry ) {
    // $registry is the Pattern_Registry instance
} );

Site Templates

blockstudio/site_templates/template_paths

Filter the directories scanned for template.json files.

PHP
add_filter( 'blockstudio/site_templates/template_paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/site-templates';
    return $paths;
} );

blockstudio/site_templates/part_paths

Filter the directories scanned for part.json files.

PHP
add_filter( 'blockstudio/site_templates/part_paths', function( $paths ) {
    $paths[] = get_stylesheet_directory() . '/site-parts';
    return $paths;
} );

blockstudio/site_templates/paths

Filter both discovery path lists together. The value contains templates and parts arrays.

PHP
add_filter( 'blockstudio/site_templates/paths', function( $paths ) {
    return $paths;
} );

blockstudio/site_templates/template_candidates

Filter source-file candidates after the manifest and logical source tree have been resolved.

PHP
add_filter(
    'blockstudio/site_templates/template_candidates',
    function( $candidates, $directory, $manifest ) {
        $candidates[] = $directory . '/template.custom.php';
        return $candidates;
    },
    10,
    3
);

blockstudio/site_templates/templates

Filter full templates returned by the registry API.

PHP
add_filter( 'blockstudio/site_templates/templates', function( $templates ) {
    return $templates;
} );

blockstudio/site_templates/parts

Filter template parts returned by the registry API.

PHP
add_filter( 'blockstudio/site_templates/parts', function( $parts ) {
    return $parts;
} );

blockstudio/site_templates/template_content

Filter a template source string before Blockstudio parses it into blocks.

PHP
add_filter( 'blockstudio/site_templates/template_content', function( $content, $template ) {
    return $content;
}, 10, 2 );

blockstudio/site_templates/part_content

Filter a template part source string before Blockstudio parses it into blocks.

PHP
add_filter( 'blockstudio/site_templates/part_content', function( $content, $part ) {
    return $content;
}, 10, 2 );

blockstudio/site_templates/parser

Filter the Blockstudio\Html_Parser instance used for one compiled template or part. Return an Html_Parser; other values fall back to the default parser.

PHP
add_filter(
    'blockstudio/site_templates/parser',
    function( $parser, $item ) {
        return $parser;
    },
    10,
    2
);

blockstudio/site_templates/discovered

Action fired after a cold discovery and compilation pass, before the rebuilt registry is persisted.

PHP
add_action( 'blockstudio/site_templates/discovered', function( $registry ) {
    // Inspect the rebuilt Site_Template_Registry.
} );

blockstudio/site_templates/registered

Action fired after a rebuilt file-backed Site Editor template registry has been persisted.

PHP
add_action( 'blockstudio/site_templates/registered', function( $registry ) {
    // $registry is the Site_Template_Registry instance
} );

The discovered and registered actions do not fire on a warm registry cache hit.