In the Lab: A Custom eBook Download Block

Welcome back to the Lab.

For this tutorial we’re going to build a custom eBook download/call-to-action block. It will include a picture of our book, some text, and a button to download the book.

It’s gonna look something like this:

So our local setup for building the block looks like this:

  • Theme: Atomic Blocks Child Theme
  • Plugins: Block Lab

That’s it. Nice and simple. Let’s do this!

Looking at our design above we can figure out the block fields we’re going to need and where we want them to be. Each field basically corresponds to a unique element in the block. So they are:

Field LabelField TypeField Location
Book ImageImageEditor
PretextTextEditor
HeadingTextEditor
TextTextareaEditor
Button TextTextEditor
Button URLURLEditor
Accent ColorColorInspector

Most of these are pretty self-explanatory. The final field Accent Coloris something a little extra. In our design we have that bold blue, but we’re going to make that configurable (apart from the actual image of the book that is). We’re going to let the person adding the block choose an “accent” color that will be used for the button and the little pretext on the right.

So in our WordPress Admin and with the Block Lab plugin active, we go to Block Lab > New Block.

Give our new block a title and configure the basic block settings. This is what we have:

Now let’s add all our fields as per our table above.

Hit Publish.

You’ll notice that when you hit publish that over on the right a notification appears telling us that the plugin is looking for a template file. Currently it’s unable to find it and is letting us know.

So let’s open up our text editor of choice and create the file. In our child theme, in the top level folder, we’re going to add a new folder called blocks. In this folder we’re going to create a file called block-ebook-cta.php. Notice that the notification lets us know what the file needs to be called.

With this file saved we can go back to our Block Editor in WordPress, hit refresh, and we’ll see that our new template file is being picked up now.

Great, so our template file is all set up. Now let’s build it out.

Let’s first stub out our HTML and give the elements CSS classes.

<section class="alignwide block-ebook-cta">
    <div class="block-ebook-cta--wrapper">
        <div>
            <img class="block-ebook-cta--book-image" src="">
        </div>
        <div>
            <span class="block-ebook-cta--pretext"></span>
            <h2 class="block-ebook-cta--heading"></h2>
            <p class="block-ebook-cta--text"></p>
            <a class="block-ebook-cta--button" href=""></a>
        </div>
    </div>
</section>

Next let’s use the two PHP functions that Block Lab gives us for interacting with our custom block and its fields. These functions are:

  • block_value()
  • block_field()

block_value stores the data saved to the field. block_field echos the data out. So with these functions available to us, our template file looks like:

<section class="alignwide block-ebook-cta">
    <div class="block-ebook-cta--wrapper">
        <div>
            <img class="block-ebook-cta--book-image" src="<?php esc_html( block_field( 'book-image' ) ); ?>" alt="">
        </div>
        <div>
            <span class="block-ebook-cta--pretext"><?php esc_html( block_field( 'pretext' ) ); ?></span>
            <h2 class="block-ebook-cta--heading"><?php esc_html( block_field( 'heading' ) ); ?></h2>
            <p class="block-ebook-cta--text"><?php esc_html( block_field( 'text' ) ); ?></p>
            <a class="block-ebook-cta--button" href="<?php esc_html( block_field( 'button-url' ) ); ?>"><?php esc_html( block_field( 'button-text' ) ); ?></a>
        </div>
    </div>
</section>

Note that we are sanitising our function outputs with esc_html. This follows WordPress coding best practices. You can learn more about that here.

We can actually now use this block. If you create a new page or post in WordPress, you’ll be able to add this block. All the fields are there and the saved data is being output. It will look like this in the editor and the frontend:

Before we move on to styling, we’re going to create a variable that can store the accent-color. We can then interact with this variable when styling.

Our variable PHP looks like this:

<?php
$accent_color = block_value( 'accent-color' );
?>

Note that when we added the Accent Color field to the block in the Block Editor, we gave it a default color so that the variable will always have a saved value.

For our CSS styling we’re going use a new feature of Block Lab. In version 1.2.1 we introduced a better way to manage styling. In our blocks folder we’re going to add a CSS file called block-ebook-cta.css. The plugin will auto-magically pair this file with the PHP file of the same name.

So in this CSS file we’re going to add the following:

.block-ebook-cta {
        margin-top: 40px;
        margin-bottom: 40px;
    }
    .block-ebook-cta--wrapper {
        display: grid;
        grid-template-columns: 1fr 1fr;
        grid-gap: 40px;
    }
    .block-ebook-cta--wrapper>div:nth-child(1) {
        background-color: #f4f4f4;
        padding: 80px;
    }
    .block-ebook-cta--wrapper>div:nth-child(2) {
        display: flex;
        align-items: flex-start;
        justify-content: center;
        flex-direction: column;
        max-width: 460px;
        padding: 40px;
    }
    .block-ebook-cta--book-image {
        /* border: 8px solid #fff; */
        max-width: 80%;
        margin: auto;
        /* margin-top: -40px;
        margin-bottom: -80px; */
        box-shadow: 1px 10px 40px 0px rgba(0,0,0,0.28);
    }
    .block-ebook-cta--pretext {
        text-transform: uppercase;
        font-size: 14px;
        line-height: 1em;
        letter-spacing: 1px;
        font-weight: 800;
        margin-bottom: 20px;
    }
    .block-ebook-cta--heading {
        font-weight: 800;
        margin-bottom: 40px;
    }
    .block-ebook-cta--text {
        font-size: 16px;
        margin-left: 20px;
    }
    .block-ebook-cta--button {
        display: inline-block;
        color: #fff;
        padding: 24px 24px;
        text-transform: uppercase;
        font-size: 12px;
        line-height: 1em;
        letter-spacing: 1px;
        font-weight: 800;
        margin-left: 20px;
        box-shadow: 1px 10px 40px 0px rgba(0,0,0,0.28);
    }
    .block-ebook-cta--button:hover {
        box-shadow: 1px 10px 40px 0px rgba(0,0,0,0.4);
        color: #fff;
    }

This gets us 99% of the way. The final piece of CSS is actually going to sit in the PHP template file. The reason for this is that we want it to interact with our stored accent_color variable. So down a the bottom of the block-ebook-cta.php file we’re going to add:

<style>
    .block-ebook-cta--button {
        background-color: <?php echo esc_html( $accent_color ); ?>;
    }
    .block-ebook-cta--pretext {
        color: <?php echo esc_html( $accent_color ); ?>;
    }
 </style>

And that is the final piece of this puzzle. Let’s go create a new Page in WordPress, add our block, fill out the fields and see what it looks like. To change it up, let’s set the accent color to purple.

Nice!

So to take this even further you could:

  • Add other button options. E.g. text color
  • Add CSS to handle the blocks responsiveness for smaller screens

I hope you like this one. I’m pretty happy with how it turned out. 😀

If you want to learn more, check out this previous tutorials:

  • Custom Hero Block
  • Custom Gravity Form Block
  • Custom Pricing Table Block

Happy block building!

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. ?

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!