In The Lab: Building a Custom Form Block with Gravity Forms

One of the first things site builders realise when working with Gutenberg is that the other plugins they use don’t always play as nicely. Many plugins are adding Gutenberg support, which is great, yet the ones that are don’t always give us what we want. Because… well, we want what we want. Not what the average user does. We have unique needs. ❄️

So, in this tutorial, we’re going to show you how you can get what you want.

For this one we’re covering one of the most common needs of a website. Custom forms. There are some great form plugins out there. Free and premium. We’re going to show you how you can use your favourite form plugin and create a custom Gutenberg form block that works with it. Gravity Forms is the plugin of choice for this tutorial but the same process will work with nearly any of the others.

TL;DR. In your block template use the gravity_form() function. In your block add a text field so you can input your form ID.

Let’s do this!

Our block will look like this by the end, but the key thing to learn from this tutorial is how we make the block interact with the form.

The Final Block

Step 1: Creating our Form

For this step we’ll create our form using the Gravity Forms plugin. In our Gravity Forms settings (Forms > Settings), we’re going to turn off the CSS that the plugin outputs to the front end. This means when we write our own CSS it gives us full control over how the form will look.

Now to create our form, in the WordPress Admin go to Forms > Add New.


Call the new form “Contact”.

We’re going to add 3 fields and give each some placeholder text.

Field TypeField NameField Placeholder
TextNameYour Name
TextEmailYour Email
Paragraph TextMessageYour Message

Hit Publish and take note of the Form ID. In this example, the generated ID is 1.


Form = Done!

Step 2: Adding and Configuring the Block

Now we get to building our block.

  1. In the WordPress Admin, got to Block Lab > Add New
  2. Give your new block the title Form
  3. Keep the automatically generated slug.
  4. Choose an icon, set a category, and add some tags.

Step 2 complete. Nice!

Step 3: Adding Fields

Ok, these are the fields we’re going to add:

Field LabelField TypeField Location
Form TitleTextEditor
Form TextTextareaEditor
Form IDTextEditor

As far as fields go, that’s about as simple as it gets.

In the admin, it looks like this:

Add all these fields to your block and hit Publish.

Step 4: Building the Block Template

Time to open a text editor. I use VSCode.

In our Block Building screen in the WP Admin, you’ll see over on the right that the plugin is looking for the block template file for the new block. As we’ve only just added it, it’s telling us it can’t find it. Helpfully it’s also telling us exactly what it’s looking for.

Take note of the name block-form.php and open up your active theme files in your text editor.

Add a folder called blocks.

In this new folder, add a new file and type block-form.php as its file name. Hit save.

Switch back to our block editor in WP Admin and hit refresh just to make sure it’s picking up the new file.

Success!

Now, we build the template. We’re going to write some simple CSS, HTML, and PHP in our template file. There are other ways to do this, including building a preview template file for the block, but for simplicity’s sake we’re going to do it all in this single file.

We’ll have 2 sections in our file. CSS at the top, and HTML and PHP at the bottom.

Let’s stub out the HTML for our block. The structure will include:

  • A div to wrap around our form
  • a h2 for our form title
  • a p for our form text
  • a php tag for where we will call the form function
<div class="block-form">
    <h2 class="block-form_title"></h2>
    <p class="block-form_text"></p>
    <?php 

    ?>
</div>

I’ve also added CSS classes to each HTML element.

Next step is to add the content of our block using Block Lab’s block_field function.

Our block template file now looks like this.

<div class="block-form">
    <h2 class="block-form_title"><?php block_field( 'form-title' ); ?></h2>
    <p class="block-form_text"><?php block_field( 'form-text' ); ?></p>
    <?php 
         
    ?>
</div>

Now we get to the crux of this whole tutorial. We use the gravity_form() function made available to us with the Gravity Forms plugin, alongside our form-id field to output the form in our custom block.

Our code now looks like:

