DEV Community: Jack Lowrie

Building a WordPress Accordion Block, no Javascript Required

Jack Lowrie — Thu, 11 Feb 2021 15:53:06 +0000

In this post we’ll go over how to build a Bootstrap accordion as a WordPress block using Advanced Custom Fields. This is a useful approach for rapidly building WordPress blocks. It’s also a great stopgap for developers who are still learning JavaScript, since it doesn't require you to write any JavaScript.

Just looking for the code? Check out the GitHub Repo:

jacklowrie / wp-accordion-block-tutorial

Child Theme for TwentyTwenty. Demo for making an accordion block in WordPress with Bootstrap and ACF Pro.

Quick Links

Prerequisites
Getting Started
Registering your first block
Setting up a Field Group
Rendering content in the template
Conclusion

Prerequisites (assumptions)

This tutorial assumes a basic understanding of how WordPress themes are structured. In particular, you should be familiar with what functions.php is in the context of a theme, the basics of how to use action hooks, and how templates work in WordPress Themes. If you’ve worked with child themes before or built a WordPress theme, you’ll likely be familiar with functions used in this tutorial. If you haven’t, we’ll cover how to set up a simple child theme.

ACF functions used in this tutorial

have_rows() and the_row()
This pair of functions is very similar to have_posts() and the_post() in the WordPress Loop, so if you’ve seen one pair, you’ll understand the other.
get_field() and get_sub_field()
The latter acts much the same as the former, only in the context of a repeater field.
acf_register_block_type()
We’ll cover how to use it. :)

Background knowledge of Bootstrap

Additionally, having a basic understanding of Bootstrap (what it is, why it’s useful as a "shortcut") will help. While we won’t use the Bootstrap grid, we will be implementing a version of the Bootstrap collapse component as well as the Bootstrap card component. You don’t need to have used these before to follow along, especially if you’ve used other Bootstrap components before.

Getting Started

To follow along, you’ll need a simple WordPress website that you can hack on. For simplicity, we’ll work inside a child theme. We’ll extend TwentyTwenty, a default theme which comes with every WordPress installation, though any theme will do. If you’re building just for yourself, this is adequate. If you’re building blocks you want to distribute, it’s better to keep them in a plugin. That way, switching themes won’t remove content from posts and pages.

Create your child theme

Begin by creating a new directory in the themes directory. The best practice would be to name it twentytwenty-child, but you can pick whatever name you’d like. Inside this directory, create a style.css file and add the following header:

/*
 Theme Name:   Twenty Twenty Child
 Author:       [your name]
 Template:     twentytwenty
*/

The most important part is to specify the template, which tells WordPress which theme is this one’s parent. You can add additional information, such as the theme version or a description, to your header as documented in the developer handbook. For reference, here’s the header from mine:

/*
 Theme Name:   Accordion Tutorial
 Description:  Twenty Twenty child theme for demoing a Bootstrap accordion block.
 Author:  Jack Lowrie
 Author URI: https://github.com/jacklowrie
 Template:  twentytwenty
 Version: 1.0.0
 License: GNU General Public License v2 or later
 License URI:  http://www.gnu.org/licenses/gpl-2.0.html
*/

Then, create a functions.php file, and add the following to it:

<?php

function enqueue_parent_styles() {
   wp_enqueue_style( 'parent-style', get_template_directory_uri().'/style.css' );
}
add_action( 'wp_enqueue_scripts', 'enqueue_parent_styles' );

This enqueues TwentyTwenty’s styles before ours, that way the changes we make will extend TwentyTwenty rather than replace them. And that’s it for now! You have a child theme ready to hack on.

Enqueue Bootstrap

Of course, we can’t build anything with Bootstrap without enqueueing it! To keep it simple, we’ll load it in from Bootstrap’s CDN. add the following to your theme’s functions.php file:

function enqueue_bootstrap() {
    wp_enqueue_style('bootstrap-styles', 'https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/css/bootstrap.min.css');
    wp_enqueue_style('bootstrap-styles', 'https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/css/bootstrap.min.css');
    wp_enqueue_script( 'bootstrap-scripts','https://cdn.jsdelivr.net/npm/bootstrap@4.5.3/dist/js/bootstrap.bundle.min.js', array( 'jquery' ), '', true );
}
add_action( 'wp_enqueue_scripts', 'enqueue_bootstrap' );

