Add a Custom Block to Your Website Content

After creating a custom block using the Block Builder, the next step is to create a block template so it can be properly displayed on your website. 

You can do this using the built-in Template Editor, but if you prefer, you can create the template manually using the PHP templating method.

In this article, we’ll show you how to use the PHP templating method to create an associated HTML template (or a block template) that includes the field data required for displaying the custom block.

Table of Contents:

• Understanding the basics
  • Template organization
• Creating and storing the template (required)
  • Step 1: Add a new directory and the required PHP file
  • Step 2: Build the PHP template
    • Add a wrapper to support CSS classes (optional)
• Creating block previews (optional)
• Overriding the template path

---

Understanding the basics

A block template must be stored inside a directory named blocks and placed within the active theme’s directory. Also, the block’s slug (which is determined in the custom block’s properties) should be used. The correct formats to use are: 

• {theme directory}/blocks/{block slug}/block.php …or
• {theme directory}/blocks/block-{block-slug}.php

For example, if your block’s slug is testimonial, Genesis Custom Blocks will look for a block template in your theme in these locations: 

• {theme directory}/blocks/testimonial/block.php
• {theme directory}/blocks/block-testimonial.php

Genesis Custom Blocks first checks to see if the template exists in the child theme. If it’s not, it checks to see if it exists in the parent theme.

Template Organization

Genesis Custom Blocks supports the following directory structure for blocks:

• /theme
  • /blocks
    • /block_one
      • preview.php
      • block.php
      • block.css
    • /block_two
      • preview.php
      • block.php
      • block.css

Note: Genesis Custom Blocks does NOT auto-enqueue JavaScript files.

Also, block templates are expected to load in the following order:

Editor templates:
These templates are only loaded in the editor.

1. blocks/{name}/preview.php
2. blocks/preview-{name}.php
3. blocks/preview.php

Frontend templates: 
These templates are loaded both in the editor and on the frontend of your website.

1. blocks/{name}/block.php
2. blocks/block-{name}.php
3. blocks/block.php

Creating and storing the template (required)

Now it’s time to add and build the block template. Follow the steps below.  

Step 1: Add a new directory and the required PHP file

Using your favorite code editor, open the active theme’s files and add the following 2 items to it:

1. a new folder named blocks.
2. a blank PHP file named block-{block-slug}.php and place it inside the new blocks folder. Be sure to change block-slug to the name of your block.

Step 2: Build the PHP template

Now that the template is recognized by the plugin, you can build the template using HTML and any necessary PHP functions from the Genesis Custom Blocks plugin.

In the example below, we’ve created a simple template for a custom testimonial block and added the following HTML and PHP:

<img src="<?php block_field( 'profile-picture' ); ?>" alt="<?php block_field( 'author-name' ); ?>" />
<h3><?php block_field( 'author-name' ); ?></h3>
<p><?php block_field( 'testimonial' ); ?></p>

We used the block_field function to interact with the fields that we added when creating the custom block in the WordPress admin.

Add a wrapper to support CSS classes (optional)

When building the template, we recommend including a wrapper in your template to support the Additional CSS Class(es) field that’s built into WordPress core (shown in the image below).

For example:

<div class="genesis-custom-block <?php block_field('className'); ?>">
...
</div>

Click image to enlarge

Creating block previews (optional)

Sometimes a block’s template markup will be too detailed to be properly previewed in the editor. 

In this case, you may create a preview template. This will be used instead of the block template while previewing the block in the WordPress editor. 

Preview templates should be saved in your theme as follows:

{theme directory}/block/preview-{block slug}.php

Preview template example

A preview template for a custom testimonial block would be saved in the following file:

{theme directory}/blocks/preview-testimonial.php

We want our preview to look similar, but maybe we’ll remove the profile picture to make some extra space. The preview template code would look similar to this:

<h3><?php block_field( 'author-name' ); ?></h3>
<p><?php block_field( 'testimonial' ); ?></p>

Overriding the template path

It is possible to change the template path so that it uses a custom template, outside of the theme or blocks directory.

To use a different template inside your theme, use the genesis_custom_blocks_override_theme_template( $theme_template ) filter. 

To use a different template outside your theme (for example, in a plugin), use the genesis_custom_blocks_template_path( $template_path ) filter.

Read more about using filters on WordPress.org.