GiveWP 3.0 will use Gutenberg as a Foundation, Not Just a Block Builder

The Block Editor is Gutenberg, but Gutenberg is not the Block Editor. GiveWP 3.0 will be powered by the Gutenberg framework in a new and innovative way. Here’s what that means and why other plugin owners should pay attention.

Block Editor? Site Editor? Full-Site Editing? Gutenberg? All of these phrases have been used recently to describe the editing experience in the WordPress admin. But what is it exactly and what does that mean for plugin developers?

More specifically, when we say that GiveWP 3.0 will use “Gutenberg” what does that mean? Let’s dispel some myths and dig into why and how the Gutenberg code base has become a powerful development foundation that we’re excited to be building 3.0 on top of.

The Foundational Pieces of the Gutenberg Codebase

Currently, you can think of the Block Editor code base in terms of five main components:

  • Block List
  • Block Type List
  • Block List Tree
  • Block Editor Provider
  • Writing Flow

The Block List is the central component of the Gutenberg project – it is the container for the content area. Whether that represents a text document, an HTML document, or an abstract syntax tree of a dynamic application (more on this later), the Block List defines and manages the code structure of that content.

But the Block List alone doesn’t provide you with a visual editing experience. That’s where the Block Type List, the Block List Tree, and the Block Editor Provider come in. With these components combined the resulting application is a fully featured block editor.

The Block Type List is the registry of blocks that allows you to  drag-and-drop into the Block List. The ability to make the drag-and-drop user experience smooth and intuitive is technically quite challenging, which is one less challenge that we need consider.  Additionally, this component organizes the different block types into sections and provides search and filter functionality when inserting a new block.

The Block List Tree visualizes the hierarchy of blocks in the Block List. Blocks containing other blocks (known as Inner Blocks) are presented in the Block List as a part of the containing block. Whereas the Block List itself is one dimensional, in that it only shows the vertical order of the blocks,the Block List Tree introduces a horizontal order that visually communicates the hierarchy of the blocks. This is similar to a file folder system or an outline of a document.

The Block Editor Provider is a higher-order component, meaning that it provides additional functionality to another component in a way that is reusable. Essentially, the Block Editor Provider pulls together the Block List, Block Type List, and the Block List Tree into a shared context. This means that the Block List, the Block List Tree, and the Block Types List operate together using the same underlying blocks and block types.

Lastly, the Writing Flow is another higher-order component. It adds support for text selection across multiple blocks. While each section of content is a separate block, the Writing Flow provides a cohesive relationship between the pieces of content. This is important for a block editor that contains, largely, written content. When composing a blog post, each paragraph is a part of the overall narrative even though each is also a separate block. The Writing Flow component affirms this relationship.

Now that we understand the foundational components of how the Block Editor is put together, let’s talk about how we can dissect it and use only the pieces that we need for a unique and visual Donation Form builder experience.

Re-assembling the Pieces

Because the WordPress Block Editor is constructed of individual components, those pieces can be re-used to construct something different – something unique while still familiar. Like Lego pieces without the instructions the possibilities are limited only by the imagination of the creator.

Let’s take a specific code example. Below is what a common implementation of a block editor would look like, but for a different use-case.

Common block editor code implementation:

jsx

const BlockEditor = () => {
  return (
    <BlockTools>
      <WritingFlow>
        <ObserveTyping>
          <BlockList />
        </ObserveTyping>
      </WritingFlow>
    </BlockTools>
  );
};

In our case, the WritingFlow and the ObserveTyping higher-order components may not be necessary. These can be removed while keeping with the other components, like the BlockList.

jsx

const FormBlocksEditor = () => {
  return (
    <BlockTools>
      <BlockList />
    </BlockTools>
  );
};

This is still using the underlying components of the Block Editor, but in a new and unique way. Like Legos, we’ve taken only the pieces that we want and implemented them with something new.

How We Build a New Experience with the Block Editor in GiveWP 3.0

OK, now for the fun and exciting part: GiveWP 3.0!

Our “Next Generation” Visual Donation Form Builder is an example of constructing a unique, while familiar, editing experience within the context of WordPress. So we want to leverage the same components to provide the familiar user experience, but customize it specifically for a visual donation form building experience – not a page or content building experience.

The following is an example of arranging custom components in a familiar layout. Sections such as header, content, and sidebar can be configured with these custom components.

jsx