This code ensures that Bootstrap (and it’s dependencies) will load on your site.

Install Advanced Custom Fields Pro (ACF)

You’ll also need to have the Advanced Custom Fields plugin installed. While the core plugin is free and available in the WordPress Plugin Directory, it doesn’t give you all the capabilities and field types available with a Pro license. This tutorial makes use of the repeater field and the block-level field group, both of which require a pro license. ACF Pro is potent, and is worth the investment. Even if you don’t need to build custom blocks, you may find yourself reaching for it on more WordPress projects than not.

Registering your first block

Once you have a WordPress site (with Bootstrap styles and scripts enqueued and ACF Pro activated), you’re ready to start building blocks. The bird’s eye view for this is to create a template file for your block, then register it using ACF’s block registration function to ensure that the block is only registered if ACF is present on the site.

It’s helpful to keep all block templates in a folder to stay organized. Where you keep it is up to you, especially if you’re doing this in a theme and not a plugin — it may make sense to keep it as a top-level folder in the theme or to place it inside of a templates or template-parts folder if your theme has one. We’ll keep ours top-level for now. Create a new blocks folder in the root of your theme, then create a new template file called accordion.php inside. We don’t need to add anything to this file yet. It only needs to exist.

Then, we need to register that file (in functions.php, just like we enqueued Bootstrap).

function register_acf_block_types() {
     acf_register_block_type(array(
         'name'              => 'accordion',
         'title'             => __('Accordion'),
         'category'          => 'custom',
         'render_template'   => 'blocks/accordion.php',
     ));
 }
 add_action( 'acf/init', 'register_acf_block_types' );

You’re done! Sort of.

This is actually all there is to registering a block. If you add a block to a post or page now, the accordion will show up as an option. If you use it, any markup inside that template file will show up in the corresponding spot on the post or page. In fact, let’s do that! We can add the accordion example from the bootstrap collapse docs to a page as proof that we have a movable, renderable block (this is also an easy way to verify that we enqueued Bootstrap correctly).

Now, this isn’t a terribly useful block (it’s entirely uneditable, and we’re dependent on ACF to register the block even though we haven’t made any custom fields). But let’s not downplay the accomplishment!

FWIW, ACF’s register block function at its core is a php wrapper for WordPress’s Javascript function RegisterBlockType(), which is how we’d register the block if we didn’t use ACF. We are avoiding that since this post is about building blocks without Javascript.

Setting up a field group

Now that we have a block template, we need to set up fields to render in that block. We can set field groups to display only on specific blocks! From the Custom Fields menu in the WordPress Dashboard, add a new field group and call it Block - Accordion. It’s nice to keep all the field groups for blocks together in the list, though this is up to personal preference. Then add a location rule: “show this field group if block is equal to Accordion.

An accordion is a perfect candidate for a repeater field in ACF. Each new row in the repeater will correspond to a new ‘fold’ in the accordion, and all the folds will have the same subfields and layout.

So, add a repeater field and call it ‘folds’, then for simplicity of this demo, add a text field called ‘title’ and a WYSIWYG subfield called ‘content’. Now, if we add our accordion block to any page, we’ll be able to add as few or as many folds to the accordion as we’d like, and the content of each fold is customizable with a WYSIWYG editor!

We can save this data, and it will persist on the individual instance of the block, though we still need to render it in the template.

Rendering field content in the block template

Now, we can start to render each fold in the template. Each .card element in the example code we pasted in earlier makes up one fold. So first, let’s remove all but one ‘fold’, by deleting all the divs after the first card, taking care not to remove the closing tag for the accordion, and also remove all the placeholder content:

<div class="card">

  <div class="card-header" id="headingOne">
    <h2 class="mb-0">
      <button class="btn btn-link btn-block text-left" type="button" data-toggle="collapse" data-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne">

      </button>
    </h2>
  </div>

  <div id="collapseOne" class="collapse show" aria-labelledby="headingOne" data-parent="#accordionExample">
    <div class="card-body">

    </div>
  </div>

</div>