<div class="block-form">
    <h2 class="block-form_title"><?php block_field( 'form-title' ); ?></h2>
    <p class="block-form_text"><?php block_field( 'form-text' ); ?></p>
    <?php 
        $form_id = block_value( 'form-id' );
        gravity_form( $form_id , false, false, false, '', true, 12 ); 
    ?>
</div>

Using the block_value function we can fetch the ID of the form as input by the user when adding the block to a post or page and assign it to the variable $form_id

We then call the gravity_form() function and set a few parameters. For the from ID parameter, we use our $form_id variable.

The rest of the paramaters mean that the title and description will not be displayed, the form itself will not display if it is inactive, and it will not use AJAX for form submission.

To read more about this Gravity Forms function, or embedding forms in general, check out the official docs.

We now have a functioning custom form block that we can to add to a new post or page in WordPress and have it work in both the editor and frontend.

Let’s check it out.

In the WordPress admin, go to Pages > Add New. Now add a new block and look for our “Form” block. Add it to the page and fill in the fields.

In the editor with the block selected.

Click away from the block to view the preview.

In the editor with the block deselected.

And hit the Preview button at the top of the page to preview the form on the front end.

On the frontend.

We now have a fully functional form block.

Time to make it look good! Back in our template file, at the top, we’re going to write our custom CSS. Our styling looks like this:

<style>
    .block-form {
        padding: 60px;
        background-color: #5a3fd6;
        border-radius: 10px;
        box-shadow: 0px 4px 0px 0px rgba(0,0,0,0.5);
        text-align: center;
        color: #fff;
    }
    .block-form_title {
        color: #fff;
    }
    .block-form ul {
        list-style: none;
        margin-left: 0;
        padding-left: 0;
    }
    .block-form input,
    .block-form textarea {
        border-radius: 4px;
        border: none;
    }
    .block-form input[type="submit"] {
        min-width: 30%;
        background-color: #41b8ff;
        box-shadow: 0 3px rgba(38,30,65,.3);
        text-shadow: 1px 1px rgba(38,30,65,.1);
        font-size: 24px;
    }
    .block-form input[type="submit"]:hover {
        box-shadow: 0 10px rgba(38,30,65,.6);
    }
    .block-form label {
        font-size: 0;
        position: absolute;
    }
</style>

With this in the template file, our form on the front end looks like:

Our Final Form

And that’s it! With our styling complete we get a custom Gutenberg block that can display a Gravity form and look just the way we like. ?

So our final template file code is:


<style>
    .block-form {
        padding: 60px;
        background-color: #5a3fd6;
        border-radius: 10px;
        box-shadow: 0px 4px 0px 0px rgba(0,0,0,0.5);
        text-align: center;
        color: #fff;
    }
    .block-form_title {
        color: #fff;
    }
    .block-form ul {
        list-style: none;
        margin-left: 0;
        padding-left: 0;
    }
    .block-form input,
    .block-form textarea {
        border-radius: 4px;
        border: none;
    }
    .block-form input[type="submit"] {
        min-width: 30%;
        background-color: #41b8ff;
        box-shadow: 0 3px rgba(38,30,65,.3);
        text-shadow: 1px 1px rgba(38,30,65,.1);
        font-size: 24px;
    }
    .block-form input[type="submit"]:hover {
        box-shadow: 0 10px rgba(38,30,65,.6);
    }
    .block-form label {
        font-size: 0;
        position: absolute;
    }

</style>
<div class="block-form">
    <h2 class="block-form_title"><?php block_field( 'form-title' ); ?></h2>
    <p class="block-form_text"><?php block_field( 'form-text' ); ?></p>
    <?php 
        $form_id = block_value( 'form-id' );
        gravity_form($form_id , false, false, false, '', true, 12); 
    ?>
</div>

Pretty simple! 🙂

Note that the styling didn’t carry 100% over to the editor screen, even though we had it included in the template file. This was because some styling from the Gravity Forms plugin was given priority in the editor. To get around this we just needed to add some further specificity to our CSS.