<Layout
  header={
    <HeaderContainer
      showSidebar={showSidebar}
      toggleShowSidebar={toggleShowSidebar}
    />
  }
  content={"design" === selectedTab ? <DesignPreview /> : <FormBlocks />}
  sidebar={
    !!showSidebar && (
      <Sidebar selectedTab={selectedTab} setSelectedTab={setSelectedTab} />
    )
  }
/>;

OK, now we’ve introduced how the Gutenberg codebase provides us with the flexibility to build something unique. What is it about the Next Generation Donation Form Builder that is different or unique and why are we doing it that way?

Storing Block Data with JSON Instead of HTML Comments

The biggest difference between the WordPress Block Editor and the Visual Donation Form Builder is how the block data is handled, stored, and processed.

The Block Editor uses an HTML markup with attributes encoded within HTML comments. This allows for easy rendering of static HTML content for publishing while also allowing for reconstructing block data for editing. When building HTML documents with the Block Editor this storage format has a lot of value, even if it has been controversial amongst the developer community.

But we want to control the markup and storage of our donation form content in whatever format and markup we want. Gutenberg is flexible enough to allow us to do that!

The Visual Donation Form Builder keeps with the underlying JSON of Gutenberg’s Block List but not the encoded HTML like the Block Editor. This JSON format is then parsed through the GiveWP Fields API to render the donation form on the front-end the way we want it structured.

Here’s a simple example of the JSON format for the “Who’s Giving Today?” section of a donation form:

json

[{
  "name": "give/section",
  "attributes": {
    "title": "Who's Giving Today?",
    "description": "We promise to protect your privacy.",
  },
  "innerBlocks": [
    {"name": "give/donor-name", "attributes": {...}},
    {"name": "give/donor-email", "attributes: {...}},
  ]
}]

We built the GiveWP Fields API specifically to enable this use-case. It is our own framework package which provides a fluent and composable syntax for creating, manipulating, and rendering form fields programmatically. This system is designed to add flexibility to how forms are built and extended and is part of the reason why the Visual Donation Form Builder keeps with the JSON representation of the blocks.

With these pieces in place, we can customize our forms very simply. Here’s a fun, simple example of what you can do with the NextGen Donation Form Builder with just a few lines of code:

php

// Create a new form from block data.
$form = Form::createFromBlocks($blockJSON);

// Move the donor email field before the donor name field.
$form->move('donor-email')->before('donor-name');

// Add a new textarea field to the end of the form.
$form->append(
  give_field('textarea', 'your-story')->label('Tell me your story')
);

Block Structure and Layout

While the WordPress Block Editor supports many different layout formats and blocks can be nested, donation forms generally follow a predictable structure.

In the case of GiveWP, the NextGen Form Builder enforces a Form > Section > Block hierarchy (blocks being fields and HTML elements like paragraphs and headings, etc), with flexibility afforded to the blocks within a section.

This structure is important to GiveWP donation forms because the layout is the responsibility of the form design. The sections of the form serve as the basic building blocks for the design, whether that be a top-down classic template, or a more complicated multi-step form.

The responsibility of layout being afforded to the donation form design allows for the re-use of the donation form fields in multiple contexts across a single website. For example, a basic donation form may be re-used as a modal during exit intent as well as a more permanent sidebar form. In this case the donation form may be the same, but the design’s contexts may vary largely.

Extensibility with Custom Fields

While the Gutenberg project provides a system for registering custom blocks, the needs of a custom field differ slightly and can benefit from different systems of re-use and composability. For example, most fields will require a shared subset of field options, such as label, description, and/or help text. For third-party developers, building at the block level would require framework specific knowledge that is required of the GiveWP development team. This developer experience can be improved with a new API specific to the task of custom fields.

Join the NextGen Form Builder Journey

We are building this new experience in public and you can join and follow along.

As a quick teaser, here’s an example of our progress on the “Design Tab”:

The NextGen Donation Form Builder showing how Design mode works.

If you want to join us on this journey, head to the project page and sign-up to get notified of our progress, get sneak peek previews, participate in polls, and you might even get discount codes and swag items too!

Join Our Journey

Help shape the next generation of WordPress donation forms

About the Author

Share this post

Join Our Newsletter

Get fundraising insights directly in your inbox. Plus a 15% discount off all plans.

  • This field is for validation purposes and should be left unchanged.

Copyright © 2024 Liquid Web, L.L.C.

GiveWP™ is a trademark of Liquid Web, L.L.C.

A Liquid Web Brand

© 2024 All Rights Reserved.