Official documentation for attachment form fields

Question

I'm trying to use the attachment_fields_to_edit hook to create new fields on media attachments. According to the new documentation, one of the parameters is an "array of attachment form fields".

I can't find, however, where on the documentation are the specs on how to build this array. I found this page on the Codex, but the provided example uses only value, label and helps. I found a few more parameters in the source of get_attachment_fields_to_edit, such as input and html, and in a few tutorials I see required.

add_filter('attachment_fields_to_edit', 'new_attachment_field', 10000, 2);
function new_attachment_field( $form_fields, $post ) {
  $field_value = get_post_meta( $post->ID, 'newfield', true );
  $form_fields['newfield'] = array(
    'value' => $field_value ? $field_value : '',
    'label' => __( 'New Field' ),
    'required' => true,
    'input' => 'textarea',
    'html' => '<no idea what goes here>',
    '???' => '???',
    'helps' => __( 'Help message' )
  );
  return $form_fields;
}

Most are intuitive, except for html. And I don't know if there are more parameters I'm unaware of.

Where can I find more information in the official documentation?

Answer 1

TL;DR : I guess there's no official and complete documentation, not even in the source. html in a $form_fields is used for custom HTML markup, if you decide not use the provided options.

Longer Answer:

Hey @22510, I am not sure I understood your question correctly and I am guessing what you really want to know is what are the mandatory items in the array for a specific item in $form_fields, as you don't need to create it because it already exists, is created by core as you can see in line 1210 of wp-admin/includes/media.php (as WordPress 4.7.4)

Which brings to answer properly. In cases like this, where there no or little documentation, the best course of action is reading the source. But in this instance, the source is not properly documented. Bummmer.

But if you follow the trail inside the code you will notice the purpose of this field.

Example from lines 1216-1220:

    'post_excerpt' => array(
        'label'      => __('Caption'),
        'input'      => 'html',
        'html'       => wp_caption_input_textarea($edit_post)
    ),

Lines 1236-1242:

    'image_url' => array(
        'label'      => __('File URL'),
        'input'      => 'html',
        'html'       => "<input type='text' class='text urlfield' readonly='readonly' name='attachments[$post->ID][url]' value='" . esc_attr($image_url) . "' /><br />",
        'value'      => wp_get_attachment_url($post->ID),
        'helps'      => __('Location of the uploaded file.')
    )

And a little below, on lines 1285-1289:

    $form_fields['align'] = array(
        'label' => __('Alignment'),
        'input' => 'html',
        'html'  => image_align_input_fields($post, get_option('image_default_align')),
    );

You see, when you create a new field, if you don't provide an input value, it will use an text input type. If you do provide a value like 'input' =>'textarea' it will create and textare automatically, but if you 'input' =>'html', then you are telling WordPress to use the markup you will specify in html array item.

So, in media.php lines 1219 and 1285 they use two functions to create this markup, 1239 simply uses an string with some variables.

So, if you will use a normal textarea field, you don't need html:

$form_fields['newfield'] = array(
    'value' => $field_value ? $field_value : '',
    'label' => __( 'New Field' ),
    'required' => true,
    'input' => 'textarea',
    'helps' => __( 'Help message' )
);

But if, for example, you want a photo credits field prepopulated with the post author name, you would use html as the vale for input key and a custom markup string for the html key :

$form_fields['credits'] = array(
    'value' => $field_value ? $field_value : '',
    'label' => __( 'Photo Credits' ),
    'required' => true,
    'input' => 'html',
    'helps' => __( 'Give credits where credit is due.' ),
    'html'  => "<input type='text' class='text credits' name='attachments[$post->ID][credits]' value='" . esc_attr( esc_get_the_author_meta( 'user_nicename', $post->post_author ) ) . "' /><br />",
);

Hope this helps.