I really hope you’ve found this tutorial interesting and helpful. If you have any ideas of what you’d like to see in future ones, please let me know in the comments below.

If you’d like to learn more, check out the previous tutorial on building a custom Hero Block.

Happy block building. ?

In The Lab: Building a Custom Hero Block

Today we kick-off an ongoing series of posts called “In The Lab“. These are going to be fun playground posts where we build cool things with Block Lab. 🙂

For the inaugural post of the series, we’re going to build a custom Hero Block. It’s going to be nice and simple and follow the typical design patterns you expect from the Hero section of a page. There will be a couple of extra controls that let you change the styling of the block, but nothing over-the-top.

To see an example of what this custom block will be able to do, here are 4 examples.

Example Hero Sections built with our Custom Block

So take note of some features of this custom block.

  1. Background Image
  2. Background Colour
  3. Heading & Text
  4. 2 x Buttons
  5. Left, Center, and Right alignment of the block content
  6. Different heading font sizes
  7. Light & Dark text

With this kind of block, it would make it pretty easy to beautify the first section of any of your pages.

So, before we get in to the step-by-step, here is our setup. Fresh WordPress install (v5.03). Block Lab plugin installed and active (v1.1.2). Atomic Blocks child theme installed and active.

We’re using the Atomic Blocks theme for 2 reasons.

  1. It’s great!
  2. It has a great blank “page builder” page template that works as a good blank canvas for working with a Hero kind of block.

Ok, let’s do this! By the end of this tutorial, this is what we will have built.

The Custom Hero Block we are building

Step 1: Adding and Configuring the Block

  1. In the WordPress Admin, got to Block Lab > Add New
  2. Give your new block the title Hero
  3. Keep the automatically generated slug.
  4. Choose an icon, set a category, and add some tags.

Step 1 complete. Nice!

Custom Block Properties

Step 2: Adding Fields

Ok, these are the fields we’re going to add.

Field LabelField TypeField Location
HeadingTextEditor
TextTextareaEditor
Button 1 TextTextEditor
Button 1 URLURLEditor
Button 2 TextTextEditor
Button 2 URLURLEditor
Background ColorColorEditor
Background ImageTextEditor
Background DarkenRangeInspector
Text ColorSelectInspector
Heading SizeRangeInspector
OrientationSelectInspector

In the admin, they will look like this:

Fields for our Custom Hero Block
Admin screenshot of added fields

Take note of the field locations. Rule-of-thumb is that content fields belong in the editor and settings/configuration fields belong in the inspector.

For our background image field, we’re using a Text field. A Media field is coming to the plugin very soon, which would actually be used here. In the meantime, we just paste an image’s URL in to a Text field.

Add all these fields to your block, and hit Publish.

Step 3: Building the Block Template

Time to open a text editor. I use VSCode, but there are plenty you can choose from.

In our Block Building screen in the WP Admin, you’ll see over on the right that the plugin is looking for the block template file for your new block. As we’ve only just added it, it’s telling us it can’t find it. Helpfully it’s also telling us exactly what it’s looking for.

Copy the file name block-hero.php and open up your active child theme files in your text editor.

Add a folder called blocks.

In this new folder, add a new file and paste in block-hero.php as its file name. Hit save.

Switch back to our block editor in WP Admin and hit refresh just to make sure it’s picking up the new file.

Success!

Custom Block Template Notice

Now, we build the template. We’re going to write some simple CSS, HTML, and PHP in our template file. There are other ways to do this, including building a preview template file for the block, but for simplicity’s sake we’re going to do it all in this single file.

We’ll have 2 sections in our file. CSS at the top, and HTML and PHP at the bottom.

Let’s stub out the HTML for our block. The structure will include

  • a section to wrap the whole block
  • a div to use as our background darkening overlay
  • a container div to contain our content within the max content width of the site
  • a wrapper div to position the content of the block
  • and our Hero content
