How To Create Custom Blocks For WP Grid Builder

This tutorial shows how to register a custom block (not to be confused with a Gutenberg block) for use in WP Grid Builder‘s card builder using the wp_grid_builder/blocks filter and how to add it inside a card applied to a posts grid.

Example: ACF Image Block

We shall display the value of an Image-type custom field created using ACF in the card with the post’s featured image as the fallback. You can think of this as another way to achieve the same look (not the same HTML markup though) as this.

Step 1

With ACF installed and active, create a new field group having an image-type field with the name of say, card_image. Leave the Return Format at the default “Image Array”. Select your desired post type under the Location metabox.

Step 2

Edit your posts and select/upload card image for the posts for which you’d like to use images other than their featured images.

Step 3

Install and activate Code Snippets plugin.

Go to Snippets > Add New.

Title: Register ACF Image Block for WPGB

Code:

add_filter( 'wp_grid_builder/blocks', 'wpdd_register_acf_image_block', 10, 1 );
function wpdd_register_acf_image_block( $blocks ) {
	
	// 'acf_image_block' corresponds to the block slug.
	$blocks['acf_image_block'] = [
		'name' => __( 'ACF Image', 'text-domain' ),
		'render_callback' => 'wpdd_acf_image_block_render',
	];

	return $blocks;
	
}

// The render callback function allows to output content in cards.
function wpdd_acf_image_block_render() {

	// get current post, term, or user object
	$post = wpgb_get_post();

	// set image size
	// medium_large = 768×0 pixels (proportionally resized to fit inside dimensions)
	$size = 'medium_large';

	// if ACF is active, assign the current post's image field value to a variable
	if ( class_exists( 'ACF' ) ) {
		$image = get_field( 'card_image', $post->ID );
	}

	// if the ACF image is populated, assign the URL of the specified size else the featured image in the specified size to a variable
	$image_url = $image ? $image['sizes'][ $size ] : get_the_post_thumbnail_url( $post, $size );

	// print formatted string in the desired HTML markup
	printf( '<img src="%s" alt="%s" />', esc_url( $image_url ), esc_attr( $post->post_title ) );

}

where card_image is the image-type custom field associated with your desired post type (that you want to output in the grid).

You may have noticed in the code above that the WordPress template tags and ACF functions need $post or its property to be specified for them to work. This is not that convenient as we can’t freely use the standard template tags like get_the_title() for getting the post title.

Let’s assign the global $post variable, set up global post data, then use template tags and ACF function calls without worrying about specifying the post object and when done, restore the $post global.

The above code can be rewritten as:

add_filter( 'wp_grid_builder/blocks', 'wpdd_register_acf_image_block', 10, 1 );
function wpdd_register_acf_image_block( $blocks ) {
	
	// 'acf_image_block' corresponds to the block slug.
	$blocks['acf_image_block'] = [
		'name' => __( 'ACF Image', 'text-domain' ),
		'render_callback' => 'wpdd_acf_image_block_render',
	];

	return $blocks;
	
}

// The render callback function allows to output content in cards.
function wpdd_acf_image_block_render() {

	// access the global $post variable
	global $post;

	// get current post, term, or user object
	$post = wpgb_get_post();

	// sets up global post data
	setup_postdata( $post );

	// set image size
	// medium_large = 768×0 pixels (proportionally resized to fit inside dimensions)
	$size = 'medium_large';

	// if ACF is active, assign the current post's image field value to a variable
	if ( class_exists( 'ACF' ) ) {
		$image = get_field( 'card_image' );
	}

	// if the ACF image is populated, assign the URL of the specified size else the featured image in the specified size to a variable
	$image_url = $image ? $image['sizes'][ $size ] : get_the_post_thumbnail_url( get_the_ID(), $size );

	// print formatted string in the desired HTML markup
	printf( '<img src="%s" alt="%s" />', esc_url( $image_url ), esc_attr( get_the_title() ) );

	// restore the $post global to the current post in the main query
	wp_reset_postdata();

}

Set the snippet to run everywhere. Save changes and activate.

Step 4

Let’s import the Amber demo and work on a copy of it and show our custom block in place of its card media. You can of course use a blank card instead if you want.

Go to Gridbuilder > Dashboard > Import Content. Select Amber and click IMPORT DATA.

Go to All Cards and click on the duplicate icon on Amber.

Let’s leave the name of the new card as say, Amber-2.

Toggle Card Media to off.

Click on Blocks, scroll down to Custom Blocks and click ACF Image – the custom block we created earlier.

Go to All Grids and create a new grid named say, Posts Grid.

Select your post type(s) at CONTENT QUERY.

In my test site since I wanted the cards to be laid out (in the masonry layout) horizontally I toggled “Horizontal Order” on under GRID LAYOUT. Also changed grid responsive settings like this:

At CARD STYLES select Amber-2 as the default card.

Save changes.

Go back to the list of cards and copy the shortcode for showing this grid.

Ex.:

[wpgb_grid id="1"]

Step 5

For users of Oxygen: All images in Oxygen are surprisingly not responsive by default. Add this CSS at Manage > Stylesheets:

img {
  vertical-align: top;
  height: auto;
  max-width: 100%;
}

Step 6

Paste this shortcode wherever you want the grid to be shown.

Check the front end and you should see something like:

Step 7

Click on our custom block in the WPGB card builder, go to Appearance > Spacing and set top, left and right margins to -2em each and bottom margin to 2em so the image breaks out of its constraints and fills up the card without spacing.

References

https://docs.wpgridbuilder.com/resources/filter-blocks/

https://www.advancedcustomfields.com/resources/image/

https://philkurth.com.au/tips/a-function-for-temporarily-changing-the-wordpress-post-context/