Update specs with more details on usage of Fields API by third party apps/plugins, refresh readme so it's more clear and concise.

• Main Readme refresh

Objects in order of progress, then by priority:

• Users #29 @sc0ttkclark
• Terms #28 @technosailor
• Settings API #33 @technosailor
• Posts #26 @sc0ttkclark + @Idealien
• Comment #31 @sc0ttkclark
• Nav Menu Items #34 @diddledan
• Widgets #27 @nicholasio
• Media #32 @wpsmith

Hey

I just got to say that this looks very interesting!

I would suggest posting about this in the Advanced WordPress Facebook group as a way for a lot of people to quickly find out about this project:
https://www.facebook.com/groups/advancedwp/
and a way to get some quick feedback.

I will also suggest posting in a LinkedIn WordPress group:
https://www.linkedin.com/grp/home?gid=1482937
https://www.linkedin.com/grp/home?gid=3722491

Add instructions for patching implementation files to readme (patch / diff files would be handy for core/lead devs)

This control type only outputs the text value, no input, no saving.

Controls that offer options (muli-checkbox, radio, select) should accept a datasource as an alternative to passing 'choices' an array, or extending the control with your own choices method to build it dynamically.

They should accept a new Datasource class which we should build in support for a few of the main data sources in WordPress such as Posts, Terms, Users, Comments, Post formats, etc..

Seems like plugin devs might expect to be able to quickly add a WYSIWYG/TinyMCE editor to the backend using the Fields API. I don’t see a way to do so now. Apologies if I missed anything about it in the Issues or docs. But if it hasn’t already been discussed, are there any chances you’d be willing to add it? I think it makes sense in core instead of being left to 3rd parties.

Right now, our Settings API implementation in the Fields API works nicely as an integration that utilizes the Settings API itself. That means it stores settings in two places (when registered through the Fields API).

If the Settings API itself relied on communicating with the Fields API instead, that would maintain backwards compatibility at the same time as having one datastore for those configurations.

Further, any plugins and themes utilizing the Settings API would automatically be accessible through any REST API endpoints that utilize the Fields API.

• add_settings_section() to add section to settings-$page form, callback is the 'description'
• add_settings_field() to add control to section, callback is control output
• do_settings_sections() to get form for settings-$page and maybe_render()
• do_settings_fields() is tricky because of the section maybe_render() outputs a but this function outputs only rows, the methods are protected which output the rows, more work needs to be done for compatibility there

• Method to register config for widget form fields (return array?)
• Widget form parent method should look for fields config, if set, output the form fields
• Widget update parent method should look for fields config, if set, process saving of the form fields

This is just a placeholder, it exists for us to return to once we get more work done on the main field types. We want to ensure the Fields API enables plugin/theme developers to make use of their own custom implementations of a repeatable / loop field type. We aim to ensure a standard way to interact with the Fields API for such a purpose, leaving UI to the discretion of the plugin/theme developer for any given project.

• Section - Should call add_meta_box
• Display fields for section inside of meta box
• Save handling in editor (hooked into wp admin page directly, call save_fields() and in save_fields() call the edit comment function as it normally would, then parent::save_fields() to save the custom fields)
• Register core fields

• WP_Customize_Manager
• WP_Customize_Control
• WP_Customize_Setting
• WP_Customize_Section
• WP_Customize_Panel
• Additional classes related to the above
• phpunit passes against core tests

Had a discussion with @ericandrewlewis and we began working on a refresh of the Fields API specifications. There were some actionable things I mentioned while talking to him, I'm adding them here so I don't lose track of them.

• Sections = Headings
• Display sections and their fields in user editor form, below contact fields
• Save handling in editor
• Pull values for fields based on user currently being editted
• Merge existing user editor fields into implementation
• Handle edit_user compatibility concerns
• Get user object fields saving correctly (currently meta-only)
• Test it out, confirm all fields functional

Idea: Maybe hook into user insert / update function to process fields like for posts in #26?