<section class="block-hero">
    <div class="block-hero_background-darken">
        <div class="block-hero_container">
            <div class="block-hero_wrapper">
                <h1 class="block-hero_heading"></h1>
                <p class="block-hero_text"></p>
                <div>
                    <a class="block-hero_button-1"></a>
                    <a class="block-hero_button-2"></a>
                </div>
            </div>
        </div>   
    </div>
</section>

I’ve also added CSS classes to each HTML element.

Next step is to add the content of our block using Block Lab’s available functions. With the block_field and block_value functions we’re going to add our content and base styling fields first and then work with the setting fields (ones we added to the inspector) later.

Our block template file now looks like this.

<section class="block-hero">
    <div class="block-hero_background-darken">
        <div class="block-hero_container">
            <div class="block-hero_wrapper">
                <h1 class="block-hero_heading"><?php block_field( 'heading'); ?></h1>
                <p class="block-hero_text"><?php block_field( 'text'); ?></p>
                <div>
                    <a class="block-hero_button-1" href="<?php block_field( 'button-1-url'); ?>"><?php block_field( 'button-1-text'); ?></a>
                    <a class="block-hero_button-2" href="<?php block_field( 'button-2-url'); ?>"><?php block_field( 'button-2-text'); ?></a>
                </div>
            </div>
        </div>   
    </div>
</section>

By using the block_field function, we echo out the value stored in the database in that particular field.

Let’s take a quick stock-take of what we have. We should now actually be able to add our custom block in a new post or page in WordPress, add in content, and have it work in both the editor and frontend.

So, in the WordPress admin, go to Pages > Add New. Now add a new block and look for our “Hero” block. Add it to the page and fill in the fields.

Custom Hero Block Fields and their Values

Now click away from the block to see the preview in the editor.

Custom Hero Block in the Gutenberg Editor

And then click the preview button to view on the front end.

Custom Hero Block on the frontend

Hey presto. We have a functioning custom block. Now to make it pretty and customisable.

We’re going to add our CSS to the block template itself to keep it simple. Alternate and more DRY ways include adding it to a plugin or a centralised stylesheet.

So our CSS looks like this:

<style>
    .block-hero {
        background-size: cover;
    }
    .block-hero_container {
        max-width: 1080px;
        margin: auto;
        display: flex;
        min-height: 90vh;
        align-items: center;
        justify-content: space-between;
        padding: 40px 20px;
    }
    .block-hero_wrapper { 
        max-width: 600px;
    }
    .block-hero_heading { 
        color: #fff;
    }
    .block-hero_text { 
        color: #fff;
        margin-bottom: 40px;
    }
    .block-hero_button-1,
    .block-hero_button-2 {
        display: inline-block;
        padding: 8px 24px;
        border-radius: 0;
        border: solid #fff 2px;
        background-color: transparent;
        color: #fff;
        font-size: 14px;
        text-transform: uppercase;
        letter-spacing: 1px;
        margin-bottom: 10px
    }
    .block-hero_button-1 {
        margin-right: 10px;
        background-color: #fff;
        color: inherit;
    }
</style>

Our CSS is fairly simple. It’s mostly about giving the Hero section the proper amount of space and alignment on the page. The buttons also get a bit of attention to make sure they actually look like buttons (we’re using anchor tags) and work well against the background images or colour.

Additionally we’re going to add some in-line CSS to section.block-hero to pull in the background image and background color. So that particular line now looks like

<section class="block-hero" style="background-image: url('<?php block_field( 'background-image'); ?>'); background-color: <?php block_field( 'background-color' ) ?>;">

With this styling, we have basically completed the block! With the image added to the background field, this is what we see.

Our Custom Hero Block

This here is looking really good. We could finish right here if we wanted.

However, let’s add some block settings that let the user tweak the block to make it better suit their case-by-case needs.

