Data Filters

This page documents filters for customizing data providers, meta values, and expression extensions.

Filter	Description
`unblock/data/providers`	Register custom data providers
`unblock/data/filters`	Register custom expression filters
`unblock/data/functions`	Register custom expression functions
`unblock/data/post_meta`	Filter post meta values
`unblock/data/user_meta`	Filter user meta values
`unblock/data/term_meta`	Filter term meta values
`unblock/data/option_meta`	Pre-filter for option retrieval from Site provider
`unblock/data/allowed_options`	Whitelist accessible WordPress options
`unblock/data/allowed_meta_keys`	Whitelist protected meta keys

data/providers

Parameter	Type	Description
`$providers`	array	Registered providers configuration

Each provider is an array of fields. Each field requires:

label — Display label for the field
callback — Callable that returns the field value

Optional field properties:

escape — Escape function (false, 'esc_url', etc.)
returns — Return type hint ('WP_User', 'WP_Term', 'WP_Post', 'Reference')

Example: Register Custom Provider

add_filter( 'unblock/data/providers', function( $providers ) {

    $providers['shop'] = [
        'name' => [
            'label'    => __( 'Shop Name', 'flavor' ),
            'callback' => fn( $context, $args ) => get_option( 'blogname' ),
        ],
        'url'  => [
            'label'    => __( 'Shop URL', 'flavor' ),
            'escape'   => 'esc_url',
            'callback' => fn( $context, $args ) => home_url( '/shop' ),
        ],
        'phone' => [
            'label'    => __( 'Phone', 'flavor' ),
            'callback' => fn( $context, $args ) => get_option( 'shop_phone', '+1 555-0100' ),
        ],
    ];

    return $providers;

} );

Use in expressions: {{ shop.name }}, {{ shop.url }}, {{ shop.phone }}

data/filters

Parameter	Type	Description
`$filters`	array	Registered filters configuration

Example: Reading Time Filter

The first argument is always the piped value. Additional arguments follow:

add_filter( 'unblock/data/filters', function( $filters ) {

    $filters['reading_time'] = [
        'callback' => fn( $value, $wpm = 200 ) => max( 1, (int) round( str_word_count( strip_tags( $value ) ) / $wpm ) ),
    ];

    return $filters;

} );

Use in expressions: {{ post.content|reading_time }} or {{ post.content|reading_time(150) }}

data/functions

Parameter	Type	Description
`$functions`	array	Registered functions configuration

Example: Current Year Function

Arguments are passed as an indexed array — $args[0] is the first argument, $args[1] the second, etc.:

add_filter( 'unblock/data/functions', function( $functions ) {

    $functions['year'] = [
        'callback' => fn( $args ) => gmdate( $args[0] ?? 'Y' ),
    ];

    return $functions;

} );

Use in expressions: © {{ year() }} or {{ year('y') }}

Example: Function with Provider Return

Functions that return provider objects can declare a returns key so users can chain property access:

add_filter( 'unblock/data/functions', function( $functions ) {

    $functions['featured_post'] = [
        'callback' => fn( $args ) => (int) get_option( 'featured_post_id', 0 ),
        'returns'  => 'WP_Post',
    ];

    return $functions;

} );

Use in expressions: {{ featured_post().title }}

data/post_meta

Pre-filter for post meta retrieval. Return a non-null value to override get_metadata().

apply_filters( 'unblock/data/post_meta', null, string $meta_key, int $post_id, array $options );

Parameter	Type	Description
`$value`	mixed	Return non-null to override. Default: `null`
`$meta_key`	string	Meta key name
`$post_id`	int	Post ID
`$options`	array	Additional options from the expression

Common mistake

This filter receives null as the initial value — not the actual meta value. Return null to let WordPress handle the lookup. Returning any other value skips get_metadata() entirely.

Example: Type Conversion

add_filter( 'unblock/data/post_meta', function( $value, $meta_key, $post_id, $options ) {

    if ( $meta_key === 'price' ) {
        return floatval( get_post_meta( $post_id, $meta_key, true ) );
    }

    return null;

}, 10, 4 );

