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”.
| 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.
textarea
The “textarea” field type will generate a <textarea></textarea>
field.
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.
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.
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.
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')
.
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.
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.
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:
- the location of the new field
- 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.