The API Design: Keep it Simple

When deciding the API for your block, you should follow the WordPress philosophy “Decisions, not Options.” The following is selected excerpts that I believe are key guiding principles to designing your block’s API.

Out of the box

Great software should work with little configuration and setup. WordPress is designed to get you up and running and fully functional in no longer than five minutes. You shouldn’t have to battle to use the standard functionality of WordPress.

Design for the majority

Many end users of WordPress are non-technically minded. They don’t know what AJAX is, nor do they care about which version of PHP they are using. The average WordPress user simply wants to be able to write without problems or interruption. These are the users that we design the software for as they are ultimately the ones who are going to spend the most time using it for what it was built for.

Decisions, not options

When making decisions these are the users we consider first. A great example of this consideration is software options. Every time you give a user an option, you are asking them to make a decision. When a user doesn’t care or understand the option this ultimately leads to frustration. As developers we sometimes feel that providing options for everything is a good thing, you can never have too many choices, right? Ultimately these choices end up being technical ones, choices that the average end user has no interest in. It’s our duty as developers to make smart design decisions and avoid putting the weight of technical choices on our end users.

Simply put, blocks should feel like magic. Design your tools to make it so that things “just work” and content teams can easily focus on the content.

The WordPress Components

The components package, as the introductory page states, includes a library of generic WordPress components to be used for creating common UI elements shared between screens and features of the WordPress dashboard.

Panel, Panel Body, Panel Row

The Panels are what you’ll store your controls in. Think of them as Bootstrap accordions:

• Panels are the Accordion
• Panel Bodys are the Accordion Items
• Panel Rows are flex items that add some top margin.
  • Panel Rows are optional. They do some weird flex stuff to their child elements that I don’t always appreciate, so it’s often easier to leave them off entirely or to wrap your controls in a div with some inline styles.

The Controls

ToggleControl, SelectControl, and TextControl are probably the tools you’ll reach for the most.

• ToggleControl (true / false) can turn on or off options and should also allow for conditional rendering of further Panel elements
  • Example: Toggling a Swiper block’s “Navigation” to “On” also renders a new Panel for “Navigation Settings”
• SelectControl is just a WordPress UI for select elements.
• TextControl is a WordPress UI for inputs.

Responsive Design and other technical choices

As much as possible, things like responsive design and other technical choices should be kept abstracted away from the block itself. If there do need to be handles to control those options, lean into components that are rendered-on-demand, so that the block’s initial API doesn’t feel overwhelming.