data/user_meta

Pre-filter for user meta retrieval. Return a non-null value to override get_metadata().

apply_filters( 'unblock/data/user_meta', null, string $meta_key, int $user_id, array $options );

Parameter	Type	Description
`$value`	mixed	Return non-null to override. Default: `null`
`$meta_key`	string	Meta key name
`$user_id`	int	User ID
`$options`	array	Additional options from the expression

Example: Type Conversion

add_filter( 'unblock/data/user_meta', function( $value, $meta_key, $user_id, $options ) {

    if ( $meta_key === 'points' ) {
        return intval( get_user_meta( $user_id, $meta_key, true ) );
    }

    return null;

}, 10, 4 );

data/term_meta

Pre-filter for term meta retrieval. Return a non-null value to override get_metadata().

apply_filters( 'unblock/data/term_meta', null, string $meta_key, int $term_id, array $options );

Parameter	Type	Description
`$value`	mixed	Return non-null to override. Default: `null`
`$meta_key`	string	Meta key name
`$term_id`	int	Term ID
`$options`	array	Additional options from the expression

Example: Fallback Value

add_filter( 'unblock/data/term_meta', function( $value, $meta_key, $term_id, $options ) {

    $meta = get_term_meta( $term_id, $meta_key, true );

    if ( $meta_key === 'icon_url' && empty( $meta ) ) {
        return '/wp-content/themes/flavor/images/default-icon.svg';
    }

    return $meta ?: null;

}, 10, 4 );

data/option_meta

Pre-filter for option retrieval from the Site provider. Return a non-null value to override get_option().

apply_filters( 'unblock/data/option_meta', null, string $key, array $options );

Parameter	Type	Description
`$value`	mixed	Return non-null to override. Default: `null`
`$key`	string	Option key being retrieved
`$options`	array	Additional options context

Example: ACF Options Page

add_filter( 'unblock/data/option_meta', function( $value, $key, $options ) {

    if ( function_exists( 'get_field' ) ) {
        return get_field( $key, 'option' );
    }

    return null;

}, 10, 3 );

data/allowed_options

Whitelist WordPress options accessible via site.option().

Parameter	Type	Description
`$allowed`	array	Allowed option names

Default: ['date_format', 'time_format']

Example: Add Custom Option

add_filter( 'unblock/data/allowed_options', function( $allowed ) {

    $allowed[] = 'my_custom_option';

    return $allowed;

} );

Example: Theme Settings

add_filter( 'unblock/data/allowed_options', function( $allowed ) {

    $allowed[] = 'theme_mods_flavor';
    $allowed[] = 'flavor_settings';
    $allowed[] = 'social_links';

    return $allowed;

} );

Use in expressions: {{ site.option('social_links').twitter }}

data/allowed_meta_keys

Whitelist metadata keys that bypass protection checks. By default, private meta keys (starting with _) are blocked for security.

Parameter	Type	Description
`$allowed`	array	Allowed meta keys
`$meta_type`	string	Meta type: `'post'`, `'user'`, or `'term'`

Default: [] (empty — all private meta keys blocked)

Example: Allow Private Field

add_filter( 'unblock/data/allowed_meta_keys', function( $allowed, $meta_type ) {

    if ( $meta_type === 'post' ) {
        $allowed[] = '_my_private_field';
    }

    return $allowed;

}, 10, 2 );

Example: Allow ACF Fields

add_filter( 'unblock/data/allowed_meta_keys', function( $allowed, $meta_type ) {

    if ( $meta_type === 'post' ) {

        $allowed[] = '_edit_lock';
        $allowed[] = '_edit_last';

    }

    return $allowed;

}, 10, 2 );

Next steps

Query filters — modify loop query arguments
Security filters — customize HTML and SVG sanitization
Actions — plugin lifecycle and form hooks

data/providers​

data/filters​

data/functions​

data/post_meta​

data/user_meta​

data/term_meta​

data/option_meta​

data/allowed_options​

data/allowed_meta_keys​

Next steps​