alleyinteractive / wordpress-fieldmanager

Custom field types for WordPress

Fieldmanager

Fieldmanager is a comprehensive toolkit for building forms, metaboxes, and custom admin screens for WordPress.

Using Fieldmanager in your WordPress Project

Fieldmanager is a powerful library which can make the development of sophisticated features a breeze. To get started, simply download and install this plugin into your plugins directory and activate it on the plugins screen. To learn how to use Fieldmanager's API, visit the project's official website at Fieldmanager.org. There is also a demo plugin which illustrates a lot of what you can do with Fieldmanager.

Requirements

• WordPress: 5.8+
• PHP: 7.4+

Downloads and Versioning.

You can view Fieldmanager's official releases here.

The main branch on GitHub is the "bleeding edge" release. As of 1.0, Fieldmanager will maintain a typical release cycle, with alpha, beta, and RC releases, and we hope to move through "minor" versions pretty quickly. While we encourage everyone to develop with and test on early releases and help us find the bugs, stable releases are recommended for production.

Contributing to Development

Development of Fieldmanager happens on GitHub. Bugs with Fieldmanager should be addressed in the GitHub issue queue, and enhancements or bug fixes should be submitted as pull requests, which are always welcome.

Generating Documentation

To build Fieldmanager's API documentation, the latest version of which is available at api.fieldmanager.org, you need apigen installed. Once you've got that, you can generate the entire documentation tree as follows:

apigen -c apigen.neon

wordpress-fieldmanager's Issues

RichTextArea broken with WP trunk, showing broken distraction free writing elements

See screenshots. After clicking to open the field, the issue goes away.

Add ability to set toolbars for RichTextArea in construct

We can currently modify the Fieldmanager_RichTextArea toolbars via filter, which works fairly well, but produces a lot of code. It would be nice to allow one to set the toolbars when creating the object, via the options array. For instance (toolbars exaggeratively brief),

$fm = new Fieldmanager_RichTextArea( array(
    'name' => 'my_richtextarea',
    'toolbar1' => array( 'bold', 'italic' ),
    'toolbar2' => array( 'formatselect' ),
    'toolbar3' => array( 'bullist' ),
    'toolbar4' => array( 'numlist' )
) );

We could also setup a few preset toolbar collections. For instance, 'toolbar_preset' => 'basic' might provide a very simple toolbar set, while (the default) 'toolbar_preset' => 'advanced' might provide a more complex one. For usage in the sidebar, 'toolbar_preset' => 'sidebar' could provide an especially narrow set that won't break the sidebar's width. And so on.

Confusing data type for $values in Fieldmanager_Field::element_markup()

The PHPDoc says that $values should be an array. If a field is singular or empty, (I think) this is actually a string. If it's an empty repeating field or group, it's an empty string, but count() is run on it, resulting in 1 when it should be 0.

The entire chain of $values should be traced, and the data type(s) should be enforced so that it always contains the exact type of data we're expecting. This can be an array for repeating fields and a string otherwise, or it can always an array. I'd opt for the latter for the sake of predictability.

Some field types need max-width set in post sidebar

Specifically, text fields (and the like, e.g. date, password, autocomplete, etc.), textareas, richtextareas, and (potentially) select fields. This is in both MP6 and the legacy admin style.

Style enhancements for Repeatable fields not in a Fieldmanager_Group

If you set 'limit' => 0 on a Fieldmanager_* object which isn't Fieldmanager_Group, the box title bar is absent. This is (I believe) the intended behavior, though it leaves some styling issues:

1. The "drag icon" that appears isn't properly lined up with the label Edit: no longer an issue
2. The "(x)" icon isn't properly lined up with the label Edit: no longer an issue
3. The field has overflow:auto set, which leaves a hint of a scroll bar
4. It's worth noting that this is also subject to #43, where a label is necessary for the move and remove icons to appear. Edit: resolved in #203

$fm = new Fieldmanager_Textfield( array(
    'name'           => 'repeatable_text',
    'limit'          => 0,
    'add_more_label' => 'Add another field',
    'sortable'       => true,
    'label'          => 'Text Field'
) );
$fm->add_meta_box( 'Repeatable Text Fields', 'demo-text' );