This is our fold template, which we can fill with the content from our block’s custom fields. Now, we can iterate over all the folds from the repeater and render them as a new .card. To do this, we’ll use two ACF functions, have_rows() and the_row(). These are used almost identically to have_posts() and the_post(), so if you’ve ever seen a WordPress loop, this might be a familiar pattern! Wrap our fold template in a while loop, then grab the fold content using get_sub_field():

// Loop through rows.
<?php 
while ( have_rows( 'folds' ) ) : the_row();
    $fold_title = get_sub_field( 'title' );
    $fold_content = get_sub_field( 'content' );
?>
  <div class="card">
    <div class="card-header" id="headingOne">
      <h2 class="mb-0">
        <button class="btn btn-link btn-block text-left" type="button" data-toggle="collapse" data-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
          <?php echo $fold_title; ?>
        </button>
      </h2>
    </div>

    <div id="collapseOne" class="collapse show" aria-labelledby="headingOne" data-parent="#accordionExample">
      <div class="card-body">
        <?php echo fold_content; ?>
      </div>
    </div>
  </div>
<?php endwhile; ?>

Our accordion is almost good to go! If we look at this on a page now, we’d see each fold we added to the block rendered, but the accordion wouldn’t behave the way we want. This is because the Bootstrap accordion counts on each fold having a unique id. In our code, every fold has an id of collapseOne. We can follow a similar convention using ACF’s get_row_index() function, which will tell us which iteration of the while loop we’re currently in (by telling us which row we’re currently rendering). We can also update the aria labels at the same time:

<?php 
while ( have_rows( 'folds' ) ) : the_row();
    $fold_title = get_sub_field( 'title' );
    $fold_content = get_sub_field( 'content' );
?>
<div class="card">

  <div class="card-header" id="heading-<?php echo get_row_index(); ?>">
    <h2 class="mb-0">
      <button class="btn btn-link btn-block text-left" type="button" data-toggle="collapse" data-target="#collapse-<?php echo get_row_index(); ?>" aria-expanded="true" aria-controls="collapse-<?php echo get_row_index(); ?>">
      <?php echo $fold_title; ?>
      </button>
    </h2>
  </div>

  <div id="collapse-<?php echo get_row_index(); ?>" class="collapse show" aria-labelledby="heading-<?php echo get_row_index(); ?>" data-parent="#accordionExample">
    <div class="card-body">
      <?php echo fold_content; ?>
    </div>
  </div>

</div>
<?php endwhile; ?>

Now, our accordion works! The last thing to do, since this is now a fully-functioning accordion and not just an example, is to update the id of the accordion (and the data-parent attribute of each fold) from #accordionExample to #accordion. Not technically necessary, but names matter!

That’s it!

We now have a fully functional accordion block. We can use this as a template to make other Bootstrap components as well, including Jumbotrons, Media Objects, List Groups, and more.

You can use the code from this tutorial as a template for creating other Bootstrap blocks for practice or to fit your needs. See the full code in my github repo:

jacklowrie / wp-accordion-block-tutorial

Child Theme for TwentyTwenty. Demo for making an accordion block in WordPress with Bootstrap and ACF Pro.

Have you tried building this or other Bootstrap components as WordPress blocks? How'd it go?

Building Gutenberg Blocks with Advanced Custom Fields (ACF) as a Stopgap

Jack Lowrie — Tue, 24 Nov 2020 14:23:12 +0000

WordPress is a fantastic way to start learning to code. You rarely need to learn more than one new thing at a time in order to get building, and you can always find one new skill to learn (or improve) with each new project.

But all that changed when ~~the fire nation attacked~~ the block editor was introduced. Gutenberg raised the barrier to entry for programming with WordPress, and created a sizable speedbump for faithful WordPress developers that had never needed JavaScript before.

This doesn’t have to kill momentum, or stop new developers from using WordPress as their ‘way in.’ There’s a workaround for building custom blocks that requires minimal JavaScript. It isn’t necessarily a long term solution (though you can build very polished websites with it). But it is an effective stopgap to keep (or start) building websites while developing the skills necessary to start building native WordPress blocks.

Using WordPress as a ladder for improvement