So the block fields we added earlier that will handle the settings are:

  • background-darken – This lets the user darken the background image to improve contrast with overlaid text
  • heading-size – This lets the user increase the text-size of the heading
  • text-color – This lets the user select between light and dark text based on the image or color they have in the backgroun
  • orientation – This lets the user select between left, right, and center orientations for the block content

We will be writing some basic PHP to handle these. Our code looks like:

<?php
    $background_alpha = block_value( 'background-darken') / 100;
    $heading_size = block_value( 'heading-size') / 10 + 2;
    $orientation = block_value( 'orientation' );
    $text_color = block_value( 'text-color' );

    if ( $text_color == 'dark' ) {
        $font_color = '#272c30';
    } else {
        $font_color = "#fff";

    }
    if ( $orientation == 'left' ) {
        $justify_content = 'flex-start';
    } elseif ( $orientation == 'center' ) {
        $justify_content = 'center';
    } else {
        $justify_content = 'flex-end';
    }
?>

So depending on the values input in to our block in the editor, we are given different values we use within our CSS. Our updated HTML/PHP part of the template now looks like:

<section class="block-hero" style="background-image: url('<?php block_field( 'background-image'); ?>'); background-color: <?php block_field( 'background-color' ) ?>;">
    <div class="block-hero_background-darken" style="background-color: rgba(0,0,0, <?php echo $background_alpha ?>);">
        <div class="block-hero_container" style="justify-content: <?php echo $justify_content; ?>">
            <div class="block-hero_wrapper" style="text-align:<?php echo $orientation; ?>">
                <h1 class="block-hero_heading" style="font-size: <?php echo $heading_size; ?>em; color:<?php echo $font_color; ?>"><?php block_field( 'heading');?></h1>
                <p class="block-hero_text" style="color:<?php echo $font_color; ?>"><?php block_field( 'text'); ?></p>
                <div>
                    <a class="block-hero_button-1" href="<?php block_field( 'button-1-url'); ?>"><?php block_field( 'button-1-text'); ?></a>
                    <a class="block-hero_button-2" style="color:<?php echo $font_color; ?>" href="<?php block_field( 'button-2-url'); ?>"><?php block_field( 'button-2-text'); ?></a>
                </div>
            </div>
        </div>   
    </div>
</section>

With this in place, we can go to our page and edit the block. For our cycling block, we will

  • Darken the background slightly
  • Switch the text colour to light
  • Increase the heading size a bit
  • Set the orientation to center

And now, without further ado. Here is our block.

Our Custom Hero Block with Settings

And with just changing the content and tweaking the settings, you can create more hero sections on any page or post as diverse as these. 🙂

Our final template file, with all our styling and templating looks like:

<style>
    .block-hero {
        background-size: cover;
    }
    .block-hero_container {
        max-width: 1080px;
        margin: auto;
        display: flex;
        min-height: 90vh;
        align-items: center;
        justify-content: space-between;
        padding: 40px 20px;
    }
    .block-hero_wrapper { 
        max-width: 600px;
    }
    .block-hero_heading { 
        color: #fff;
    }
    .block-hero_heading:after { 
        color: #fff;
    }
    .block-hero_text { 
        color: #fff;
        margin-bottom: 40px;
    }
    .block-hero_button-1,
    .block-hero_button-2 {
        display: inline-block;
        background-color: #fff;
        padding: 8px 24px;
        border-radius: 3px;
        color: #333;
        border-radius: 0;
        border: solid #fff 2px;
        background-color: transparent;
        color: #fff;
        font-size: 14px;
        text-transform: uppercase;
        letter-spacing: 1px;
        margin-bottom: 10px
    }
    .block-hero_button-1 {
        margin-right: 10px;
        background-color: #fff;
        color: inherit;
    }
