Fields API — Where we’re at

Over the past few months, we’ve been working towards one of the most wide-reaching API’s to be suggested for core inclusion, apart from the REST API. It has the potential to touch nearly every area of WordPress that deals with forms and fields. The Fields API is nearly there, and we’re seeking more feedback on a number of areas we need to tie down before we go into the official proposal stage for core inclusion.

What is the Fields API?

We just published a specification for the Fields API last week and we’re seeking constructive feedback on that now. Please take a moment to read about it, ask questions, and voice your concerns with us so we can address those things before we go to the next official stage.

There’s also some helpful docs which include TerminologyRegistration of fields, and example code.

What can you do with the Fields API right now?

We’ve put together a number of implementations to show the potential of what the Fields API can accomplish inside of core. Each implementation is an example of what could end up in WordPress core, should the Fields API itself be merged.

  • Edit User screen (@sc0ttkclark, @technosailor)
    • Our internal implementation of the Edit User screen replaces core’s entirely using the Fields API.
    • Here’s a code example to add more fields (and sections and controls) to the Edit User screen
    • Backwards compatibility hooks
    • To-do: Further custom markup and/or styling to match uniform layout
  • Edit Post screen (@sc0ttkclark, @brentvr)
    • Our internal implementation of the Edit Post screen will replace core’s entirely using the Fields API, we only have support for adding new sections / controls right now
    • To-do: Register sections / controls based on what’s on the Post Editor screen currently (@brentvr is working on this now)
    • To-do: Add additional output types (no meta box, etc)
    • To-do: Backwards compatibility hooks
  • Term Add / Edit (@sc0ttkclark, @technosailor)
    • Our internal implementations of the Add Term and Edit Term screen replaces core’s entirely using the Fields API
    • Backwards compatibility hooks
  • Comment Edit (@sc0ttkclark)
    • Our internal implementation of the Edit Comment screen will replace core’s entirely using the Fields API, we only have support for adding new sections / controls right now
    • To-do: Register sections / controls based on what’s on the Comment Editor screen currently
    • To-do: Add additional output types (no meta box, etc)
    • To-do: Backwards compatibility hooks
  • Settings Pages (@sc0ttkclark, @technosailor)
  • Widget Forms (@nicholasio, @sc0ttkclark)
    • Our internal implementation of the Widget forms will integrate with WP_Widget to allow form fields to be registered for widgets and rendered/saved automatically without the custom code every widget ends up needing currently.
    • To-do: WP_Widget integration (@nicholasio is working on this now)
  • Nav Menu Items (@diddledan, @sc0ttkclark)
    • Our internal implementation of the Nav Menu Items overrides the core Walker class used for building the Nav Menu Item forms, and uses the Fields API to output registered controls.
    • To-do: More compatibility work for CSS
    • To-do: Look into Customizer integration
    • To-do: Getting/saving values for nav menu item fields
  • Media
    • We do not currently have an implementation for this yet, but one was proposed by @wpsmith, and we are seeking additional help from anyone looking to make this happen
    • To-do: Add sections and controls to Media Edit
    • To-do: Add sections and controls to Media Modal Add/Edit
  • REST API
    • We currently have limited direct integration with the REST API, but we’d like to work with the REST API team towards implementing REST API options and building in addition configurations the REST API can consume for it’s endpoint(s)
    • register_rest_field integration

Possible Roadmap to Merge

Here’s an example of how Fields API could eventually be merged into core, along with other implementations.

  • Release 1: Merge Fields API into core
  • Release 2: Merge Implementation 1 into core
  • etc..

So each release could focus on a different implementation, which of course is a great time to coincide to UX / design work on each area, like the User Profile screen. There’s lots of options here, but hey, let’s discuss it!

How to help

If you’d like to help anywhere, please just reach out and I’ll get you into it. Every area needs review, some areas still need more work to finish, but any area could use additional help.

So who do you contact or where do you go to help?

Next Meeting Agenda – March 14th, 2016

Our next meeting is Monday 20:00 UTC 2015 and it promises to be eventful. We plan on discussing a number of things including:

#feature-plugins, #fields-api, #options-meta

Fields API updates from Q4 of 2015

It’s been a while since I updated everyone here about progress on the Fields API. I’ve been hard at work in the code and haven’t come up for air until now, but I’m planning on more regular updates in the coming weeks 🙂

Lots of progress since our last chat summary in early October, here’s a bird’s eye view of what we’ve been up to:

