This tutorial explains how to define and add custom custom fields to any USP Pro form. This advanced feature of USP Pro makes the plugin vastly extensible, enabling you to integrate your custom form fields with other plugins and scripts.

Video Tutorial

Check out more video tutorials for USP Pro »

Written Tutorial

What is a *custom* custom field?

By default, when you add a custom field to your form, USP Pro will prefix it with usp-custom-. So for example, let’s say that we want to add the following custom field to our form:

data-required#true|name#animal

This custom field will add a field named “animal” to the form. So when the form is submitted, the resulting post will have a custom field attached. The name of this custom field will be usp-custom-animal, because of USP’s auto-prefixing.

So, if you need to add a field named “animal” without any auto-prefix, you can use a custom custom field. Here are the steps.

Step 1

Visit the plugin settings: Advanced ▸ Custom Custom Fields, and enter the name of your custom field in either the “Optional” or “Required” setting. You can add multiple field names separated by a comma. Remember to save your changes.

Important: your custom field names must NOT begin with usp- or usp_ (these are reserved for default custom fields). Custom field names may contain lowercase/uppercase alphanumeric characters, plus underscores and dashes.

Step 2

Return to your USP Form. In the custom-field definition (located below the form content editor), add the following attribute:

name#animal

After saving changes, everything will be set. You can now add the custom field to your form using its shortcode. Once this is done, any posts that are submitted via your form will have a custom field named animal attached (without any usp-custom- prefix added).

Example

To help solidify the concept, here is an example, where we add three custom custom fields to a USP Form. First, we decide which fields we want to include, let’s say:

  • shoes
  • socks
  • pants

We want to include these required fields in the form, and we do NOT want USP Pro to automatically prefix the field names with the default, usp-custom-. So we visit Advanced ▸ Custom Custom Fields and enter the following in the “Required” field:

shoes, socks, pants

After saving the changes, we return to our USP Form. On the “Edit Form” screen, we scroll down a bit to just beneath the form-content editor field. There we find the form’s “Custom Fields” panel. In that panel, we should see any existing custom fields, for example something like this:

[usp_custom_field form="123" id="1"] => data-required#true
[usp_custom_field form="123" id="2"] => data-required#true
[usp_custom_field form="123" id="3"] => data-required#true

At this point, we can either add some new custom fields, or we can simply use the existing custom fields if they aren’t already being used. For this example, we’ll say the existing fields are not used, so we can just modify their values with our custom names:

data-required#true|name#shoes
data-required#true|name#socks
data-required#true|name#pants

After saving changes, we can add these fields to the form using their respective shortcodes. Continuing with our example, we would add the following custom-field shortcodes (note that the form and id attributes will be different depending on your setup):

[usp_custom_field form="123" id="1"]
[usp_custom_field form="123" id="2"]
[usp_custom_field form="123" id="3"]

After adding our three custom custom fields to the form and saving changes, we’re all set. Whenever the form is submitted, these fields will be required, and their values will be attached to the submitted post as the following custom fields:

shoes => sandals
socks => none
pants => cargo

Notice the names of these custom fields: they are not prefixed with the default usp-custom-. So you can do things like integrate with Advanced Custom Fields.

Resources