Architecting Scalable Full Site Editing (FSE) Block Themes and theme.json Using Custom Action and Filter Hooks

Leveraging Custom Hooks for Advanced theme.json and FSE Customization

Full Site Editing (FSE) and the accompanying `theme.json` paradigm offer unprecedented control over WordPress theme structure and design. However, as themes grow in complexity and specific functional requirements emerge, relying solely on the built-in `theme.json` schema and block-level controls can become restrictive. This document details advanced strategies for extending FSE capabilities by programmatically manipulating `theme.json` and block rendering through custom action and filter hooks. We will explore scenarios requiring dynamic style generation, conditional feature enablement, and deep integration with external data sources.

Programmatic `theme.json` Modification with `theme_json_data_filters`

The `theme.json` file is parsed and processed by WordPress core. To dynamically alter its contents before it’s applied to the frontend or editor, we can leverage the `theme_json_data_filters` hook. This filter allows us to intercept the parsed JSON data and modify it based on various conditions, such as user roles, active plugins, or even external API responses. This is particularly useful for enabling or disabling specific design features or setting default values that are context-dependent.

Consider a scenario where you want to enable a specific color palette or typography setting only for administrators. We can achieve this by filtering the `theme.json` data.

Conditional Color Palette Application

Here’s a PHP snippet that demonstrates how to add a custom color palette to `theme.json` only if the current user has the `manage_options` capability.

add_filter( 'theme_json_data_filters', function( $theme_json_data ) {
    // Check if the current user has administrator privileges.
    if ( current_user_can( 'manage_options' ) ) {
        // Get the existing theme.json data.
        $data = $theme_json_data->get_data();

        // Define the custom color palette.
        $custom_palette = [
            'name' => esc_html__( 'Admin Palette', 'your-text-domain' ),
            'color' => '#0073aa', // WordPress blue
            'slug' => 'admin-blue',
        ];

        // Ensure 'settings.color.palette' exists and is an array.
        if ( ! isset( $data['settings']['color']['palette'] ) || ! is_array( $data['settings']['color']['palette'] ) ) {
            $data['settings']['color']['palette'] = [];
        }

        // Add the custom palette if it doesn't already exist.
        $palette_exists = false;
        foreach ( $data['settings']['color']['palette'] as $palette_item ) {
            if ( isset( $palette_item['slug'] ) && $palette_item['slug'] === 'admin-blue' ) {
                $palette_exists = true;
                break;
            }
        }

        if ( ! $palette_exists ) {
            $data['settings']['color']['palette'][] = $custom_palette;
        }

        // Update the theme.json data.
        $theme_json_data->update_settings( 'color.palette', $data['settings']['color']['palette'] );
    }

    return $theme_json_data;
} );

In this example, we first check user capabilities. If the user is an administrator, we retrieve the current `theme.json` data, define a new color palette, and then merge it into the existing `settings.color.palette` array. The `update_settings` method is crucial for ensuring the changes are correctly applied to the theme’s JSON structure.

Dynamic Font Size Settings

Similarly, we can dynamically adjust font sizes based on site configuration or active plugins. For instance, if a specific SEO plugin is active, we might want to enforce a minimum font size for better readability.

add_filter( 'theme_json_data_filters', function( $theme_json_data ) {
    // Example: Enforce a minimum font size if a specific plugin is active.
    if ( defined( 'MY_SEO_PLUGIN_VERSION' ) ) { // Replace with actual plugin check.
        $data = $theme_json_data->get_data();

        // Ensure 'settings.typography.fontSizes' exists and is an array.
        if ( ! isset( $data['settings']['typography']['fontSizes'] ) || ! is_array( $data['settings']['typography']['fontSizes'] ) ) {
            $data['settings']['typography']['fontSizes'] = [];
        }

        // Define a minimum font size.
        $min_font_size = [
            'name' => esc_html__( 'Minimum', 'your-text-domain' ),
            'size' => '1rem', // Or '16px'
            'slug' => 'minimum',
        ];

        // Check if a font size with the slug 'minimum' already exists.
        $min_size_exists = false;
        foreach ( $data['settings']['typography']['fontSizes'] as $font_size_item ) {
            if ( isset( $font_size_item['slug'] ) && $font_size_item['slug'] === 'minimum' ) {
                $min_size_exists = true;
                break;
            }
        }

        if ( ! $min_size_exists ) {
            // Add the minimum font size to the beginning of the array.
            array_unshift( $data['settings']['typography']['fontSizes'], $min_font_size );
        }

        $theme_json_data->update_settings( 'typography.fontSizes', $data['settings']['typography']['fontSizes'] );
    }

    return $theme_json_data;
} );