Looking at WordPress as a framework, it’s easy to see the appeal of using it to learn web development. It’s extremely well-documented, surrounded by an active and supportive community, and written in a way that allows you to ‘wade in’ slowly to the code without any prior knowledge. Before Gutenberg, a new developer’s journey with WordPress might look something like this:

After exploring how WordPress works as a CMS by configuring sites without code, they can slowly start introducing their own code. They can graduate from building sites using drag & drop themes/plugins to adding custom CSS rules via the customizer as they start to learn CSS.

From there, our new dev can learn about child themes and create their first stylesheet for more comprehensive style rules. Then, they can learn about WordPress’s template hierarchy and custom templates. As they do, they can dip into as much or as little HTML and PHP as they’re comfortable with, leaning on the framework as much as they need.

As their skills grow, they can begin building their own themes, and start adding custom functionality in functions.php. Once they can modify WordPress behavior in functions.php, it’s easy to start developing plugins: First, by moving that custom functionality from their theme into simple custom plugins to understand how plugins are structured, then by building larger more complex plugins, some of which can modify or expand WordPress’s core features.

At this point, our ‘new’ dev can drop the adjective. They have enough experience reading and writing code to make learning a language for a different framework easier. Their proficiency in HTML/CSS and PHP is also strong enough to experiment with lighter PHP frameworks like Laravel or Symfony. It also makes it possible to start learning more about routing and interacting with the database (which WordPress normally handles for us) – or – they can continue learning about routing and APIs etc by extending those features in WordPress via the WordPress REST API.

Because WordPress handles so much out of the box, you can isolate one language, grammar, skill or topic to learn or improve on at a time – whether that’s language-specific, or a higher-level concept, you rarely need to learn more than one new thing at a time in order to get building. You can grow with a ‘learn one new thing per project’ strategy for your entire career without leaving the WordPress ecosystem.

The challenge with Gutenberg

In the hypothetical roadmap above (it’s not so hypothetical, I’m on it 🙂 ), there’s one now-ubiquitous language that’s noticeably absent: JavaScript. Before WordPress 5.0, JavaScript was a nice-but-optional language for WordPress developers. You could go a long way on writing or modifying only a few lines of JavaScript per project, if you did so at all. You certainly didn’t need a build process or NPM to get by.

However, when Gutenberg replaced the Classic Editor, developers had to worry about rendering content both in the template and in the editor via React components. Content is still stored the same way in the database, but instead of knowing exactly where and in what order content is rendered, developers suddenly needed to worry about content appearing in any order. Crucially, they also needed to render them appropriately both on the frontend and in the editor.

If you’ve played with the WordPress block editor, you can consider the jump from Classic to Gutenberg by looking at the Classic Editor as a single unrendered block. Instead of having one ‘block’ being rendered only on the frontend with the Classic Editor, Gutenberg allowed multiple blocks to be rendered in any order, even nested, both on the front end and in the editor. There’s even a block that mimics the Classic Editor, to make it full circle.

This triggered a lot of panic, though in practice if you don’t need to make custom blocks, or only need to make simple blocks, it wouldn’t take long to learn enough JavaScript to get up to speed. Even if your block requires a little more than barebones, there are shortcut tools that can get you by while you learn the underlying code and tools. The problem is, without any significant JavaScript experience, the underlying code and tools can take a while to decrypt.

Furthermore, if you do need to make more involved blocks, or if you want to modify the built-in editor experience at all, then all of a sudden, you’d need HTML/CSS, some PHP, JavaScript, and to be familiar with how WordPress is structured as a framework, including how its REST API works!

ACF as a Stopgap

If you weren’t sold on the Advanced Custom Fields (ACF) plugin before, it really shines in the transition period between the Classic Editor and Gutenberg. Before Gutenberg, ACF was used to augment the Classic Editor, and let WordPress content creators manage content on more robust pages. While the free version was exceptionally powerful, the pro license was generally considered to be one of the best (and even most necessary) investments for a serious WordPress site.

Building blocks using the ACF plugin allows newer developers to sidestep using JavaScript, and continue building sites learning one thing at a time. This method is also particularly useful for WordPress developers used to building sites and admin interfaces ‘the old way’ with just PHP/HTML/CSS, who haven’t had the chance yet to learn JavaScript, deeply™. There simply is no better way to make a Gutenberg block without JavaScript.

