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!

Leave a Reply

Your email address will not be published. Required fields are marked *

Take your custom blocks to the next level?

Check out Block Lab Pro and access power-user features like the Repeater field and more! 

Go Pro!

You have Successfully Subscribed!