Imagine someone creates an open-source, JavaScript admin interface for their WordPress site and names it after a greek demigod. You’re probably thinking wow, that’s so cool, I wonder if I can make it work on my site. But then you start thinking about all of the custom metaboxes and other types of custom forms that plugins add to the post, term, and user edit screens.
There is no standard for metaboxes or for declaring what fields a plugin has to use. Making something that “just works” with everything is increasingly more complicated. Custom API-driven interfaces remain the territory of those who can afford to build and maintain bespoke solutions.
Many people, including myself, have talked extensively about an API-driven future of WordPress. In the first article I wrote for Torque on the REST API, I reiterated what WordPress lead developer Andrew Nacin told the audience at WordCamp Milwaukee in 2014: the best projects for contributors to become a part of if they wanted to be a part of the future of WordPress were the REST API and what was then called the metadata project.
Part of the REST API is now in core, and the metadata project, now known as the Fields API project, has made great progress but has fewer contributors and is not yet ready for core.
If WordPress core had a Fields API, and plugins used it to declare their fields, then the problem I presented at the beginning of this article would be solvable. Developers making JavaScript-powered interfaces would be able to see what the field names, types, and storage locations were for every plugin and programmatically generate important metaboxes for each one.
WordPress core’s job is to provide infrastructure to make new and improved interfaces possible. Infrastructure for the REST API is a huge step in the right direction, but the Fields API is just as important. Not having a Fields API in place is not just holding back Calypso, it’s going to hold back any type of app or alternative user interface for WordPress that seeks to be a generic “work with anything” tool.
I recently spoke with Scott Kingsley Clark about the progress of the Fields API and the possibilities it opens up. Scott is the lead developer of the Fields API project, a senior web engineer at 10up, and lead developer of the Pods Framework.
I’d like to tell you about what he told me and show you how to use the Fields API to create a term meta editor.
Progress On The Fields API
In mid-January, Scott posted a thorough update on the Fields API project. Since then, he and other contributors have put more work into the project. Although it is not yet finished and could use more help, the groundwork has been laid to create a standard for declaring the fields. This includes all of the post, user, meta fields, or options that a plugin or theme needs.
The Fields API project isn’t just about declaring fields, it also allows for automatic generation of admin and front-end forms for editing those fields. Scott says that the Fields API will prevent developers from having to “build custom interfaces and libraries” for their interface. All of this repetitive work “has created hundreds of islands that can’t talk to each other, can’t share resources, and slowly sink without constant attention from the developers that built them as WordPress continues to grow and change around them. This is a lifeboat for these developers, they can come to the mainland and have a nice hot cocoa.”
As a proof of concept for the Fields API project, the plugin includes a user meta fields editor generated with the Fields API. It’s an excellent demonstration, but hints at what a complete Fields API in core would do.
“The Fields API will be another pivotal moment in the history of WordPress,” Scott said. “This API has the ability to unify every part of WordPress that deals with Objects (Users, Post Types, Taxonomies, Comments) and Fields (Object fields, Custom fields, Options) — a developer can build for every area with little to no custom code as easily as they create a new post type.”
This is a huge deal. WordPress, as an application framework, needs more than a REST API. It needs a way to connect all of its core data types and countless plugins added on top of those in a standard way for new applications to build on.
Scott adds that, with the Fields API, “Applications, Plugins, and Themes can all interact with each other safely and maintain a common user experience. The content structures embedded deep within WordPress can be interacted with and used by new projects like Calypso and other efforts to improve WordPress in the future.”
How It Works
Last week I wrote about the new term metadata feature in WordPress 4.4. I didn’t show how to create an admin interface for it. Instead, I said you could either make your own form or come back this week to see how to do it with the Fields API.
To demonstrate how easy the Fields API is, I have created a simple plugin to register two taxonomies. One is called “city” and one is called “state.” Before term meta, making a term of the city taxonomy associated with a term of the state taxonomy would not have been simple. Now we can just store that relationship in term meta.
Most of the code in my example plugin, which you can see here, is registering the two taxonomies. Adding the field to the edit screen for city terms with a dropdown of all of the state terms is only a few lines of code. Let’s walk through it.
The syntax of registering fields with the Fields API is modeled after the syntax of the customizer and therefore should be familiar to WordPress developers.
The first thing we do is hook into the “fields_register” action. This action exposes an object of the WP_Fields_API class, which gives us the ability to add new sections and fields to an admin screen. Start like this:
add_action( 'fields_register', 'josh_city_term_fields' );
To create the section, we use the method add_section() of the WP_Fields_API class. Here is how we do that:
/**
* @param WP_Fields_API $wp_fields
*/
function josh_city_term_fields( $wp_fields ) {
// What WP Object type?
$object_type = 'term';
// Which taxonomy?
$object_name = 'city';
// Form: Which screen to add to
$form_id = 'term-edit';
//create section
$section_id = 'city-state'; //
$section_args = array(
'title' => __( 'State', 'josh-tfx' ),
'form' => $form_id,
);
$wp_fields->add_section( $object_type, $section_id, $object_name, $section_args );
}
Now that we have a form section, we need to add a field to it. For this we can use the method add_field() like this:
// Add a field $field_id = 'state'; //setup field $field_args = array( 'control' => array( 'type' => 'dropdown-terms', 'taxonomy' => 'state', 'section' => $section_id, 'label' => __( 'State', 'josh-tfx' ), 'description' => __( 'What city is this state in?', 'josh-tfx' ), ), ); $wp_fields->add_field( $object_type, $field_id, $object_name, $field_args );
Make sure to keep it inside the same function.
That’s it, folks. No handling saving or sanitizing — the defaults will work in most use-cases. No making the markup for the form. It’s all done for us.
Here is the whole function together:
* @param WP_Fields_API $wp_fields
*/
function josh_tfx_term_fields( $wp_fields ) {
// What WP Object type?
$object_type = 'term';
// Which taxonomy?
$object_name = 'city';
// Form: Which screen to add to
$form_id = 'term-edit';
//create section
$section_id = 'city-state'; //
$section_args = array(
'title' => __( 'State', 'josh-tfx' ),
'form' => $form_id,
);
$wp_fields->add_section( $object_type, $section_id, $object_name, $section_args );
// Add a field
$field_id = 'state';
//setup field
$field_args = array(
'control' => array(
'type' => 'dropdown-terms',
'taxonomy' => 'state',
'section' => $section_id,
'label' => __( 'State', 'josh-tfx' ),
'description' => __( 'What city is this state in?', 'josh-tfx' ),
),
);
$wp_fields->add_field( $object_type, $field_id, $object_name, $field_args );
}
add_action( 'fields_register', 'josh_city_term_fields' );
If you’ve ever created a WordPress widget and thought how insane it is that you have to manually create the admin form, then you should be excited about the Fields API because it fixes that issue.
There is a growing list of example implementations in the plugin’s documentation. Check them out to see how it works and give feedback on how it can be approved. The Fields API team is also seeking new examples — they’ll even build the code for you if you can describe what you need.
Get Excited, Get Involved
To be honest, I think the lack of a Fields API is one of the biggest problems with WordPress. The example I used with Calypso not working with any plugins besides Jetpack is a major issue that needs to be addressed.
If we’re going to build Calypso-like applications with WordPress, putting all plugin settings and post metaboxes into a standard module would be a nightmare. But if we had a Fields API, there would be a programmatic definition of every plugin’s fields. Then creating a new implementation of the admin would be solvable.
The Fields API plugin is currently on GitHub, where you can try it out and give your feedback today. The plugin will be available on WordPress.org as soon as it reaches beta status. Now is the time to get involved in this exciting new project and help improve the future of WordPress.
10 Comments