Query and Looper – Learn GeneratePress

Hooks for the Query block, which builds the list of items, and the Looper block, which repeats its Loop Item block for each of them. Use the first group to change the standard post query, and the second to add a query type of your own, such as items from an API or a custom table.

The post query

generateblocks_query_wp_query_args

GB Free — GenerateBlocks Pro also uses it.

The generateblocks_query_wp_query_args filter changes the WP_Query arguments for the Query block (wp:generateblocks/query), after GenerateBlocks has built them from the block’s settings. It does not run when the block inherits the main query.

Parameters: $args (array, the WP_Query arguments), $attributes (array, the block attributes), $block (the WP_Block, or an empty stdClass when there isn’t one), $current (array with post_id and author_id, the current post and author). Default: the arguments built from the block’s query settings.

Example 1: order by a date meta field. Add order-by-date to the Query block’s classes.

add_filter( 'generateblocks_query_wp_query_args', function( $args, $attributes ) {
    if ( ! empty( $attributes['className'] ) && strpos( $attributes['className'], 'order-by-date' ) !== false ) {
        $args = array_merge( 
            $args, 
            [
                'meta_key'  => 'date_from',
                'meta_type' => 'DATE',
                'orderby'   => 'meta_value',
                'order'     => 'ASC',
            ]
        );
    }

    return $args;
}, 10, 2 );

generateblocks_rest_get_wp_query_args

GB Free

The generateblocks_rest_get_wp_query_args filter changes the arguments the editor preview sends to the generateblocks/v1/get-wp-query route, before they are turned into WP_Query arguments. Use it when a change you make with generateblocks_query_wp_query_args also needs to show in the editor.

Parameters: $args (array, the query arguments), $props (array with page, attributes, context, current (the current post_id and author_id) and query_type). Default: the arguments from the editor request.

add_filter( 'generateblocks_rest_get_wp_query_args', function( $args, $props ) {
    if ( ! empty( $props['attributes']['className'] ) && false !== strpos( $props['attributes']['className'], 'only-sticky' ) ) {
        $args['ignore_sticky_posts'] = false;
    }

    return $args;
}, 10, 2 );

generateblocks_query_per_page_default

GB Free

The generateblocks_query_per_page_default filter sets the number of items per page when the query doesn’t set posts_per_page. The Query Page Numbers block and the previous and next page dynamic tags use it.

Parameters: $per_page (int), $args (array, the query arguments). Default: 10.

add_filter( 'generateblocks_query_per_page_default', function( $per_page, $args ) {
    return 12;
}, 10, 2 );

generateblocks_query_loop_editor_posts_cap

GB Free — since GenerateBlocks 2.5.

The generateblocks_query_loop_editor_posts_cap filter sets the most items a Query block shows in the editor preview. A value that isn’t a number of at least 1 is ignored.

Parameters: $cap (int). Default: 50.

add_filter( 'generateblocks_query_loop_editor_posts_cap', function( $cap ) {
    return 20;
} );

Custom query types

The Query block has a query type. The built-in type is WP_Query. GenerateBlocks Pro adds post_meta and option, which loop over the values of a meta field or an option. To add another type you need three pieces: a JavaScript filter so the type can be chosen in the editor, generateblocks_query_data to return the items, and generateblocks_looper_render_loop_items to render them.

generateblocks_query_data

GB Free — GenerateBlocks Pro uses it for its post_meta and option query types.

The generateblocks_query_data filter changes the Query block’s data. For the WP_Query type it receives the WP_Query object. For any other type it receives an empty set, which you replace with your own items.

Parameters: $query_data (array), $query_type (string, such as WP_Query), $attributes (array, the block attributes), $block (the WP_Block), $page (int, the current page number). Default: for WP_Query, data is the WP_Query object, no_results is true when it found no posts and args holds the final query arguments. For other types, data is an empty array, no_results is true and args holds the block’s query settings.

$query_data has these keys:

data: the items to loop over.
no_results: whether to show the Query No Results block.
args: the query arguments, which pagination reads. posts_per_page is used for paging.
max_num_pages (optional): the total number of pages. GenerateBlocks Pro sets it for its own types.

add_filter( 'generateblocks_query_data', function( $query_data, $query_type, $attributes, $block, $page ) {
    if ( 'my_api' !== $query_type ) {
        return $query_data;
    }

    $items = my_plugin_get_items(); // Returns an array of arrays, each with an 'id' key.

    return [
        'data'          => $items,
        'no_results'    => empty( $items ),
        'args'          => $attributes['query'] ?? [],
        'max_num_pages' => 1,
    ];
}, 10, 5 );

generateblocks_looper_render_loop_items

GB Free — GenerateBlocks Pro uses it for its post_meta and option query types.

The generateblocks_looper_render_loop_items filter replaces the Looper block’s rendered items. The built-in WP_Query type renders its own items first, and for other types the output starts empty. Render the Looper’s Loop Item block once for each item, as GenerateBlocks Pro does.

Parameters: $output (string, the rendered items), $query_type (string), $query_data (array|object, the data you returned from generateblocks_query_data), $block (the Looper WP_Block), $attributes (array, the Looper’s attributes). Default: the rendered items for WP_Query, otherwise an empty string.

Each Loop Item is rendered with a WP_Block that gets the item as generateblocks/loopItem and its position as generateblocks/loopIndex.

