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:

  1. 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).
  2. The type of field. Included field types are:
    • checkbox
    • checkbox_grouped
    • date
    • file
    • hidden
    • html
    • multiselect
    • radio
    • readonly
    • select
    • select2
    • text
    • textarea

  3. 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.

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 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)
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’). string

These options are specific to field type.

text

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

Option Name Description Parameters (default)
size code>size attribute of <input> field int

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 and select2

The “select” field type will generate a <select></select> field. The “select2” field type will generate a multi-select field with autocomplete. Both fields require 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” 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

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

hidden

The “hidden” field type will generate an <input type="hidden"> 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.