This quick tutorial shows how to collect custom metadata for submitted files.
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 (note: 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)
- Media Title – the title of the file
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.
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
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
As of 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 class="" placeholder="" label="" required="false" max="" link="" multiple="yes" method="" key="" types=""]
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 field for multiple files)
So any of these will work:
[usp_files method="select" multiple="false"] (select 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.