This quick tutorial shows how to collect custom metadata for submitted files.

Supported meta data

Forms that enable users to upload files may also collect metadata for each file. Specifically, the following meta information may be included with each submitted file:

  • Caption – the caption for the file
  • Alt Text – alt text for the file
  • Description – a description of the file
  • File Name – the name of the file*
  • Media Title – the title of the file

* This refers to the File Name displayed in the metadata panel on the Edit Media screen; it does not refer to the actual name of the file itself.

Here is a screenshot showing custom Caption, Alt, and Description. And another showing custom File Name and Media Title.

Add Metadata to Submitted Files

If your form allows only one file to be uploaded, then you can include metadata fields in two steps:

Step 1

Include three custom-field shortcodes in the form.

[usp_custom_field form="123" id="1"]
[usp_custom_field form="123" id="2"]
[usp_custom_field form="123" id="3"]
[usp_custom_field form="123" id="4"]
[usp_custom_field form="123" id="5"]
Step 2

Define these custom fields using the following values:

data-required#true|name#alt-1|for#alt-1|placeholder#Alt Text|label#Alt Text
data-required#true|name#desc-1|for#desc-1|placeholder#Description|label#Description
data-required#true|name#caption-1|for#caption-1|placeholder#Caption|label#Caption
data-required#true|name#filename-1|for#filename-1|placeholder#File Name|label#File Name
data-required#true|name#mediatitle-1|for#mediatitle-1|placeholder#Media Title|label#Media Title

That’s all there is to it. Once set up, the form will display three new fields (Alt Text, Caption, and Description). Once the form is submitted, these fields will be used as the metadata for the submitted file (see screenshot). Additionally, the caption and description will be attached to the submitted post.

Multiple files

You can also collect metadata when uploading multiple files, although it’s a bit tedious to set it up. For each file, add a new set of three custom fields. Each set of three custom fields should specify the same file number. For example, here are the custom field definitions for Alt Text, Caption, and Description for three file uploads:

data-required#true|name#alt-1|for#alt-1|placeholder#Alt Text 1|label#Alt Text 1
data-required#true|name#desc-1|for#desc-1|placeholder#Description 1|label#Description 1
data-required#true|name#caption-1|for#caption-1|placeholder#Caption 1|label#Caption 1

data-required#true|name#alt-2|for#alt-2|placeholder#Alt Text 2|label#Alt Text 2
data-required#true|name#desc-2|for#desc-2|placeholder#Description 2|label#Description 2
data-required#true|name#caption-2|for#caption-2|placeholder#Caption 2|label#Caption 2

data-required#true|name#alt-3|for#alt-3|placeholder#Alt Text 3|label#Alt Text 3
data-required#true|name#desc-3|for#desc-3|placeholder#Description 3|label#Description 3
data-required#true|name#caption-3|for#caption-3|placeholder#Caption 3|label#Caption 3

Notice that the first three lines specify 1 for the name, for, placeholder, and label. Thus, these lines refer to the first image. Likewise, the next three lines specify 2, which refers to the second image, and the last three lines specify 3, which refers to the the third image.

Again, this may be tedious to set up, but it can enable your visitors to provide their own metadata for uploaded files.

Setting default values for Media Title and File Name

If you would like to set a default value for the Media Title and/or File Name, you can hook into usp_mediatitle_default and/or usp_filename_default, respectively.

Caveat

As of USP Pro version 1.7, this technique works only when:

  • Using the “Add Another File” method of submitting files (when uploading a single file OR multiple files)
  • Using either method (“Add Another File” or the select field) to upload a single file

To understand how this works, consider the default [usp_files] shortcode:

[usp_files class="" placeholder="" label="" required="false" max="" link="" multiple="yes" method="" key="" types=""]

Notice the method attribute? That is where you specify how the files field should be displayed. You can leave it blank to use the “Add Another File” method (i.e., method=""), or you can give it a value of “select” to use a <select> field (i.e., method="select"). Another way of saying this is that custom metadata cannot be added when using the following attributes:

[usp_files method="select" multiple="true"]   = Select/dropdown field for multiple files

So any of these will work:

[usp_files method="select" multiple="false"]   = Select/dropdown field for single file
[usp_files method="" multiple="true"]          = "Add Another File" for multiple files
[usp_files method="" multiple="false"]         = "Add Another File" for single file

For more information about the different attributes and methods, check out the [usp_files] shortcode reference.