Limitations to using ACF

The most obvious drawbacks are:

It introduces a dependency in every project
That dependency isn’t free

To use ACF with Gutenberg blocks, you need a pro license, making it harder to get away with the free version post WordPress 5.0. If you’ve been building WordPress sites with the Classic Editor and ACF pro previously, neither of these are significant changes. Furthermore, given this is a pretty major shortcut to building custom blocks, the return on investment for the pro license is substantial – even more so than it was before.

Additionally, this method also fails to take full advantage of Gutenberg, and arguably offers a worse editor experience, since the ACF UI remains largely unchanged. Though this is less attractive for brand new builds, it can be an advantage when updating a site that already uses ACF to use Gutenberg, since content creators are already familiar with that editing experience and can transition more easily.

Perhaps the biggest limitation of using ACF to build custom blocks is, instead of editing content directly as-styled like a native block, you make edits in an input field on the side menu and watch the change happen in real-time in the rendered preview block. For simple or small fields, this is almost as good as editing the preview directly. If you’re using more complex ACF fields like repeaters or field groups, then cramming those fields into the side menu doesn’t quite work.

ACF solves this by letting you edit blocks by ‘flipping’ them over to expose the ACF editor. When doing this, you can’t see how those changes would be rendered in real time (you’d have to keep flipping the block over to make tweaks).

This in no way limits the ability to create polished, high quality websites; the published page looks the same either way. However, having native blocks that can be edited directly sandwiched between ACF blocks that can only be edited in the side menu (or flipped) creates a clunky editor experience. This might seem a small concession given the benefits, however it still underscores using ACF to circumvent JavaScript as a temporary measure on the way towards full Gutenberg adoption.

Will ACF drive mass developer adoption of the Block Editor?

JavaScript becoming a core part of the WordPress stack threw a wrench in things for a lot of established WordPress developers and made WordPress a little less accessible for new developers. Using ACF to build custom blocks can counteract that for a little while, buying time for working WordPress devs to learn JavaScript. Ultimately, embracing JavaScript is a good thing. Its rate of adoption has made it too big to fail, and it is the future of the web – at a minimum, it’s the intended future of WordPress. But until we can download languages instantly and directly into our brains, this is a very effective stopgap.

In the next post, we’ll look at a practical example of how to build a custom Gutenberg block with ACF, no JavaScript required.

Supporting Time Ranges for Manually Built Nova Value Metrics in Laravel

Jack Lowrie — Mon, 06 Jul 2020 14:07:02 +0000

tl;dr

Manually built metrics in Nova don't support the time-range dropdown that the Nova helper functions support, and those helper functions don't handle many<->many relationships well (at least not the way I needed).

To get around this, you can use two protected functions from the parent Value class: currentRange() and previousRange(). Just don't forget to pass in the current admin's timezone!

Just looking for a code snippet? Jump to the end.

Quick Links

Background (What does the metric class look like?)
- Class Structure
- The Calculate Method
- Manually Building Results Values
Problem (Where I got stuck)
How I Solved: Looking Under the Hood (How I got unstuck)
My Workaround (my code)

Background

Metric cards in Nova can be produced rapidly, are straightforward to plan and explain, and provide high-impact 'quick wins' when using Nova to build out a dashboard for a Laravel application.

Class Structure

Value metrics generally consist of four methods: calculate(), ranges(), cacheFor(), and uriKey(). We're only concerned with the first two.

The ranges method ultimately populates the dropdown on the frontend. It returns an array of time ranges your metric will support and is pre-populated by Artisan. If you don't want to support ranges, you can remove this method; it's actually optional, and you can add/remove ranges from the returned array as you see fit.

The Calculate Method

Metrics are centered around that calculate method, which can frequently be a one-liner. The parent class for ranged metrics includes methods for the most frequent queries you'd want to make (count, sum, max, min, and average), so as long as you're creating a metric for an eloquent model -- say, users -- Nova (and Artisan) will do most of the work for you. The calculate method for metric measuring how your app is growing might look like this:

use App\User;

public function calculate(NovaRequest $request) {
    return $this->count( $request, User::class );
}

