Adding Fields

This page provides documentation on how to add fields, including the allowed field types, locations, and settings for fields.

It involves two steps: 1. create a new PMProRH_Field object with an array of properties and options then 2. add the field using pmprorh_add_registration_field() hook.


Creating Fields: Using the PMProRH_Field class

The PMProRH_Field class has various options for different types of fields, but there is a set of general options which applies to every type.

Fields are added via the PMProRH_Field object with 3 parameters:

  • The name attribute. This is the meta key that is used when storing the field value in the wp_usermeta table. The name must only contain letters, numbers, and underscores (no spaces, dashes or special characters).
  • The field type.
  • An array of options. There are some options that apply to every field type, and some that are unique to specific field types. See below for more details.

Available Field Types


Options that apply to all field types:

Option NameDescriptionParameters (default)
namename attribute of the field. This will override the name previously set when declaring the PMProRH_Field object. Must start with a letter and not include any spaces or special characters other than _.user_meta key
idCustom id attribute for the field.string
addmemberIf the PMPro Add Member Admin plugin is activated, this field will also show up in the form under Memberships –> Add Member.bool (false)
classCustom class attribute for the field.string
requiredMake this field required.bool (false)
labelCustom <label> for the field or ‘false’ to hide the label. If not specified, the name will be used.string
levelsShow this field only for certain levels. Takes either a single membership level ID or an array of membership level IDs.int or array
memberslistcsvShow this field on the CSV export when using the “Export to CSV” feature on the Members List page in the WordPress dashboard.bool (false)
readonlyMake this field read-only (uneditable).bool (false)
dependsMake this field dependent on another field. See Conditional Fields.array
profileShould this field also be shown in the profile? Valid values are false, true, “admin”, “only”, or “only_admin”.

  • Use false to hide the field from the user profile page.
  • Use true to show the field on the profile page for both users and admins.
  • Use admin to show the field on the profile page to admins only.
  • Use only to show the field only on the profile page to users and admins. The field will not be shown at checkout.
  • Use only_admin to show the field only on the profile page for admins. The field will not be shown at checkout. Users will not see the field in the admin.
mixed (false)
showrequiredShow the asterisk(*) next to the field if it is required.bool (true)
showmainlabelShow the <label> for the field.bool (true)
divclassCustom class attribute for the field’s containing <div> element.string
hintDisplay a hint under the field.string
html_attributesAdditional HTML attributes to be included in the field output (i.e. ‘placeholder’).array
Note: If you are using BuddyPress and our BuddyPress Integration you can sync profile fields with xProfile fields using the buddypress option.

Specific Options by Field Type

text

The “text” field type will generate an <input type="text"> field.

Option NameDescriptionParameters (default)
sizesize attribute of <input> fieldint

textarea

The “textarea” field type will generate a <textarea></textarea> field.

Option NameDescriptionParameters (default)
rowsrows attribute of <textarea> fieldint (5)
colscols attribute of <textarea> fieldint (80)

select, select2, and multiselect

The “select” field type will generate a <select></select> field. The “select2” field type will generate a multi-select field with autocomplete. A multiselect field will show a list of options in a fixed height field. This field requires an array of options with the format array('option_value' => 'Option Label'). A default “blank” option can be added by passing a blank option value.

Option NameDescriptionParameters (default)
optionsArray of <option></option> elements as described above.array
multipleAdd the multiple attribute, allowing multiple options to be selected at once. Has no effect with “select2” or “multiselect” field types.bool (false)

checkbox

The “checkbox” field type will generate an <input type="checkbox"> field. If the “text” option is not provided, the main label will be next to the checkbox. If the “text” option is provided, a separate, additional label will be shown next to the checkbox.

Option NameDescriptionParameters (default)
textCustom <label></label> for the checkbox.string

checkbox_grouped

The “checkbox_grouped” field type is more like a select/dropdown type than a checkbox. It will generate a grouped list of multiple checkbox options. Requires an array of options with the format array('option_value' => 'Option Label'). Unlike the select and select2 fields, this field type is multiselect by default and cannot be made to choose just one value.

Option NameDescriptionParameters (default)
optionsArray of <option></option> elements as described above.array

radio

The “radio” field type will generate an <input type="radio"> field. It requires an array of options with the format array('option_value' => 'Option Label').

Option NameDescriptionParameters (default)
optionsArray of <option></option> elements as described above.array

file

The “file” field type will generate an <input type="file"> field. By default, uploaded files are saved to the “wp-content/uploads/pmpro-register-helper/user_login/” directory.

Option NameDescriptionParameters (default)
acceptAdd the accept attribute.string

html

The “html” field type will generate any HTML you wish. The name attribute of any element within the given HTML will be used for the field’s value.

Option NameDescriptionParameters (default)
htmlThe custom HTML code to display for the field.string

number

The “number” field type will generate an <input> field that has a toggle to increment or decrement the value of the field.


date

The “date” field type will generate a <select> with dropdown options for month and day then a text input field for a 4-digit year value.


hidden

The “hidden” field type will generate an <input type="hidden"> field.


readonly

The “readonly” field type will show just the value of the $field.


Conditional Fields

Any registered field can be dynamically hidden or shown with JavaScript depending on another field’s value. To create a conditional field, pass an array of conditions as the depends option. The depends array should contain an array of conditions formatted like array(array('id' => {field_name}, 'value' => {field_value}))


Adding Fields: Using the pmprorh_add_registration_field() function

Now that you have created your fields, you need to add the registered fields to the checkout and profile pages. This is done via the pmprorh_add_registration_field() function.

pmprorh_add_registration_field() parameters:

  1. the location of the new field
  2. the PMProRH_Field object itself

By default, you can place a new field in one of 8 different locations:

  • after_username
  • after_password
  • after_email
  • after_captcha
  • checkout_boxes
  • after_billing_fields
  • before_submit_button
  • just_profile – The field will only be shown on the Edit User/Profile pages. To use this, “profile” must be set to either true or admin.

Visual Reference: Checkout Locations Visual Reference: Profile Locations


Checkout Boxes

You can add additional locations for your fields called checkout boxes. Each checkout box is its own <table> element like the Billing Fields or Username Fields sections, and has its own label and description. By default, new checkout boxes are displayed in the order they are added and have the label “More Information”.

To add a new checkout box, use the pmprorh_add_checkout_box function. It takes 4 parameters:

  • the ID of the checkout box
  • (optional) the label for the checkout box (Default: “More Information”)
  • (optional) the description for the checkout box
  • (optional) the order of the checkout box

Then add fields to these boxes.

Checkout boxes can be reordered by passing an integer for the order.