save_empty and single elements

Currently, the save_empty property only works when $limit != 1 (this is correctly documented). We should make this work when $limit == 1 as well.

allow 'slug' and 'post_name' storage option in datasource

Will make migration to WordPress.com much easier.

Labels are required for repeatable fields to work properly

1. If a 'label' is not set on a Fieldmanager_* object with 'limit' => 0, the repeating elements cannot be removed
2. If a 'label' is not set on a Fieldmanager_* object with 'limit' => 0, and 'sortable' => true, the repeating elements are not sortable
3. If a 'label' is not set on a Fieldmanager_* object with 'limit' => 0, and 'collapsible' => true, the repeating elements are not collapsible
4. add_more_label should have a default (e.g. "Add more", or even just a simple "+"); if absent, the button is empty

The following code...

$fm = new Fieldmanager_Group( array(
    'name'           => 'repeatable_text',
    'limit'          => 0,
    'sortable'       => true,
    'children'       => array(
        'text_field' => new Fieldmanager_Textfield( 'Repeatable Field' ),
    ),
) );
$fm->add_meta_box( 'Repeatable Text Fields', 'post' );

... will produce this:

"Add More" button can run flush against the next group of fields

When adding a Fieldmanager_Group, and having one group of repeatable fields above another group of fields, there isn't any space between the first group's "Add More" button and the second group. Everything still works, but visually, it's hard to see the distinction in the groups.

Code snippet and screenshot:

$page = new Fieldmanager_Group( false, array(
    'name' => $this->option_name,
    'children' => array(
        $this->meta_tags_option_key => new Fieldmanager_Group( 'Meta Tag', array(
            'limit' => 0,
            'starting_count' => 1,
            'extra_elements' => 0,
            'add_more_label' => 'Add another meta tag',
            'children' => array(
                'name' => new Fieldmanager_Textfield( 'Name', array( 'description' => 'Ex: google-site-verification' ) ),
                'content' => new Fieldmanager_Textfield( 'Content', array( 'description' => 'Ex: 371e9a2594450af0222d7c7bcf6bcfac' ) )
            ),
        ) ),
        $this->refresh_option_key => new Fieldmanager_Group( 'Meta Refresh Interval Values', array(
            'children' => array(
                'default' => new Fieldmanager_Textfield( 'Default Value', array(
                    'description' => 'Used if no values are specified on edit screens for pages or posts.',
                    'validation_rules' => $this->refresh_validation_rules,
                ) ),
                'home' => new Fieldmanager_Textfield( 'Home Page Value', array(
                    'validation_rules' => $this->refresh_validation_rules,
                ) ),
            ),
        ) ),
    ),
) );
$page->add_submenu_page( 'options-general.php', 'Meta Tags' );

Adding image with caption to Fieldmanager_Media field

If you add an image with a caption, the Fieldmanager_Media field will display the shortcode wrapped around the image to the user. The field will still save fine and also will look normal after saving. It will just look broken to the user initially and should be addressed at some point.

Update docs with demos link, update API

For someone just diving into Fieldmanager, this distance between the two examples on the homepage and the API documentation is a bit far.

It would be really useful to have several more annotated examples.

Replace of `sanitize_url()` with `esc_url_raw()`

sanitize_url() has been deprecated since 2.8.0

Javascript validation does not respect display_if

If a field is hidden due to display_if logic, the jQuery validation logic still checks if it a value is present. It should instead ignore the field when hidden.

Add Widget Context

Warning on all tools pages in quickedit branch

On any tools page, even those not created by Fieldmanager:

Warning: Invalid argument supplied for foreach() in /Users/bcampeau/nypost/wp-content/themes/vip/plugins/fieldmanager/fieldmanager.php on line 193

If you drag a RichTextArea's container, it disables the editor

Here's what I've noticed:

• If you drag any one of an editor's containers (it can be its most immediate, all the way up to the meta box), the editor's HTML rendering becomes disabled
• The editor still works in fullscreen mode
• You don't need to re-sort, just dragging the box a single pixel will disable it
• HTML editing mode still seems to work
• There doesn't seem to be any JS errors
• The buttons continue to function