Where can we use help right now?

  • Review our User Profile screen implementation, let us know if it makes sense to you as a developer. It’s the kind of code you’ll be looking at needing for any custom screens you want to implement in plugins or themes, and it’s the kind of code we’re looking at using for other WordPress screens too (Post editor screen, Term editor screen, etc..)
  • Help us create use-cases for each type of object (Custom Post Types, Custom Taxonomies, Users, Comments, Media, Widgets, Nav Menu Items, etc..) — we’re specifically looking for what custom fields you could create for these use-cases and how it could make sense in real world scenarios. You can start out with just the structure, we can help you build the code for it.
  • We’re getting ready to release this on WordPress.org as a plugin, we could use some help to write up a good readme and ensure it directs people to the correct places for involvement

So who do you contact or where do you go to help?

Oh and did I mention that every minute you help us, you make someone really really really happy in the future? It could be your future self that gets to reap the rewards of your hard work!

#feature-plugins, #fields-api, #options-meta

Fields API chat summary – October 5th, 2015

Present: @sc0ttkclark, @nicholas_io, @tomharrigan, @ericlewis, @potatomaster

Logs: https://wordpress.slack.com/archives/core-fields/s1444021200000000

  • I just got 100 hours from 10up to work on Fields API!
  • I will be working on getting the WP 4.3 Customizer changes put into the Fields API, my first pass doesn’t have unit tests passing yet
  • We’ll be fleshing out Control classes, based on Customizer control classes and expand the main control class into individual classes as opposed to a ‘switch’
  • We laid out a few implementations we’d like to get into prototyping
    • User profile fields (piggy backing existing UI of section heading + fields) @sc0ttkclark
    • Settings API (cue the oooh’s and aaah’s sound effect) @sc0ttkclark
    • Post editor (meta boxes + fields) @tomharrigan
    • Widget forms @nicholas_io
    • Future: Term editor (sections + fields)
    • Future: Comment forms?
  • We want to improve the main Fields API readme to better explain the project, offer more links to information about the Customizer API since it’s what we based the Fields API on, and flesh out more examples
  • We need more examples, so any use-cases we can put together for any object type, would be handy to start putting that code together (structures, not custom implementations or overrides)

We certainly could use additional contributors involved with the project, especially as we seek to start more implementation prototypes of how things could work. Just hop into Slack #core-fields or check out our Github repo. Over the next 5 weeks my involvement in the project will be greatly increased, so if you are going to get involved — now would be the right timing!

Next chat: Monday 20:00 UTC 2015 (every Monday)

#chats, #feature-plugins, #fields-api, #meeting-notes, #options-meta

Fields API: Request for review of direction

Over the past many months this year, I have been working with guidance from @helen on the new Fields API with the intention of inclusion into WordPress core. It’s based on the Customizer API, so those who have experience with it will see a lot of similarities. The goal isn’t to create a duplicate API though, and in our proposal we would be implementing the Fields API within the Customizer API.

What does that bring to core as a whole? It gives core a very real and far reaching API to add fields to any type of object in a standard interface. Given the growth of the Customizer API and its inclusion of fields, @helen and I both agreed it’d be great to leverage everything it can do in our efforts here. The goal isn’t focused on the actual Customizer UI or editing on the front-end, it’s all data-oriented.

We would create implementations behind the scenes in the various existing APIs such as the Customizer API (now) and Settings API (later) while maintaining backwards compatibility. We’re also hoping to implement the Fields API within the User profile screen. This would give core more flexibility towards revamping the User profile screen in the future, without having to tackle even more than just a UI refresh. That’s also not mentioning the fact that plugin and theme authors could leverage this API to extend WordPress with their own fields in the various areas. Future places we’d look at integrating Fields API with would be the Post editor, which I’ve pegged as our third focus, behind User profile fields and the Customizer API.

Anyways, that leads us to the point we’re at now, we have an API but we don’t have all of the built-in Field Types (control types) yet or the latest Customizer API changes from 4.3 merged upstream into the Fields API. There are unit tests that are running (and passing!) so that is going to help us on our road towards core for sure.

We need developers to give their feedback on the direction we’re heading. Here are the relevant links for those reviewing:

I’d love more feedback from anyone contributing to WordPress, or the *countless* plugin and theme developers who would use the Fields API. Please comment on this post, or if you’d like to discuss further, you can hop into our weekly meetings on Mondays (Monday 20:00 UTC 2015) in the WP Slack #core-fields channel, or ping me there anytime.

