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 Name	Description	Parameters (default)
name	name 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
id	Custom id attribute for the field.	string
addmember	If the PMPro Add Member Admin plugin is activated, this field will also show up in the form under Memberships –> Add Member.	bool (false)
class	Custom class attribute for the field.	string
required	Make this field required.	bool (false)
label	Custom <label> for the field or ‘false’ to hide the label. If not specified, the name will be used.	string
levels	Show this field only for certain levels. Takes either a single membership level ID or an array of membership level IDs.	int or array
memberslistcsv	Show this field on the CSV export when using the “Export to CSV” feature on the Members List page in the WordPress dashboard.	bool (false)
readonly	Make this field read-only (uneditable).	bool (false)
depends	Make this field dependent on another field. See Conditional Fields.	array
profile	Should this field also be shown in the member profile when a user is logged into their account? Valid values are false, true, “admin”, “only”, or “only_admin”. Use false to hide the field from the user profile page when a member is logged into their account. 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 when they are logged into their accounts 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 when they are logged into their accounts.	mixed (false)
showrequired	Show the asterisk(*) next to the field if it is required.	bool (true)
showmainlabel	Show the <label> for the field.	bool (true)
divclass	Custom class attribute for the field’s containing <div> element.	string
hint	Display a hint under the field.	string
html_attributes	Additional HTML attributes to be included in the field output (i.e. ‘placeholder’).	array
save_function	A custom function that adjusts how the value is saved. Read this article for an example method of using the attribute.	string

---

Specific Options by Field Type

text

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

Option Name	Description	Parameters (default)
size	size attribute of <input> field	int
value	pre-populate a field’s value if not set for the current user	string (optional)

---

textarea

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

Option Name	Description	Parameters (default)
rows	rows attribute of <textarea> field	int (5)
cols	cols attribute of <textarea> field	int (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 Name	Description	Parameters (default)
options	Array of <option></option> elements as described above.	array
multiple	Add 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 Name	Description	Parameters (default)
text	Custom <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 Name	Description	Parameters (default)
options	Array 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 Name	Description	Parameters (default)
options	Array 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 Name	Description	Parameters (default)
accept	Add the accept attribute.	string
preview	Whether to display a preview of file (image-type fields only).	bool (false)
allow_delete	Option to allow users to delete their uploaded file. Valid values are false, true, or “only_admin” (default). Use false to disallow file deletion. Use true to allow users and admins to delete files. Use only_admin to only allow file deletion for admins only.	mixed (only_admin)

---

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 Name	Description	Parameters (default)
html	The 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 with a dropdown option for the month field and then text input fields for the day and a 4-digit year value. Optionally specify the “value” attribute to pre-populate a field’s value if not set for the current user.

A date value will be recorded even when the user does not complete the date fields. To require a date to be entered by the user, use this snippet:

---

hidden

The “hidden” field type will generate an <input type="hidden"> field. Optionally specify the “value” attribute to pre-populate a field’s value if not set for the current user.

---

readonly

The “readonly” field type will show just the value of the $field. Optionally specify the “value” attribute to pre-populate a field’s value if not set for the current user.

---

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.