Product Setup

This plugin is primarily for the purpose of expanding the WordPress user account to include additional information which the user (or administrator) can edit on their profile page. It  provides several ways to connect a Participants Database record to a WordPress user. This works whether you already have WordPress users, or you have Participants Database records, or even if you have nothing to start with.

Start by Defining Your Data Fields

Unless you already have your Participants Database fields defined, you need to first set up the fields of data that will be stored with the user’s profile.

To do that, go to the Manage Database Fields page in Participants Database and define the fields you want for your users. Using field groups, you can define fields that are public, private (for the user only) or admin (only site admins will be able to see these). Once the fields have been defined, you can configure how it interacts with WordPress users and user registration.

You can define as many or as few extra fields as you want. Participants Database comes with a set of predefined fields, these can all be deleted if you don’t need them.

Link Key Participants Database Fields to WordPress Account Fields

There are a few key fields in the WordPress user account that are usually linked to fields in the Participants Database record. This establishes synchronization between the two on these fields: First Name, Last Name, Email, User Login, and User Avatar (also known as the Profile Picture). It is not absolutely necessary to set up these fields, but it can be helpful to be able to see the user’s name, etc. in the Participants Database record.

To set this up, go to this plugin’s settings under the “WordPress User Profile/Participants Database Record Settings” heading. This is where you can determine which Participants Database fields relate to the core fields of the WordPress profile. In most cases, the defaults will be OK.

When a new WP user account is created from a Participants Database record (either an existing record or a new signup), the information in these fields will be used. The User Login field can be used as a way to let user determine their own user login name (this works for new signups only). In most cases, if this field is configured, it is for the purpose of showing the username in the PDB record.

Creating WordPress User Accounts

If you want new WP user accounts to be created automatically (there are several ways this can happen), check the “Create New WordPress User Settings.” If you want the new users to get a welcome email, make sure “Send the WordPress New User Email” is checked. If you’ve got the Email Expansion Kit installed, you can also define your own welcome email. If you’re doing that, you can uncheck the setting so only the custom email gets sent.

Creating WP User Accounts with a Signup Form

If you’re starting from nothing with your membership, or you want to let new members register, you can use the Participants Database signup form to provide a way for your new members to sign up. This is enabled using the “Create New WP User Mode” setting in the PDb User Profile plugin settings.

When a Participants Database signup form is submitted, you can set it up so that the person registering will be given a WP account. You can also set it up so that when they register, it stores their info but does not set up the WP account until the registration is approved by an administrator.

When the registration is approved, the info from the signup is used to create the new account. The Participants Database record is now associated with the new WP account.

The signup form can have as many fields as you like, so your new accounts can be established with a full set of information. The one exception is you cannot use the PDb signup to establish the password as explained below.

Note that when this setting is used, a logged-in user won’t see the signup form because they already have an account.

User Account Passwords

When using a Participants Database signup form to create new WP accounts, you cannot use a PDB password field to set the password on the new account. This is because WordPress requires that new accounts be verified via email with a link that forces them to create a password. User account passwords are handled by WordPress, not Participants Database.

Creating WordPress User Accounts on Approval

If you want to be able to approve the new user before granting them an account, you can use the approving records mechanism to create the user account. When a record is approved, a new WP user account will be created using the info in the signup submission. This can also be used to turn the user’s account access on and off. If a record id unapproved, the user won’t be able to log in. If the record is approved again, they will regain access.

If you have WP User accounts already, if you use this feature, be sure to set the approval field to default to “approved” so that your existing users won’t get deactivated.

Creating WordPress User Accounts Manually

If you’ve got people in Participants Database and you want to establish WordPress user accounts for them, you can easily do that on the admin List Participants page. Select the records you want to establish WP user accounts for, then select “create WordPress user account for record” then confirm the operation by clicking “apply.”

Select the users you want to establish accounts for, then use the “with selected” dropdown to select “Create WordPress user account for record” and click “apply.” Each of the people who got new user accounts will be sent the welcome email (with the login link) if you have that configured. It is probably a good idea to test this on a single user before doing it for a lot of them.

Starting with Existing WordPress Users

If you have WordPress users already registered and you want to give them expanded information storage in their account profile, it’s very easy. When the user visits their profile page, a new Participants Database record is created for them if it did not exist before. All the extra information that they enter on the profile page will be added to that record, which is now fully connected to the WP user.

The Profile Page