This snippet checks for a hypothetical plugin constant. If found, it adds a ‘Minimum’ font size option. Using `array_unshift` places this new option at the beginning of the list, potentially making it the default or most prominent choice in the editor.

Customizing Block Rendering with `render_block` and `block_type_metadata`

While `theme.json` controls global styles and settings, individual blocks often require custom rendering logic or attribute manipulation. The `render_block` filter is your primary tool for intercepting and modifying the output of any block, including core blocks, custom blocks, and blocks from third-party plugins. The `block_type_metadata` filter allows for more granular control over block registration and its associated attributes and features.

Conditional Block Attribute Modification

Imagine you want to automatically add a specific CSS class to all `core/image` blocks when a certain condition is met, perhaps to apply a special hover effect that’s only enabled on specific pages or for logged-in users.

add_filter( 'render_block', function( $block_content, $block ) {
    // Target only the core/image block.
    if ( 'core/image' === $block['blockName'] ) {
        // Example condition: apply class on specific post types or if a custom field is set.
        if ( is_singular( 'post' ) && get_post_meta( get_the_ID(), '_enable_fancy_image_effect', true ) ) {
            // Add a custom class to the image block's wrapper.
            // This assumes the block wrapper is a div. More robust parsing might be needed.
            $block_content = preg_replace( '/(



This filter receives the block's rendered HTML content and the block's attributes. We check the `blockName` and, if it matches `core/image`, we then apply a conditional check (here, checking if it's a singular post and a custom field `_enable_fancy_image_effect` is set). If the condition is true, we use `preg_replace` to inject a CSS class into the block's outer `div`. Note that directly manipulating HTML with regex can be brittle; for complex scenarios, DOM parsing libraries might be more appropriate.



Enforcing Block Constraints with `block_type_metadata`



The `block_type_metadata` filter allows you to modify the metadata of a block *before* it's registered. This is powerful for enforcing constraints, such as disabling certain features of a block or adding default attributes. For instance, you might want to prevent users from changing the alignment of specific blocks or ensure a default `align` value.



add_filter( 'block_type_metadata', function( $metadata, $name ) {
    // Example: Disable alignment controls for the core/button block.
    if ( 'core/button' === $name ) {
        // Ensure 'supports' key exists.
        if ( isset( $metadata['attributes']['align'] ) ) {
            // Remove alignment support.
            unset( $metadata['attributes']['align'] );
        }
        // Alternatively, to disable specific supports like color, background, etc.
        // if ( isset( $metadata['supports'] ) ) {
        //     $metadata['supports']['color'] = false;
        //     $metadata['supports']['background'] = false;
        // }
    }

    // Example: Set a default value for a custom block's attribute.
    // if ( 'my-plugin/my-custom-block' === $name ) {
    //     if ( isset( $metadata['attributes']['some_attribute'] ) ) {
    //         $metadata['attributes']['some_attribute']['default'] = 'default_value';
    //     }
    // }

    return $metadata;
}, 10, 2 );



In this example, we target the `core/button` block. If the block's name matches, we check for the `align` attribute within `metadata['attributes']` and remove it, effectively disabling alignment controls for buttons in the editor and frontend. The commented-out section shows how you could disable other `supports` like color or background. This filter is also ideal for setting default values for custom block attributes.



Advanced Use Cases and Architectural Considerations



The techniques discussed above form the foundation for building highly dynamic and adaptable FSE themes. Here are some advanced considerations:



Dynamic `theme.json` Generation: For extremely complex themes or those requiring real-time configuration changes (e.g., based on user preferences stored in post meta or options), consider generating the `theme.json` structure entirely within PHP using the `theme_json` filter. This allows for full programmatic control over every aspect of the theme's styling and settings.
Performance Optimization: While dynamic modification is powerful, be mindful of performance. Heavy computations within filters, especially those that run on every page load, can impact performance. Cache generated `theme.json` data where possible, or ensure your conditional logic is efficient.
Editor vs. Frontend Consistency: Ensure that any modifications made via filters are consistently applied in both the editor and the frontend. The `render_block` filter affects frontend output, while `theme_json_data_filters` and `block_type_metadata` influence both. Test thoroughly.
User Experience in the Editor: When disabling block features or modifying attributes, consider the user experience. Provide clear feedback or documentation if certain controls are intentionally hidden or altered.
Integration with Custom Post Types and Taxonomies: Leverage WordPress's conditional tags (e.g., `is_singular()`, `is_archive()`, `is_tax()`) within your filter callbacks to apply FSE customizations on a per-content-type basis.
External Data Sources: For themes that pull design elements or configurations from external APIs or services, implement robust caching mechanisms to avoid excessive API calls and ensure responsiveness.



Example: Theme.json Generation for a Multi-Tenant Site



In a multi-tenant WordPress setup, each tenant might have unique branding. We can dynamically generate `theme.json` based on tenant-specific options.



add_filter( 'theme_json', function( $theme_json, $context ) {
    // Assuming a function get_tenant_branding() exists that returns an array of branding settings.
    // This function would typically fetch data from a custom options table or a multisite setting.
    $branding_settings = get_tenant_branding(); // Example: returns ['primary_color' => '#ff0000', 'font_family' => 'Arial']

    if ( ! empty( $branding_settings ) ) {
        // Merge with existing theme.json data.
        // This is a simplified merge; a deep merge function would be more robust.
        if ( isset( $branding_settings['primary_color'] ) ) {
            $theme_json['settings']['color']['palette'][] = [
                'name' => esc_html__( 'Tenant Primary', 'your-text-domain' ),
                'color' => $branding_settings['primary_color'],
                'slug' => 'tenant-primary',
            ];
            // Also set this as the default accent color if desired.
            $theme_json['settings']['color']['accent'] = $branding_settings['primary_color'];
        }

        if ( isset( $branding_settings['font_family'] ) ) {
            $theme_json['settings']['typography']['fontFamily'] = $branding_settings['font_family'];
        }
    }

    return $theme_json;
}, 10, 2 );

// Placeholder for the actual function to get tenant branding.
function get_tenant_branding() {
    // In a real scenario, this would query a database or use multisite options.
    // Example: return ['primary_color' => '#0073aa', 'font_family' => 'Georgia'];
    // For demonstration, let's simulate fetching data.
    if ( defined( 'TENANT_ID' ) ) { // Assume TENANT_ID is defined in a multisite context.
        // Fetch from options based on TENANT_ID
        $primary_color = get_option( 'tenant_' . TENANT_ID . '_primary_color' );
        $font_family = get_option( 'tenant_' . TENANT_ID . '_font_family' );

        $settings = [];
        if ( $primary_color ) $settings['primary_color'] = $primary_color;
        if ( $font_family ) $settings['font_family'] = $font_family;
        return $settings;
    }
    return []; // Return empty if no tenant context or settings found.
}



This advanced example uses the `theme_json` filter, which receives the fully parsed `theme.json` array. It then merges tenant-specific branding colors and fonts directly into the structure. The `get_tenant_branding()` function is a placeholder for logic that would fetch tenant-specific configurations, crucial for multi-tenant architectures. This approach offers maximum flexibility, allowing `theme.json` to be entirely dynamic.



Conclusion



By mastering custom action and filter hooks in conjunction with `theme.json` and block rendering, WordPress developers can transcend the limitations of standard FSE implementations. These advanced techniques empower the creation of highly customized, context-aware, and scalable themes that adapt to complex project requirements. Careful planning, rigorous testing, and a deep understanding of WordPress's hook system are key to successfully architecting such sophisticated FSE solutions.