</style>
<?php
    $background_alpha = block_value( 'background-darken') / 100;
    $heading_size = block_value( 'heading-size') / 10 + 2;
    $orientation = block_value( 'orientation' );
    $text_color = block_value( 'text-color' );

    if ( $text_color == 'dark' ) {
        $font_color = '#272c30';
    } else {
        $font_color = "#fff";

    }
    if ( $orientation == 'left' ) {
        $justify_content = 'flex-start';
    } elseif ( $orientation == 'center' ) {
        $justify_content = 'center';
    } else {
        $justify_content = 'flex-end';
    }
?>
<section class="block-hero" style="background-image: url('<?php block_field( 'background-image'); ?>'); background-color: <?php block_field( 'background-color' ) ?>;">
    <div class="block-hero_background-darken" style="background-color: rgba(0,0,0, <?php echo $background_alpha ?>);">
        <div class="block-hero_container" style="justify-content: <?php echo $justify_content; ?>">
            <div class="block-hero_wrapper" style="text-align:<?php echo $orientation; ?>">
                <h1 class="block-hero_heading" style="font-size: <?php echo $heading_size; ?>em; color:<?php echo $font_color; ?>"><?php block_field( 'heading');?></h1>
                <p class="block-hero_text" style="color:<?php echo $font_color; ?>"><?php block_field( 'text'); ?></p>
                <div>
                    <a class="block-hero_button-1" href="<?php block_field( 'button-1-url'); ?>"><?php block_field( 'button-1-text'); ?></a>
                    <a class="block-hero_button-2" style="color:<?php echo $font_color; ?>" href="<?php block_field( 'button-2-url'); ?>"><?php block_field( 'button-2-text'); ?></a>
                </div>
            </div>
        </div>   
    </div>
</section>

I really hope you’ve found this tutorial interesting and helpful. If you have any ideas of what you’d like to see in future ones, please let me know in the comments below.

Happy block building. 🙂

Where it all began

Back in early 2018 I was working on a website and recognised that it was about time I started taking Gutenberg seriously. I needed to move away from the page templates I was using to offer some of the more complex layouts of the site.

Now I’m not an amazing WordPress developer, but … I get by. However, when I went to look at building custom blocks in Gutenberg, I very quickly found myself out of my depth.

I work with some pretty amazing WordPress engineers, a number who have contributed in significant ways to WordPress Core and other projects in the space, so I messaged a couple of them and asked if I could have a bit of dummies intro to building custom blocks. A couple of them, looking into it for the first time, came back and said that they could certainly help but were surprised by how complex it was and that I was going to have to seriously level-up my dev skills. Levelling-up sounded great, but I put it on the shelf for a little while as I didn’t have the time to invest right then.

Fast forward to WordCamp Sydney in July and Luke (co-conspirator here at Block Lab) was giving the keynote presentation and talked the audience through Gutenberg. The talk was great and everyone loved it. During Q&A time at the end, someone piped up and said…

“Wouldn’t it be great if there was an Advanced Custom Fields like solution geared towards building Custom Blocks.”

Bloke in the crowd

Huh… Yeah, that would be great. It would certainly help me personally with my custom block needs. And if I need it, chances are lots of other people would as well.

The next day Luke and I talked it over and decided we were going to build it.

The next day we called our friend Rheinard and asked if he wanted to help out.

The next week we built out a prototype.

With some really really cool feedback from peers and friends in the WordPress community we decided we were going to do a proper good job of this. 2 months on and we released v1.0 of Block Lab to the WordPress plugin repo.

Since then we’ve added new features and received some pretty cool kudos from the community including a mention from Matt Mullenweg in his 2018 State of the Word at WordCamp US in Nashville.

We’ve got some solid plans for Block Lab and are excited about being the solution for all those people like me back in early 2018 who just “wanted a custom block to do X”, but didn’t know where to start.

Save 75% on the Unlimited Sites License

Buy an Early Access Pass for Block Pro and save 75% on the annual license for unlimited sites.

 

Check it out!

You have Successfully Subscribed!