and would return the number of users your app has acquired (over a given range), along with a percent increase or decrease compared to the previous period. You can also further specify your query for users matching a particular set of rules (for example, if your users had an account_status, you could alter the return statement like so:

public function calculate(NovaRequest $request) {
    $this->count( $request, User::where('account_status', 'active'))
}

The metric looks pretty good on the frontend out of the box, too:

Note the range dropdown in the upper right; this is where the ranges() method comes in -- you can choose what options appear in that dropdown by setting them in that method (or, if you're happy with the default options that are pre-populated, don't worry about it!). The actual implementation of this feature seems to be Nova magic.

This is great for simple metrics like counting how many active users there are in your application, or counting the number of posts that were published, but what if you want to report on a metric that isn't covered by Nova helper functions?

Manually Building Results Values

Manually building results is equally straightforward at first glance. Nova metrics support manually building result values. It even supports including reporting previous result values, so long as you calculate them yourself:

public function calculate(NovaRequest $request) {
    $result = //some query
    $previous = //another query (optional)

    return $this->result($result)->previous($previous);
}

This works well for reporting a value in one time range, but when you build your results manually, you lose the ability to dynamically compare the metric across different time ranges (see the dropdown in the upper right of the screenshot above). What if you need that dropdown?

Problem

We needed to return a count of the records in the pivot table (in this case, we have a badges table and users, and need to report the total number of badges earned (by all users, over a time range).

Building that result manually is easy enough: We can use Laravel's database facade to count the records in the user_badges pivot table:

$result = DB::table('user_badges') ->count();

We can even compare to a previous value if we calculate it ourselves, but it won't connect to the ranges() method, so this only works if we hardcode a fixed time range. What about that dropdown?

I was unable to find anything in the documentation on how to handle ranges if building the result values manually, especially to support the dropdown that seems to be Nova magic for straightforward metrics. Fortunately, we can look at how Nova's metric helper functions are written for ideas. There is an answer in the source code!

Looking Under the Hood: How Nova implements Metrics classes

The metrics classes we generate with Artisan extend the abstract class Value. This class contains the helper methods you use for simple metrics. There isn't a whole lot happening in these helpers, however. They're all one-liners that call a protected method. It's that protected method, aggregate(), that's of interest to us:

protected function aggregate($request, $model, $function, $column = null, $dateColumn = null)
    {
        $query = $model instanceof Builder ? $model : (new $model)->newQuery();

        $column = $column ?? $query->getModel()->getQualifiedKeyName();

        $timezone = Nova::resolveUserTimezone($request) ?? $request->timezone;

        $previousValue = round(with(clone $query)->whereBetween(
            $dateColumn ?? $query->getModel()->getCreatedAtColumn(),
            $this->previousRange($request->range, $timezone)
        )->{$function}($column), $this->precision);

        return $this->result(
            round(with(clone $query)->whereBetween(
                $dateColumn ?? $query->getModel()->getCreatedAtColumn(),
                $this->currentRange($request->range, $timezone)
            )->{$function}($column), $this->precision)
        )->previous($previousValue);
    }

This method may look like a lot, but at a bird's eye view, it's doing something that's already documented, both in this post and in Nova's official docs - it's manually building a result and a previous value, and returning them! To do this, it's using two more protected helper methods: currentRange() and previousRange(). So when we manually build results in our metrics class, we're overriding these!

It follows that we can do the same in our class to support time ranges. However, that method takes two inputs, which we must remember to pass in ourselves: the timezone of the current user (conveniently calculated in the third line of the aggregate method above) and the time range (which even more conveniently is passed in as part of the request).

So, the strategy is to use these two helper functions to help manually build our result.

My Final Calculate Function

public function calculate(NovaRequest $request) {
  $timezone = Nova::resolveUserTimezone($request) ?? $request->timezone;

  $result = DB::table('user_badges')
      ->whereBetween( 'created_at', $this->currentRange($request->range, $timezone) )
      ->count();
  $previous = DB::table('user_badges')
      ->whereBetween( 'created_at', $this->previousRange($request->range, $timezone) )
      ->count();

  return $this->result($result)->previous($previous);
}

This approach, in combination with the built-in ranges() method, successfully counts the number of records in the pivot table that were created within the time range selected on the front end.