Datepicker with time cannot be saved empty

I have a field of type Fieldmanager_Datepicker with use_time set to true. If I leave the field empty and save the post, the field is saved with the current date and time instead of an empty value. When use_time is false, the field is saved correctly with a value of 0.

Fieldmanager_Datepicker::presave does not check whether time has been entered before using it to save a datetime value.

Before save:

After save:

Show description at the top of the meta box

As a way of introducing the fields in the meta box to the user, I'd like to have the description appear at the top of the meta box, instead of the bottom where it currently is now:

Alternatively, we could come up with another paradigm for "help text" that would be positioned separately.

Fix skipped tests

In order to get the build passing, I marked two tests as skipped in 8ec9d4c. It wasn't immediately obvious whether what they were testing was relevant anymore.

Need to track down the history of these tests and either fix them or remove them.

Javascript vulnerability

You're outputting a potentially unescaped value from the database in javascript at: https://github.com/alleyinteractive/wordpress-fieldmanager/blob/master/php/util/class-fieldmanager-util-validation.php#L260

To fix, just have Fieldmanager_Util_Validation:: format_value do an esc_js for strings. Since strval isn't actually doing anything useful here you can keep it or let it go — it's just turning the value into a string if it happens to be an integer or something. Strings can contain bad javascript though, so we have to escape it.

https://github.com/alleyinteractive/wordpress-fieldmanager/blob/master/php/util/class-fieldmanager-util-validation.php#L311

If it's a boolean or integer we can assume it's safe :)

Add 'default_value' option

This needs to be done in all contexts.

When setting a field's value to be the default, it's important to only set it on "new" fields to distinguish between an unset value and an intentionally empty one. For instance, say you have a "date" field and you set the initial value to the current day. If the user clears the field and saves, the field should remain empty and not get re-populated with the default value. This can be tricky, since the values may be identical in both situations (e.g. coming from get_post_meta).

Consider using jQuery Timepicker for Datepicker->use_time = true

One of the jQuery Timepicker UIs would provide an interface more consistent with the existing Datepicker UI.

Autocomplete with custom datasource requires exact match

If you have a string in your data like "Hello" and you type "hello", it doesn't match. We should implement a simple tokenizer for this in the datasource. The same tokenizer would need to be applied to the autocomplete fragment, using JS, so that it works in both an ajax and non-ajax context.

The tokenizer would at the very least downcase the text. Further enhancements could include:

• removing all punctuation (e.g. typing oreilly would give you o'reilly)
• removing plurals
• normalizing utf-8 chars (for instance, é => e)

Remove fm_json_to_serialized.php if no longer necessary.

Or, if it is, it would be great to convert to a wp-cli command

Fieldmanager_Post should use hidden form fields, not JSON in its own <input>

Using the preview button works, but exposes the JSON. Once you save it again from that screen, the field is wiped out because JSON serialization fails.

Updating indexed fields leaves duplicate stale database record

If you update a field that was previously saved empty, the index postmeta is not updated or deleted. This creates an issue later when retrieving the meta data -- sometimes the old value is fetched.

Reproduce the issue by following these steps:

1. Create a field that is indexed for meta queries, e.g.:
   $event_fields = new Fieldmanager_Group( array(
   'name' => 'event',
   'children' => array(
   'location' => new Fieldmanager_Textfield( 'Location' , array(
   'index' => 'event_location'
   ) )
   )
   ) );
2. Do not enter anything into the field and save the post
3. Enter a value into the field and save the post
4. Look at the database. There will be two records for the meta key in the postmeta table, e.g.:
   [682] => stdClass Object
   (
   [meta_id] => 1115
   [post_id] => 342
   [meta_key] => event_location
   [meta_value] => 0
   )
   [688] => stdClass Object
   (
   [meta_id] => 1121
   [post_id] => 342
   [meta_key] => event_location
   [meta_value] => New Location
   )

Can't remove individual repeatable fields with 'one_label_per_item' => false

When adding this field:

'foo' => new Fieldmanager_Group( 'Meta Tag', array(
    'limit' => 0,
    'starting_count' => 1,
    'extra_elements' => 0,
    'add_more_label' => 'Add another meta tag',
    'one_label_per_item' => false,
    'children' => array(
        'name' => new Fieldmanager_Textfield( 'Name', array( 'description' => 'Ex: google-site-verification' ) ),
        'content' => new Fieldmanager_Textfield( 'Content', array( 'description' => 'Ex: 371e9a2594450af0222d7c7bcf6bcfac' ) )
    ),
) ),

Individual fields that are added to the repeater can't be removed except by deleting the field content.

Clicking the "X" at the top of the screen wipes out all of the fields, even fields not part of that group. Before-and-after screenshots:

Removing 'one_label_per_item' => false fixes the issue.

How do I utilize metadata generated by a Fieldmanager group child?

I love that you've made it so easy to generate repeatable form items!

However, I'm having trouble pulling that data from the $post object. The use case is that I want many "locations" for each "distributor". However, when I access the metadata where I expect to see the content (rich text) of each "location", I get what looks like serialized data (not a pretty JSON string):

Within functions.php:

  $fm_distributor_location = new Fieldmanager_Group( array(
        'name' => 'distributor_location',
        'limit' => 0,
        'label' => 'Distributor Location',
        'label_macro' => 'Distributor Locations',
        'add_more_label' => 'Add another Distributor Location',
        'collapsed' => false,
        'children' => array (
            'location' => new Fieldmanager_RichTextarea( 'Location', 
                array(
                    'index' => 'location',
                ) 
            ),
        ),
    ) );

Within WP template:

$metadata = get_post_custom($d->ID);
$distro_location_array = $metadata['distributor_location'];
var_dump($distro_location_array);

Output:

array (size=1)
  0 => string 'a:2:{i:0;a:1:{s:8:"location";s:106:"<p>Monterey Bay Wine Co. ~ [phone]<br />
<a href="http://www.mbwines.com/">www.mbwines.com</a></p>
";}i:1;a:1:{s:8:"location";s:106:"<p>Monterey Bay Wine Co. ~ [phone]<br />
<a href="http://www.mbwines.com/">www.mbwines.com</a></p>
";}}' (length=286)

What is the preferred method for accessing Child data like this? Thanks for any advice you can provide!!

Best,
jared

Bug with repeating grandchildren ("proto" ends up in field names)

Using the following code to add a meta box,

$fm = new Fieldmanager_Group( array(
    'name'           => 'group',
    'limit'          => 0,
    'add_more_label' => 'Add another group',
    'label'          => 'Group',
    'children'       => array(
        'field' => new Fieldmanager_Textfield( 'Field', array(
            'limit' => 0,
            'add_more_label' => 'Add another field'
        ) )
    )
) );
$fm->add_meta_box( 'Nested Repeatables Bug Demo', 'demo-debug' );

1. Click "Add another group"
2. Populate the text field in the new group
3. Save your post

After you save your post, you'll see that the data doesn't save. The reason why the data doesn't save is that the newly-generated text field has the name group[1][field][proto]. When you repeat a group, all of its descendants are subject to this bug (e.g. adding all this to a group named 'grandparent', the field's name would be grandparent[1]group[proto][field][proto].

Permission issues

Came across two permission issues today:

1. If you have a Fieldmanager_Datasource field which refers to an object that has since been deleted, the post will not save, indicating that the user cannot edit the object.

2. if ( ! current_user_can( 'edit_post', ... appears in a couple of places. It's possible for that to not be the capability to edit a post, if a post type has custom capabilities set. This should be loaded dynamically (see below for demo code), and a code audit should be done to ensure that all could-be-modified capabilities are loaded dynamically.

   $post_type_object = get_post_type_object( $post_type );
   if ( ! current_user_can( $post_type_object->cap->edit_post, ...

   Edit: turns out core does this mapping automatically.

Issues when removing fields or boxes from the middle of a repeatable sortable list

There are a few issues here:

1. Removing a field or group in the middle of a repeatable sortable list leaves a blank gap on save
2. You can't remove the blank gap
3. Removing multiple fields or groups from the middle of a repeatable sortable list causes data loss

To reproduce,

1. Make a repeatable text field:

$fm = new Fieldmanager_Textfield( array(
    'name'           => 'repeating_text_field',
    'label'          => 'Text Field',
    'limit'          => 0,
    'add_more_label' => 'Add another field',
    'sortable'       => true,
) );
$fm->add_meta_box( 'Repeating Text Field', 'demo-text' );

1. Add 4 boxes, fill them with "one", "two", "three", and "four"
2. Save the post.
3. You should now have "one", "two", "three", "four", and a blank field. Remove "two".
4. Save the post.
5. On reload, you should have "one", blank field, "three", "four" (screenshot below)
   
6. Remove the blank field.
7. Save the post.
8. The blank field is still there.
9. Remove "three".
10. Save the post.
11. Now you should have "one", blank field, blank field. "four" is missing, though it wasn't removed.

The source of the bug is the for loop here:
https://github.com/alleyinteractive/wordpress-fieldmanager/blob/master/php/class-fieldmanager-field.php#L400

Hypothetically, this could be converted to be a foreach loop to preserve the original sequence if that's necessary. Alternatively, before save, we could use array_values() to reset the sequence (then a field previously at index 3 might get dropped to index 2).

When using display_if with autocomplete fields, the autocomplete doesn't activate when the field is shown

test core fieldmanager javascript actions using qUnit

http://qunitjs.com/

Post meta getter helper

I've written a helper for a base class like this:

/**
 * Get a given Fieldmanager field
 */
private function get_fm_field() {

    $vars = func_get_args();

    $pm_key = array_shift( $vars );

    $value = get_post_meta( $this->get_id(), $pm_key, true );

    foreach( $vars as $key ) {
        if ( isset( $value[ $key ] ) ) {
            $value = $value[ $key ];
        } else if ( empty( $value[ $key ] ) ) {
            return '';
        } 
    }

    return $value;

}

Usage: $this->get_fm_field( 'project-details', 'background', 'background' )

Would something like this be useful packaged with the plugin?

Repeatable grids don't work

tinymce scripts are loaded on every page, including front-end

TinyMCE should only be loaded on pages where the editor will display. Currently, the scripts load on every page, both in admin and the front-end.

Add ability to store fields as unserialized postmeta using their own meta keys for meta queries

Currently, the data for all Fieldmanager fields which are children of a group is stored as serialized data. This is not friendly for meta queries. We need to add an option to allow a field to store its data in its own meta key for this purpose.

Nonce validation fails when mixing child term and non-child term meta contexts

If a taxonomy has a mix of fields that only appear on certain child terms and those that appear for all terms, nonce validation will fail when saving the form on terms where the optional child fields are not present.

RichTextArea fields in tabs do not work

Term Context has some styling bugs, especially with mp6

1. Radios, checkboxes are on their own line
   
2. Radio buttons are huge on MP6
   
3. Fields are 100% width, which isn't terrible but is inconsistent with the post context
4. Groups are too subtle on MP6
   
5. Buttons are inconsistent with other contexts and are full width (they don't look like buttons, in fact)
   
6. The "New Term" form is too narrow for the full Rich Text Editor, depending on the screen width. Any laptop will cut it off. Not sure if there's a solution to this, unfortunately.
   

Required fields

How do you feel about adding the ability to mark certain fields as "required" (however you might define that)?

Can Fieldmanager_Post use jQueryUI?

Since jQueryUI is bundled with WordPress, I'd rather limit our library dependencies to it—and if it's insufficient for any purpose, I'd rather find an appropriate jQuery plugin so we're not maintaining a dependency on additional library. I've also seen a number of issues with the Twitter Boostrap autocomplete.

Versioning

For other projects that want to depend on Fieldmanager, it would be nice to implement versioning on the project. This would also imply regular "releases" and communicating what's included in the release.

Provide documentation for Fieldmanager

Saw this plugin in the WordPress.com VIP repo. Can I get some more details on what this plugin does?

add_term_form() breaks WXR imports

When wp_insert_term runs, FM checks for a nonce for the term field. Ultimately, WXR wouldn't be the only victim of this; any programmatic use of wp_insert_term() would also trip this. My hunch is that we should check if isset( $_POST[ $this->fm->name ] ) before checking the nonce.

Error & Stack Trace

PHP Fatal error:  Uncaught exception 'FM_Exception' with message 'Nonce validation failed' in wp-content/plugins/wordpress-fieldmanager/php/class-fieldmanager-field.php:839
Stack trace:
#0 wp-content/plugins/wordpress-fieldmanager/php/context/class-fieldmanager-context-term.php(203): Fieldmanager_Field->_unauthorized_access('Nonce validatio...')
#1 [internal function]: Fieldmanager_Context_Term->save_term_fields(3, 3, 'category')
#2 wp-includes/plugin.php(429): call_user_func_array(Array, Array)
#3 wp-includes/taxonomy.php(2209): do_action('created_term', 3, 3, 'category')
#4 wp-admin/includes/taxonomy.php(129): wp_insert_term('test', 'category', Array)
#5 wp-content/plugins/wordpress-importer/wordpress-importer.php(420): wp_insert_category(Array)
#6 wp-content/plugins/wordpress-importer/wordpress-importer.php(113): WP_Import-> in wp-content/plugins/wordpress-fieldmanager/php/class-fieldmanager-field.php on line 839

To Reproduce

1. Add a term form to a taxonomy:

add_action( 'init', function() {
    $fm = new Fieldmanager_Textfield( array( 'name' => 'test_field' ) );
    $fm->add_term_form( 'Test Field', 'category' );
} );

2. Import WXR with a term in that taxonomy. Here's a simple demo:

<?xml version="1.0" encoding="UTF-8"?>
<!-- generator="WordPress.com" created="2013-07-16 21:24"-->
<rss version="2.0" xmlns:excerpt="http://wordpress.org/export/1.2/excerpt/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:wfw="http://wellformedweb.org/CommentAPI/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:wp="http://wordpress.org/export/1.2/">
  <channel>
<title>Theme Unit Test Data</title>
<link>http://wpthemetestdata.wordpress.com</link>
<description>Just another WordPress website with a purposefully really long description</description>
<pubDate>Tue, 16 Jul 2013 21:24:06 +0000</pubDate>
<language>en</language>
<wp:wxr_version>1.2</wp:wxr_version>
<wp:base_site_url>http://wordpress.com/</wp:base_site_url>
<wp:base_blog_url>http://wpthemetestdata.wordpress.com</wp:base_blog_url>

<wp:category>
  <wp:term_id>12345</wp:term_id>
  <wp:category_nicename>test</wp:category_nicename>
  <wp:category_parent/>
  <wp:cat_name><![CDATA[test]]></wp:cat_name>
</wp:category>

  </channel>
</rss>

When a post is deleted, it should clean up its reciprocals

When you add children to a post using a post datasource, it can register a meta entry on each child post referring back to the parent. When a post is deleted, it should clean up those meta entries so that we don't leave references to posts that no longer exist.

As discussed in #61, this is the better way to handle that issue.

Term Meta integration doesn't use taxonomy

The term meta integration looks to depend entirely on term_id, which isn't necessarily unique. It needs to also use the taxonomy (it could use term_taxonomy_id instead, but that's not ideal since it isn't readily available in the current taxonomy API).

RichTextArea is missing icons in MP6 if the main editor isn't present

In a post context without a post_content field, or in any other context, RichTextArea fields are missing icons in MP6.

Convert Fieldmanager_DraggablePost to Fieldmanager_Multipicker

Should use Fieldmanager_Datasource, which could be tags or users. Perhaps also allow the usage of 'limit' instead of assigning it directly, but make it limit the number of things you can drag in.

Autocomplete on users needs enhancement

Autocomplete on users currently uses the get_users() "search" argument. This is quite limited for two reasons:

1. You can't search by display name, which is not only the most intuitive way to search for a user, but it's also what the autocomplete returns. From the Codex, "Use this argument to search users by email address, URL, ID or username (this does not currently include display name)."
2. The searches must be exact, which defeats the purpose of autocomplete. That is, if you're searching for the user "John Smith", whose username is "admin", you would have to type "admin". Typing "admi" would get you nothing. And per the first point, once you type "admin", the autocomplete will say "John Smith".

We should implement a custom search solution for this to resolve both issues.