Update – 08/10/2015:

We now also have a growing list of developers who are behind this project and would implement it in their projects if it were merged into core.

#fields-api, #options-meta

Metadata API project reborn: The new Fields API project

Many of you will remember that a couple of years ago, @ericlewis and a group of us set out to start a project to make sense of all of the different APIs that arose from third party plugins and themes to build custom field solutions on top of WordPress. That project was nicknamed “Metamorphosis” and subsequently went by the “Metadata UI/API” project. As plugin authors dealing with and using custom fields and content types, we had been tackling the issues of developing for multiple object types in WordPress for years prior to getting together.

Now, @helen and I are pleased to (re)introduce to you what we’re hoping to be the fruits of all of this labor: Meet the new Fields API project.

function fields_api_example_post_field_register( $wp_fields ) {

   // 1. Define a new section (meta box) for fields to appear in
   $wp_fields->add_section( 'post_type', 'my_cpt', 'my_meta_box',
      array(
         // Visible title of section
         'title'       => __( 'My Meta Box', 'mytheme' ),

         // Determines what order this appears in
         'priority'    => 'high',

         // Determines what order this appears in
         'context'     => 'side',

         // Capability needed to tweak
         'capability'  => 'my_custom_capability'
      )
   );

   // 2. Register new fields
   $wp_fields->add_field( 'post_type', 'my_cpt', 'my_custom_field',
      array(
         // Default field/value to save
         'default'    => 'All about that post',

         // Optional. Special permissions for accessing this field.
         'capability' => 'my_custom_capability',

         // Optional. Add an associated control (otherwise it won't show up in the UI)
         'control' => array(
            // Don't set 'id' and it will automatically be generated for you as
            'id' => 'mysite_my_custom_field',

            // Admin-visible name of the control
            'label'   => __( 'My Custom Field', 'mytheme' ),

            // ID of the section this control should render in (can be one of yours, or a WordPress default section)
            'section' => 'my_meta_box',

            // Control type
            'type'    => 'text'
         )
      )
   );

}
add_action( 'fields_register', 'fields_api_example_post_field_register' );

(Please note: The code above may not be the same as the final implementation, it will especially change over the next few weeks)

First of all, we split off the UI side of the project to focus solely on the API. This way, we’re not held up by anything as we move towards implementation inside of core. We can tackle each UI separately and that helps us keep the project nimble and on track.