WordPress has a built-in profile page on the backend that is accessible to users where they can edit their profile info. This plugin can add Participants Database fields to that profile page. This is configured in the plugin settings under the “User Profile Settings” heading. There is a checkbox that enables this functionality.

You can also control which groups of Participants Database fields are shown in the profile. There is another setting where specific fields can be excluded.

When a logged-in WP user visits their profile page, the matching Participants Database record is used to add the extra fields. If there is no record for the user the “Create PDb Record for WP User” option creates a new record for them. That record is now attached to the WP user, and will be used to store their information.

Frontend Profile Page

If you want your users to be able to access their profile on a regular website page (instead of an admin page), you can do that using the [pdb_user_profile] shortcode. Just select or create a page for your profile and put the shortcode on that page. This is perfect if you don’t want your users going to the backend to edit their profile.

When the frontend profile page is set up, the plugin automatically changes the user’s profile link to point to this page instead of the default profile page in the backend.

There are two built-in templates for the frontend user profile page. The default template is a responsive layout based on the Bootstrap framework. There is also a flexbox-based layout that can place the fields in columns and will generally be more compact. You can use the flexbox template by adding the name of the template to the user profile shortcode like this:

[pdb_user_profile template=frontend-profile-flexbox]

The frontend profile uses the same configuration settings as the backend profile page. The layout and appearance of the profile page is under the control of your WP theme. If you need to make changes to its appearance, you will need to use your own CSS rules to make the desired changes. The main Participants Database plugin has a place for your custom CSS rules in the settings.

It is also possible to create a custom template for the frontend user profile. The name of the template file must begin with “pdb-record-frontend-profile” and must be based on one of the two frontend profile template included in the plugin.

Using a Custom “Welcome” Email

If you have the Email Expansion Kit installed, you can easily create a custom email that goes out to the user when a new account is set up for them. If you are notifying your users this way, you should uncheck the “Send the WordPress New User Email” setting to avoid sending two emails.

When creating the email template, use the “WordPress User Profile:: New WP User Created” action to send a notification to the new user that they have a WP User account and need to activate it using the activation link.

This email must contain the “activation link” so that the user can activate their new account. This is a security feature that allows you to avoid putting a plaintext password in the email.

The user must visit the site using the activation link, where they will need to create a new password for themselves.

Here is an example content for your welcome email template:

If you do want to send them the plaintext password, you can use the tag [user_pass]. They will be able to use that with their user login to log into the account immediately without changing their password.

Showing a List of Users

You can use the Participants Database list shortcode to show a list of your users, showing only users with a specific role. For example, to list all the subscribers, use

[pdb_list role="subscriber"]

You can also name more than one role there, for example:

[pdb_list role="subscriber,member"]

This will work to show both subscribers and members if you have a custom role named “member.”

Showing the Current User’s Record

It is possible to show the current user’s record in a non-editable form by using the Participants Database single record shortcode. This is done by using the “current_user” key for the record_id shortcode attribute, like this:

[pdb_single record_id=current_user]

Of course, you can use the other available shortcode attributes to configure the display, including using a custom template.

Product Settings

User Profile Settings

Show PDb Fields in WP Profile

This is the overall enable switch for including the extra fields defined in Participants Database in the WordPress user’s profile page.

Profile Groups

Select which Participants Database field groups to include in the profile page. Only public and private groups will be available here.

Profile Excluded Fields

If there are specific fields within the selected field group that you wish to exclude, list them here. It should be a comma-separated list of Participants Database field names.

PDb Profile Title

This title is printed above the extra fields that Participants Database adds. Blank it out to show no title.

Create PDb Record for WP User

This determines whether a participants Database record should be assigned to the WP user if they visit their profile page and there is no PDB record associated with their account. In most cases, you will want this checked.

WordPress User/Participants Database Record Settings

These settings set up a correspondence between the key fields of the WordPress profile and the Participants Database record. These settings are optional, the plugin does not use these fields to determine which record belongs to the user. They are helpful, however, because it provides a readable way to know which WP user the PDB record belongs to.

These are configured by default to connect to the default fields in Participants Database if they exist.

First Name Field, Last Name Field, Email Field

These setting tell the plugin which PDB fields are connected to the WP user profile fields. In most cases, you won’t need to change these, they will be set up by default.

User Login Field

This setting provides a way to store the user login name in the PDB record. If the site was previously configured to use the user login as a way to identify which user the record belonged to, this setting should set that up automatically. This works by looking for a hidden field in the PDB field definitions that is set up to record the user’s user login name in a signup form.

User Avatar Field