In your examples you include the add_setting() method for each object type. I believe having this as a requirement for each control is pretty pointless and would add a lot of unnecessary code when you compare it to how some third-party libraries handle stuff like this already.

Currently each object type has only 1 data storage:

Users - wp_usermeta
Post Types - wp_postmeta
Taxonomies - wp_termmeta (I'm guessing future tense here).
Settings - wp_options

Whereas the Customiser has 2 data storage options, theme mods and the wp_options table, hence the requirement for add_setting().

The API obviously isn't fleshed out yet, but this is the main thing that strikes me as something that would eventually become quite cumbersome, and would drive me to just create my own wrapper that would register the setting the same time as the control.

Like from ACF project: http://www.advancedcustomfields.com/resources/repeater/

I still think it's confusing to have object_type and object_name when the latter is determined to possibly be a post_type.

"so my name is the type, and the type is the name, but sometimes the type is the name and the name is the type? my brain hurts.."

It'd be great to have a list on-hand of developers (and their GitHub usernames if possible) for themes and plugins so that we can know who to work with on spreading the use of the Fields API. It'd be great to have a large number of them to reference in our official proposal when it comes time for that.

• Add to readme

It's difficult to get a form from the control, we should address that and add methods that help get those types of relations.

Forms

• Don't allow $wp_fields->add_form() to add duplicate forms, return WP_Error
• Add $form->get_sections() helper method that maps to $wp_fields->get_sections( $object_type, $object_name, $form_id )

Sections

• Add $section->get_form() to get the correct form object from $section->form which stores the Form ID
• Don't allow $wp_fields->add_section() to add duplicate sections, return WP_Error
• Add $section->get_controls() helper method that maps to $wp_fields->get_controls( $object_type, $object_name, $section_id )
• Change all references of ->form to ->get_parent()

Controls

• Add $control->get_section() to get the correct section object from $control->section which stores the Section ID
• Add $control->get_form() to get the correct form object from the section in $control->get_section()
• $control->fields and $control->field is a bit convoluted outside of the Customizer, we need to fix this
• Add $control->get_field() to get the correct field object from $control->field which stores the Field ID
• Don't allow $wp_fields->add_control() to add duplicate controls, return WP_Error
• Change all references of ->section to ->get_parent()

Fields

• Don't allow $wp_fields->add_field() to add duplicate fields, return WP_Error #

• phpunit
• qunit

In your example for fields_api_example_post_field_register() I believe the priority should be numeric based to keep the new API consistent rather than bowing down to what add_meta_box() did previously.

add_meta_box() could then be changed to translate current low/high/core/default priorities into sane numeric default values to retain backwards compatibility.

I have faced with unpleasant warning when I've tried to use an example from the README file. It turns out that you sanitize args list passed to the add_field method. The problem is that $args parameter is always an object or an array (not a string), but sanitize_key function tries to strtolower it and causes this warning.

Instead of using sanitize_key function, we could take md5 from serialized version of the $args parameter or something similar.

[15-Jun-2015 07:03:46 UTC] PHP Warning:  strtolower() expects parameter 1 to be string, array given in /srv/www/wordpress-default/wp-includes/formatting.php on line 1233
[15-Jun-2015 07:03:46 UTC] PHP Stack trace:
[15-Jun-2015 07:03:46 UTC] PHP   1. {main}() /srv/www/wordpress-default/wp-admin/themes.php:0
[15-Jun-2015 07:03:46 UTC] PHP   2. require_once() /srv/www/wordpress-default/wp-admin/themes.php:10
[15-Jun-2015 07:03:46 UTC] PHP   3. require_once() /srv/www/wordpress-default/wp-admin/admin.php:31
[15-Jun-2015 07:03:46 UTC] PHP   4. require_once() /srv/www/wordpress-default/wp-load.php:29
[15-Jun-2015 07:03:46 UTC] PHP   5. require_once() /srv/www/wordpress-default/wp-config.php:60
[15-Jun-2015 07:03:46 UTC] PHP   6. do_action($tag = 'wp_loaded', $arg = *uninitialized*) /srv/www/wordpress-default/wp-settings.php:374
[15-Jun-2015 07:03:46 UTC] PHP   7. call_user_func_array:{/srv/www/wordpress-default/wp-includes/plugin.php:496}(array (0 => class WP_Fields_API { private $_post_values = NULL }, 1 => 'wp_loaded'), array (0 => '')) /srv/www/wordpress-default/wp-includes/plugin.php:496
[15-Jun-2015 07:03:46 UTC] PHP   8. WP_Fields_API->wp_loaded('') /srv/www/wordpress-default/wp-includes/plugin.php:496
[15-Jun-2015 07:03:46 UTC] PHP   9. do_action($tag = 'fields_register', $arg = class WP_Fields_API { private $_post_values = NULL }) /srv/www/wordpress-default/wp-content/mu-plugins/vendor/wordpress-fields-api/includes/class-wp-fields-api.php:104
[15-Jun-2015 07:03:46 UTC] PHP  10. call_user_func_array:{/srv/www/wordpress-default/wp-includes/plugin.php:496}(array (0 => class TEN\Shared\Settings {  }, 1 => 'register_settings'), array (0 => class WP_Fields_API { private $_post_values = NULL })) /srv/www/wordpress-default/wp-includes/plugin.php:496
[15-Jun-2015 07:03:46 UTC] PHP  11. TEN\Shared\Settings->register_settings($wp_fields = class WP_Fields_API { private $_post_values = NULL }) /srv/www/wordpress-default/wp-includes/plugin.php:496
[15-Jun-2015 07:03:46 UTC] PHP  12. WP_Fields_API->add_field($object_type = 'settings', $id = 'mytheme_sharing_buttons', $args = array ('default' => '1', 'capability' => 'manage_options', 'control' => array ('label' => 'Show Sharing Buttons?', 'description' => 'This will show sharing buttons below blog posts on singular templates', 'section' => 'mytheme_setting_sharing', 'type' => 'checkbox'))) /srv/www/wordpress-default/wp-content/mu-plugins/includes/TEN/Shared/Settings.php:80
[15-Jun-2015 07:03:46 UTC] PHP  13. sanitize_key($key = array ('default' => '1', 'capability' => 'manage_options')) /srv/www/wordpress-default/wp-content/mu-plugins/vendor/wordpress-fields-api/includes/class-wp-fields-api.php:588
[15-Jun-2015 07:03:46 UTC] PHP  14. strtolower(array ('default' => '1', 'capability' => 'manage_options')) /srv/www/wordpress-default/wp-includes/formatting.php:1233

• Map Settings API functions over to Fields API for backwards compat
• Display sections
• Display fields for each section
• Settings save integration to process through Settings API
• Backwards compat control types?
• Extend (?) Control Type for Page Settings
• Control "Group" to allow more than one type of control per "field". (e.g. thumbnail sizes)

Long term we need to enable nesting for plugins / themes to use the Fields API in the context of #8

Trying to think up how to make Fields vs Controls more clear, because Fields sounds like form fields, but controls are the inputs on the actual form.

• WP_Fields_API_Value
• WP_Fields_API_Storage
• WP_Fields_API_Stash
• WP_Fields_API_Meta
• WP_Fields_API_Setting (match Customizer)

Need some input/feedback from @helenhousandi when possible.

A Control is the input that appears in a form, which handles showing the current value and letting someone edit that value.

A Field handles getting, sanitizing, or saving the value and the operations involved in that across all object types.

Getting the fields via core API in post edit screen is cool, ACF and a horde of similar plugins already do this even without API. But there's almost no solutions for adding custom fields to the Quick Edit panels. Being able to add fields there would help many users. Maybe, it's out of scope for this API. Maybe it's too early to think about it. Maybe we need a total rework of Quick Edit panels. That's kind of terra incognita atm. Just saying.

• Sections = Headings?
• Display sections and their fields in term editor form
• Save handling in editor
• Maintain hooks on display as available in term add / term edit forms

Idea: Maybe hook into term insert / update function to process fields like for posts in #26?

• Display fields in editor / modal
• Save handling from editor / modal

Follow-up: Add backwards compat for existing hook to add custom fields

Add hooks to auto-override customizer classes and user-edit.php for testing purposes.

Customizer manager class override:

remove_action( 'plugins_loaded', '_wp_customize_include' );
add_action( 'plugins_loaded', '_wp_fields_api_customize_include' );

User profile edit override:

add_action( 'load-user-edit.php', '_wp_fields_api_load_user_edit' );

I installed the plugin on WordPress 4.2 and overrode the core files with the files included in implementation/. This produced a fatal error.

Fatal error: Class 'WP_Customize_Theme_Control' not found in /srv/www/wordpress-develop/src/wp-includes/class-wp-customize-manager.php on line 1378

I believe this is because the overridden version of class-wp-customize-control.php does not include class WP_Customize_Theme_Control which was added in 4.2.

While we're at it, can we add installation instructions for the plugin as it is?

Just adding this here for later

• Look at previous Core Proposals and devise our markup / format from those

This error appears whenever I attempt to access the Customizer with the Fields API activated.

I have turned off all other plugins and gone back to twentyfifteen theme and still get this error. I've just pulled the latest changes from master and still get this error message.

Awesome ideas, though!! I've been trying to work on something like this for a while, based on my CakePHP experience with form building. Best of luck!

lets use the issue to discuss ideas - the conversation gets lost a bit on slack

$wp_fields->add_field( ‘object_type’, ‘field_id’, array( … ) );`
is current usage (as per Customizer base implementation)
sc0ttkclark

but for e.g post, taxonomy.. we need to add the "actual type"
my suggestion would be to use an "configuration" array or object?

$wp_fields->add_field(
    array(
        'object' => 'post_type',
        'type'    => 'my_custom_post_type',
        'id'        => 'field_id'
    ),
    array( ... ) );

this is better than add it as another parameter which needs to be NULL for e.g. user

Not sure if this is possible given current hooks.

• Display fields for nav menu item
• Save fields on menu save

Advanced Custom Fields and similar plugins offer rules for meta box visibility such as these:

This is very powerful because it allows the creation of meta boxes that:

• appear only when you select a certain page template (meta boxes appear as soon as you select the template, without a page refresh);
• appear only for certain post categories
• etc.

To accomplish this, there are a couple of approaches we could take:

1. Let the first parameter of the add_field and add_section methods take an optional array instead of the default string, which would allow users to specify in more detail exactly where fields and sections appear.
2. Add an additional 'visibility' parameter that would work alongside 'capability' to allow users to filter areas where fields would appear. (This may be more legible than option one.)

I appreciate that the Fields API may not be a complete functional replacement for ACF. But if it's to become widely adopted and loved by all, it probably needs to take on some of the more advanced functionality that developers are currently gaining from third-party plugins.

For internal time tracking purposes (Harvest)

I'd like help on fleshing out the examples (what fields to register for each use-case) on each of the main objects:

• Customizer
• User profile

Additional examples for long-term reach:

• Settings screens
• Post editor

As we are dealing with some moving pieces, regarding shared architectures, classes/subclasses, etc. This issue is for deciding and implementing these structures.

@sc0ttkclark: Some initial thoughts based on your recent work of Jan 27th, 2016.

Here is my feedback, by request. Some of it may seem obvious, but I'm approaching this from the perspective of not being overly familiar with the code and philosophy and what I, as an arbitrary plugin developer, would need to get up to speed and implement it.

Creating an implementation class

• How is $this->object_type defined?
• Does obejct_type mirror WordPress object types (i.e. WP_User, WP_Post, etc)?
• Does object_name mirror WordPress object names (i.e. post_tag, etc )?
• Maybe we should force the use of WP_Error returns on save if failed?

Registering Screen

• For plugins, how does registering a screen differ from hooking to admin_menu and a callback in the traditional plugin development sense?

General

• I feel like there is some need for some terminology definition here. You allude to what a Screen and a Control is, but how they relate to WordPress is mildly unclear (though probably a bit more clear to me). If a WordPress developer jumped into this, it would take a bit just to understand the terminology and how it relates to what they already know in WordPress. For example...
  • What is a screen? Is it an admin page? Is it a customizer section? Do the terminologies match what is already in WordPress?
  • What is a panel and how is it different from a screen?
  • Are there specific use cases that can be pointed to in the WP Admin that would make this stuff clearer? Not to dumb things down for a fairly advanced project, but... Maybe some screenshots lining up what belongs to what in the Fields implementation?
• Do plugin authors have to hook on admin_init for saving callbacks? I'd assume yes, but that's not clear.
• Why is the object_name null here? Why wouldn't it be 'user'?

I'm working on moving a lot of the configs over to using shorthand, I just need to finish moving the forms / settings forms over to this new format.

Would love any help from contributors on suggestions for skeleton classes / methods that cover the following:

1. Sanitization of value before save
2. Override save of a value to a different place (for third party things)
3. Display field input for form
4. Enqueue assets (js/css) apart from field input display in above number 3, done in footer enqueue of page request

Other things that would be great to figure out, though I'm not sure how best to tackle it yet:

• Validation of value before the start of saving data
• Field value display (onto page in theme)

Registering them would look like this, that part is somewhat the easy part:

$wp_fields->register_control_type( 'text', 'WP_Fields_API_Control_Text' );

• WP_Customize_Manager
• WP_Customize_Control
• WP_Customize_Setting
• WP_Customize_Section
• WP_Customize_Panel
• Additional classes related to the above
• phpunit passes against core tests

Just adding these here as notes of some of the feedback I got from @mboynes today.

• Fields vs Controls is confusing, Field sounds like a form field, like an input, but control (ala customizer) is less obvious
• Examples could be simplified, passing in $object_type / $object_name everywhere on each level is tedious / unnecessary, we should show/use examples of the shorthand instead with nested arrays of section controls and fields

• Section - Should call add_meta_box
• Field - Should call register_meta
• Display fields for section inside of meta box
• Save handling in editor
• Pick up field saves from wp_insert_post( $post_data ) just like terms allows, and process through Fields API (maybe this can apply to the item above)
• Register core fields

Future ability to add fields to display in:

• edit_form_after_title
• post_submitbox_misc_actions

We need one, you got one?

A project of this complexity would blossom with a great deal of test coverage and some continuous integration.

Are there any plans for the rest API support?

• Create/Extend REST API Endpoints for Schema
• Expose Fields to REST (register_rest_field)

Should we include a date, datetime, and/or time control type?

I've been working the WP-API project since August. In hindsight, here are some things I wish we had done in advance:

1. Set a clear mission statement for the project. This will give clarity to the problem you're solving, what to say yes to, and what to say no to. You ideally want to avoid crises of faith late in the project.
2. For your contributors, clarify involvement expectations. When most contributors are doing so in their "free" time (e.g. not getting paid directly for it), it's really difficult to budget for unlimited development scope. A little bit of proper project management goes a long way. I feel like WP-API is a much more sustainable project with four contributing developers than two. I would encourage you to have at least three.
3. Model your data before writing code. What is a field? What attributes should it have and why? What is a control? What attributes should it have and why? When you dive into development before appropriately modeling your application, you run into these implementation details one by one, and burn a lot of time (waiting to) discuss them.
4. Focus on clearing blockers above all else. Because you're working on an open source project with contributors across many timezones, average time to feedback will optimistically be 6 hours. More likely, it will be 24-48 hours. This slow feedback cycle can kill progress on pull requests. As a project maintainer, prioritize giving feedback, clearing blockers, and making decisions.

@rachelbaker @joehoyle or @rmccue may have other input.