Menu Close

Blocksify Docs

CSS pipeline filters deep dive

Blocksify CSS filters let developers adjust the pooled pipeline without editing core files.

This guide covers collection, final output, and file-mode internals.

Pre-release builds used dotted names such as blocksify.css.output; every release from 1.0.0 uses the underscore names, and there is no compatibility shim for the old names. Old dotted-name add_filter() calls silently do nothing.

What the pipeline emits

Blocksify_CSS_Pipeline is the single frontend delivery path for Blocksify block CSS. It pools static block CSS and per-instance CSS into one handle instead of scattering per-block links and inline styles.

LayerSource
Static base CSSBuilt block styles from build/blocks/{name}/blocksify-{name}.css, included once per active block type.
Per-instance CSSBlocksify_CSS_Generator::generate_block_css(), targeting each block’s per-instance class.
Token variablesGlobal :root emitters, outside the cached per-page CSS file.

For the user-facing performance model, see How Blocksify keeps your site fast. For the broader extension surface, start with Extending Blocksify: hooks overview.

Gate, page, and print method filters

Use the first group to control whether the pipeline runs, which page ID it scans, and whether output uses file or inline delivery.

FilterReceivesReturns
blocksify_css_enabledtrueBoolean gate for the whole pipeline.
blocksify_css_page_idThe resolved singular post ID.Post ID to scan, or 0.
blocksify_css_print_methodThe dashboard output mode.file or inline.

Force inline during a custom preview.

add_filter(
    'blocksify_css_print_method',
    function ( $method ) {
        return is_preview() ? 'inline' : $method;
    }
);

Collection filters

blocksify_css_collected_blocks lets an integration add block entries before generation. Entries carry a block name and attrs.

FilterReceivesReturns
blocksify_css_collected_blocksThe collected block entries.The block entries to generate.
blocksify_css_attrsOne block’s attributes and block name.The attributes passed into defaults merge and CSS generation.

Add an integration-owned block entry.

add_filter(
    'blocksify_css_collected_blocks',
    function ( $blocks ) {
        $blocks[] = array(
            'name'  => 'blocksify/button',
            'attrs' => array(
                'uid' => 'integration-preview',
            ),
        );

        return $blocks;
    }
);

Normalize attrs before CSS generation.

add_filter(
    'blocksify_css_attrs',
    function ( $attrs, $name ) {
        if ( 'blocksify/button' === $name && empty( $attrs['uid'] ) ) {
            $attrs['uid'] = 'fallback';
        }

        return $attrs;
    },
    10,
    2
);

Dynamic integrations can supply generated Blocksify block entries that do not appear directly in post_content. If you are extending Content Loop, keep renderers generic and add CSS inputs through public seams.

Per-block CSS filters

This group changes CSS at block granularity. Use blocksify_css_static_block for one block type’s static base CSS and blocksify_css_block for one block instance’s generated CSS.

Append a static rule for one block type.

add_filter(
    'blocksify_css_static_block',
    function ( $css, $name ) {
        if ( 'blocksify/section' !== $name ) {
            return $css;
        }

        return $css . "\n/* Extension static CSS for Sections. */\n";
    },
    10,
    2
);

Append CSS for a generated block instance.

add_filter(
    'blocksify_css_block',
    function ( $css, $name, $attrs ) {
        if ( 'blocksify/container' !== $name || empty( $attrs['uid'] ) ) {
            return $css;
        }

        return $css . "\n/* Container " . sanitize_key( $attrs['uid'] ) . " */\n";
    },
    10,
    3
);

Final output filter

blocksify_css_output runs after the CSS pool is concatenated and before it is emitted. Use it for final global changes, not for logic that needs to know which block produced a rule.

Append a final diagnostic comment.

add_filter(
    'blocksify_css_output',
    function ( $css ) {
        return $css . "\n/* Generated through Blocksify CSS pipeline. */\n";
    }
);

File mode internals

File mode is default. On singular pages, Blocksify writes pooled CSS to uploads/blocksify/style-{post_id}.css, or style-{post_id}-blog-{blog_id}.css on multisite, and enqueues it with ?ver=filemtime.

NamePurpose
blocksify_css_generation optionStores the global CSS epoch. It is not a filter.
blocksify_css_cache_generationFilters the effective global epoch used at build time and freshness-check time.
_blocksify_css_builtPer-post marker showing which generation built the file.
save_postInvalidates cached CSS after supported post saves.
Plugin version changeBumps the generation counter because static base CSS may have changed.
Clear cache or regenerateBumps the counter without deleting files, avoiding stale cached HTML pointing to a missing file.
FilterReceivesReturns
blocksify_css_cache_generationThe stored generation integer.The effective generation integer.
blocksify_css_inline_thresholdThe default threshold, 500 bytes.Byte threshold for inline CSS.
blocksify_css_conditional_blocksConditional CSS and collected block entries.The conditional CSS bundle.
blocksify_css_file_owner_post_typesExtra file-owner post types, defaulting to blocksify_template.Post types that may own stable CSS files.

Tune file-mode filters.

add_filter( 'blocksify_css_cache_generation', 'absint' );
add_filter( 'blocksify_css_inline_threshold', function () {
    return 1024;
} );
add_filter( 'blocksify_css_conditional_blocks', function ( $css, $collected ) {
    return $css;
}, 10, 2 );
add_filter( 'blocksify_css_file_owner_post_types', function ( $post_types ) {
    $post_types[] = 'portfolio';
    return $post_types;
} );

Preview, Customizer preview, AMP, write failures, and CSS pools under the threshold fall back inline. Token value edits do not invalidate the file because Global Settings token variables are emitted on :root every request.

Was this helpful?

0

Updated