This provides a way for the user to use a “local” avatar for their profile. Normally, WordPress would attempt to get the user’s avatar from Gravatar, but with this feature, the user can upload an image to use instead or if they don’t have a Gravatar image configured. This image will be used to identify the user anywhere on the site that the avatar is displayed.

This selection must be an “Image Upload” type field.

Create New WordPress User Settings

It is possible to use this plugin as a way to set up a WP user account for someone who is in a Participants Database record. This can happen in several ways, and these setting determine how that will work.

When a new WP user account is created, an email is sent to the person informing them of their new account, along with information to go to the site and set up their password. They will not be able to log in until they do this. This is standard WordPress functionality, but it can be overridden when using the Email Expansion Kit.

Create New WP User Mode

There are 3 ways a new WP user account is created in this plugin. This setting determines which one you want to use. If you don’t want WP user accounts to be created at all, use the “Manual” setting (which is the default).

When a new WP account is established by any method, an email is sent to the new account holder with their login instructions.

With the Manually setting, new WP user accounts can be created for people in Participants Database by using the “With Selected” function on the admin List Participants page. Note that you can always use the “With Selected” action, no matter what setting you have here.

The On Signup setting means that the WP user account is established immediately when the signup form is submitted.

The On Approval setting also works with the signup form, but instead of establishing the WP account immediately, it only does so when the record is approved. (See Approving Records for how this is configured in Participants Database). This setting also means that if you approve an unapproved record that was already in the database that does not have a WP account assigned to it, a new WP account will be created.

New WP User Role

This determines the role given to new WP users that are created by this plugin. If you  have custom roles defined, you will be able to assign new users to a custom role.

New User Login Name Source

When a new WP user is created, the account is given a username. This setting determines what information will be used to set up the account user name.

If you have a user login field defined, it is possible to let the person signing up determine their own username. The plugin will make sure it is unique.

Usernames cannot be changed once established.

There are 4 options for how the username is constructed:

• First or Last Name – this will use the first name if possible, then the last name if the first name isn’t available as a username.
• First and Last Name –  the first and last name will be combined to create the username.
• Email Field – the user’s email address is used to create the username: the “@domain” part is removed and what is left is the username.
• User Login Field –  this makes it possible for the user to set their own username, this is only possible in the signup form.

If the selected method creates a username that is alredy set for another user, a numeral is added to the username to make it unique.

Joining Character

When building the username, this setting sets the character that is used to join the parts together. This character is also used if a numeral is added to the username. “No Character” means the parts are joined together with nothing in between. The setting is limited to characters that are allowed in a username.

Send the WordPress New User Email

This preference determines whether the WordPress standard “welcome” email is sent to the new user when the account is established. If you are using the Email Expansion Kit to define a custom email for this purpose, you can uncheck this to prevent the built-in WordPress email from getting sent.

If you just don’t want that email going out at all or at a later time, you can uncheck this.

It’s always possible to resend the “welcome” email using the “With Selected” function on the admin List Participants page.

Deactivate WP User when Unapproved

When a record is unapproved (if it was approved before it was unapproved) the WP user account can be deactivated at the same time. The account is not deleted, it just becomes inactive and the person won’t be able to log in. This is done by setting the deactivated user’s role to “None.” If the record is approved again, the account will be reactivated, using the New WP User Role setting above to restore the user’s role.

Handle WP User Account on PDB Record Delete

When a Participants Database record is deleted, this setting determines what happens to the associated WP user account.

Deactivate means the account still exists, but the user will be unable to log in. Choose this if you think you may want to give the user access again in the future.

Do Nothing means they can still log in, but note that when they visit their profile page, a new Participants Database record will be created for them. The plugin doesn’t try to prevent that.

If you set it to Delete, the associated WP account will be deleted along with the PDB record. Admin accounts and accounts that have authored posts will not be automatically deleted.

Deactivated Account Message

This lets you define the error message that is shown to the user when they try to log in while their account is deactivated. You can include some simple HTML here.

F.A.Q.

Is it possible to use this add-on with Field Group Tabs to provide a tabbed interface for the frontend profile?

Yes, it requires the use of a special custom template. I’ve created an example of how this can be done, the template is available below.

Please read Using Participants Database Custom Templates so you understand how to install and use this custom template.

To use the template, set up your shortcode like this:

[pdb_user_profile template=frontend-profile-tabs tabs=true ]

You must (of course) have the Field Group Tabs add-on installed for this to work.

https://gist.github.com/xnau/e4480bb20d7d58d65dbb37535f5ea970