Official documentation for attachment form fields

Question

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.

Leave a Comment Cancel reply