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.
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:
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.
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_ (these are reserved for default custom fields). Custom field names may contain lowercase/uppercase alphanumeric characters, plus underscores and dashes.
Return to your USP Form. In the custom-field definition (located below the form content editor), add the following attribute:
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).
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:
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
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.