add_filter( 'generateblocks_looper_render_loop_items', function( $output, $query_type, $query_data, $block, $attributes ) {
    if ( 'my_api' !== $query_type || ! is_array( $query_data ) ) {
        return $output;
    }

    $index = 1;

    foreach ( $query_data as $item ) {
        $output .= ( new WP_Block(
            $block->parsed_block['innerBlocks'][0],
            [
                'postType'                 => get_post_type(),
                'postId'                   => get_the_ID(),
                'generateblocks/queryType' => $query_type,
                'generateblocks/loopIndex' => $index,
                'generateblocks/loopItem'  => $item,
            ]
        ) )->render( [ 'dynamic' => false ] );

        $index++;
    }

    return $output;
}, 10, 5 );

Inside the Loop Item, the GenerateBlocks Pro Loop Item dynamic tag reads from the item. For example {{loop_item key:title}} outputs the item’s title, and a fallback option gives a value to use when the key is missing.

Editor (JavaScript)

These are wp.hooks filters. Add them with wp.hooks.addFilter() in a script that loads in the block editor.

generateblocks.editor.query.queryTypes

GB Free

The generateblocks.editor.query.queryTypes filter adds query types to the Query type select of the Query block. The select only shows when there is more than one type.

Parameters: types (array of { label, value, help }), attributes (the Query block’s attributes). Default: one type, { label: 'Post Query', value: 'WP_Query', help: 'Standard WP_Query for posts and pages.' }.

wp.hooks.addFilter(
    'generateblocks.editor.query.queryTypes',
    'my-plugin/query-types',
    ( types ) => [
        ...types,
        { label: 'My API', value: 'my_api', help: 'Items from my API.' },
    ]
);

generateblocks.editor.query.query-parameters

GB Free

The generateblocks.editor.query.query-parameters filter changes the list of parameters people can add to a query with Add Parameter.

Parameters: parameters (array of parameter definitions). Each has an id, a type, a default, a label, a description and a group, and some have isSticky or isRepeatable. Default: the built-in parameters. The first two are post_type (a post type select, default [ 'post' ]) and posts_per_page (a number, default 10).

The built-in id values are author__in, author__not_in, date_query, offset, order, orderby, paged, post__in, post__not_in, post_parent__in, post_parent__not_in, post_status, post_type, posts_per_page, s, tax_query, which match the WP_Query argument names. The control type values are authorsSelect, dateQuery, excludeParent, excludePosts, includeParent, includePosts, multiSelect, number, postTypeSelect, select, taxonomySelect and text.

wp.hooks.addFilter(
    'generateblocks.editor.query.query-parameters',
    'my-plugin/query-parameters',
    ( parameters ) => parameters.filter( ( parameter ) => 'offset' !== parameter.id )
);

generateblocks.editor.query.inspectorControls

GB Free

The generateblocks.editor.query.inspectorControls filter adds controls to the Query block’s settings, after the built-in query controls.

Parameters: controls (null by default), props (object with queryType, attributes, setAttributes, queryState, setParameter, removeParameter, context and queryClient). Default: null.

const { createElement } = wp.element;

wp.hooks.addFilter(
    'generateblocks.editor.query.inspectorControls',
    'my-plugin/query-controls',
    ( controls, { queryType, attributes, setParameter } ) => {
        if ( 'my_api' !== queryType ) {
            return controls;
        }

        return createElement( 'p', null, 'Controls for My API.' );
    }
);

generateblocks.editor.looper.query

GB Free

The generateblocks.editor.looper.query filter supplies the items the Looper previews in the editor for a custom query type. It is only used when the type isn’t WP_Query.

Parameters: result (null by default), context (object with query (the Query block’s settings), queryType, context, props, useWpQuery and selectedBlock). Default: null. Return an object with data (an array of items), isResolvingData and hasResolvedData.

wp.hooks.addFilter(
    'generateblocks.editor.looper.query',
    'my-plugin/looper-query',
    ( result, { queryType } ) => {
        if ( 'my_api' !== queryType ) {
            return result;
        }

        return {
            data: [ { id: 1, title: 'Example item' } ],
            isResolvingData: false,
            hasResolvedData: true,
        };
    }
);

generateblocks.editor.looper.fallback.postId

GB Free

The generateblocks.editor.looper.fallback.postId filter sets the post ID the Looper uses in the editor when the query has no items to preview.

Parameters: postId (int), props (the Looper block’s props). Default: 0.

wp.hooks.addFilter(
    'generateblocks.editor.looper.fallback.postId',
    'my-plugin/looper-fallback-post-id',
    ( postId, props ) => postId
);

generateblocks.editor.looper.fallback.postType

GB Free

The generateblocks.editor.looper.fallback.postType filter sets the post type the Looper uses in the editor when the query has no items to preview.

Parameters: postType (string), props (the Looper block’s props). Default: post.

wp.hooks.addFilter(
    'generateblocks.editor.looper.fallback.postType',
    'my-plugin/looper-fallback-post-type',
    ( postType, props ) => 'page'
);

Jump to

The post query

generateblocks_query_wp_query_args

generateblocks_rest_get_wp_query_args

generateblocks_query_per_page_default

generateblocks_query_loop_editor_posts_cap

Custom query types

generateblocks_query_data

generateblocks_looper_render_loop_items

Editor (JavaScript)

generateblocks.editor.query.queryTypes

generateblocks.editor.query.query-parameters

generateblocks.editor.query.inspectorControls

generateblocks.editor.looper.query

generateblocks.editor.looper.fallback.postId

generateblocks.editor.looper.fallback.postType