The goals of this new API proposal will be to be implemented across WordPress objects as an API to register fields and sections for. We aim to cover these objects (not necessarily in this order):

  • Customizer (retrofitting it beneath the existing Customizer API)
  • User profile screen
  • Post editor
  • Settings screens (retrofitting it beneath the existing Settings API)
  • And other areas in the future (Comment editor, Network Settings screens [see #15691], Media modals, etc)

This API offers a great deal of standardization across all of WordPress and code reusability. It’s paramount for third-party developers, who will be able to utilize these structures in their own plugins and themes, build apps and give access to other developers so they can contextually see what a site really contains. I see the biggest use-case being able to expose the entirety of WordPress to the REST API and giving apps like the WordPress iOS app access to meta boxes and custom fields to display real editor screens with field inputs based on the control types natively.

Areas we need help currently:

  • Examples and use cases for Customizer, User profile screen, Post editor, and Settings screens (submit issues in GitHub with your ideas, coordinate with us to refine them if you want)
  • Unit tests for core
  • Testing Customizer implementation, you’ll find the core files to replace under the /implementations/ folder in the repo
  • Brainstorming implementation classes for other object types to implement in the UI, starting with User profile screen

If you’re interested in joining our merry crew which includes @helen and a few of us, hop into Slack #core-fields and join our weekly meetings every Monday (Monday 20:00 UTC 2015). You can check out the Fields API and submit PRs on GitHub, or ping us in #core-fields throughout the week with questions or concerns.

#customize, #fields-api, #options-meta, #team-update

WP Metadata UI / API project update and new meeting time/place

It’s been a few weeks since we’ve posted an update, @mikeschinkel has been working hard on some new commits to give us some shortcuts for option arrays and things have stabilized there finally. We’re now focused on documenting field type development so we can get some contributors in there fleshing out the remaining field types.

We are also moving our “Office Hours” time and place, to Mondays @ 1800 UTC , but instead of IRC where people can’t sync up and collaborate, we’re moving it to our public Gitter room. Some other WP projects are using it and we’ve found it incredibly helpful to keep up with GitHub activity along with chat that can happen at all times of the day and it sticks around for you to read anytime you want to.

Our Gitter chat can be found here: https://gitter.im/wordpress-metadata/metadata-ui-api

Anyone can see the chat messages, and if you want to participate it’s just a GitHub login away. They have iOS / Mac apps too, so that’s helpful to some people as well.

If you’re interested in contributing, or if you want to check out what we’ve got and need some insight, just ping us — anytime — in Gitter 🙂

#fields-api, #options-meta

WP Metadata API / UI office hours this Friday

We will continue our weekly meetings this Friday. As no other suggestions have been made, it will remain at 18:00 UTC on Fridays in #wordpress-core-plugins on Freenode IRC.

We may be transitioning from meeting into office hours as we haven’t had as many contributors joining us at the meetings as we had hoped. We will continue developing some awesomeness over at https://github.com/wordpress-metadata/metadata-ui-api

Feel free to hop into the issues and take ownership of new field types or documentation. We’re also looking for help with styling of the form fields and JS in relation to support for repeatable fields.

#fields-api, #options-meta

WP Metadata API / UI team meeting hours vote

It was brought up that our current meeting time at 18:00 UTC on Fridays in #wordpress-core-plugins on Freenode IRC is not necessarily the best for everyone.

What day would be better? Around what time would be better?

This week’s meeting will continue as planned at the existing time on Friday, but next Friday’s meeting will be postponed due to a scheduling conflict with @mikeschinkel and I.

#fields-api, #options-meta

We’re ready for more contributors to join us on the WP Metadata UI / API project

Where we need help most

  • Field Types – We need help building new field types, we currently have a few basic fields to start off with including the Text, Textarea, URL, Date, and Hidden field types.
  • Actions / Filters – We are now seeking to add in the hooks necessary to extend things further, feel free to request hooks anywhere you see a need for them.
  • Repeatable Fields – We are architecting a solution for repeatable fields, in which you can take a single field and make it have repeatable inputs that let someone add multiple values. These values would be stored in multiple meta values for the same meta key for the specific object ID.
  • Unit Testing – If your UT fu is strong, then strong would the use of your fu be on our team!

Have any other ideas you’d like to help out with? Hop in, the world is your oyster and we’re eager to help you get those pearls!

Join us in #wordpress-core-plugins on Freenode IRC and seek out @sc0ttkclark or @mikeschinkel if you need anything to help you get started, or open up an issue on our GitHub with your questions/feedback.

We’re also still meeting 18:00 UTC on Fridays in #wordpress-core-plugins on Freenode IRC, feel free to search IRC logs for <#metadata> for a history of our previous conversations.

So… ready to start? Head over to the WordPress Metadata UI / API GitHub now, see you there! Happy coding!

#fields-api, #options-meta

Metadata UI / API status update

We’ve been hard at work the past many weeks on getting something ready for contributors to start adding their PR’s against. @mikeschinkel took the helm for the initial base, after many discussions came up with a brilliant first code PR to the project. In our Friday meeting, we presented the PR and merged it into the official master for the project.

You can start browsing through it now over at: https://github.com/wordpress-metadata/metadata-ui-api

Some notable items from this initial first draft:

  • Global functions to access class/method based architecture (register_*)
  • register_post_form( ‘meta_box_name’, ‘post_type’, $args ) — Add new forms to a post type (like meta boxes)
  • register_post_field( ‘meta_key’, ‘post_type’, $args ) — Add new fields to a post type
  • Initial support to expand the API for use with Comment types, Option Groups, and Users
  • Support for custom object types that aren’t WP object types, like for plugins that have their own custom tables
  • Very efficient registration limits ‘fixups’ until fields are called, so registering hundreds of fields won’t detrimentally affect timing (confirmed by initial benchmarking)
  • Storage handling broken up into meta, options, taxonomy terms, can be extended by plugins to add additional storage options (like in Pods, we have custom tables/columns available for custom fields)
  • WP_Html_Element class methods handle html element building and auto-sanitization for attributes

Our next steps are to continue testing the API and start having contributors join in (read: yes, YOU!). We’d like to start getting PR’s that add new field types and start working on unit testing next.

Also, a call-out to our UI / JS team, we’re ready for you now 🙂

#fields-api, #options-meta