Provides a secure "contact" button for your lists and single record displays.
Product Setup
Start by installing and activating the add-on, making sure you also have installed the Participants Database Email Expansion Kit plugin.
Adding a Contact Button
The first step is to add a new “Contact Form” type field for your button on the Manage Database Fields page. You can call it “contact” or anything you want. This will add a contact button to your list and/or single record display in the same way that any other field is shown. You can show it with other fields, or show it alone by using the “fields” attribute of the shortcode.
The contact button is always associated with a single Participants Database record.
For instance, if you are showing a list of records that includes the contact button, each button in the list can send an email based on the information in that record: typically, it will be the email address. So, if your list is a list of club members, clicking on the contact button on a member’s listing could send an email to that member. That is only one example, the configuration of the button is very flexible, many other actions are possible.
The text on the button is configured in the add-on’s settings, but it is also possible to individually configure the button in the “values” section of the field definition on the Manage Database Fields page. This is explained in detail below.
What the Button Does
Once you have added your contact button field and configured it to appear in your list and/or single record display, it will show up as a clickable button. When that button is clicked, a contact form appears in an overlay on the page. This form includes an input for their name, email address and the message they want to send. Optionally, the user can enter a subject line.
When the user clicks the “send” button, the email is triggered with the entered information and also the data from the associated record.
reCAPTCHA
If you have Participants Database reCAPTCHA installed, the form will include an “invisible” recaptcha device that will verify that the user is a human.
To configure the reCAPTCHA for this add-on, you must use “invisible” API credentials, the regular reCAPTCHA v2 credentials won’t work.
Go to your reCAPCTCHA developer page. You will see a list of all your API keys. Under “Site Type” you will see if the key you are using is v2 or Invisible. If the keys you are using are v2, you should create a new set of keys (you can’t change existing keys) for your site, and make sure they are the “invisible” type. Use these new keys in the settings for Participants Database reCAPTCHA. The usual reCAPTCHA on your signup forms will continue to work with the new keys.
If you don’t use reCAPTCHA, the contact forms will still work, but they won’t be protected against automated submissions from non-human users. In many cases, this is OK, the contact forms are not easily detected by bots, or perhaps in your case the page with the contact buttons is not public.
Setting Up the Email
When a users submits the contact form, an “email event” is triggered with the submitted data. For that event to actually send an email, you must use an email template that determines what will be in the email, who it goes to, and all that stuff.
Go to the PDb Email Templates screen and create a new template. Set the Send Action to “Contact Button Email” so that the template will be triggered when the contact form is submitted. Fill out the rest of the template to set up what the content of the email will be and who it will go to.
Using Value Tags
In your template, you can use “value tags” that will be substituted with the values in the form submission. It’s important to understand that the data you will have access to in this template is all the record data from the record that was displayed or clicked on to send the contact email. There will, of course, also be all the information the user entered into the contact form.
To set up a typical contact email where the record the user has selected is the person to whom the contact email is sent, put the participant record email in the Recipient Email space. You can also fill in the Recipient Name with fields from the record as well. (See the screenshot below for what that looks like.)
Information from the contact form uses field names that are prefixed with “pdbcff-” (short for Participants Database Contact Form Field) so that they will not conflict with information from the record. The fields from the contact form that you will be able to use are:
- pdbcff-sender_name
- pdbcff-sender_email
- pdbcff-subject (this is the “Global Subject Line” setting)
- pdbcff-body
The “Body” of the email template would probably contain only the [pdbcff-body] tag, but you could add other text and use the pdbcff-body tag to place the message from the user in the body of the email.
Of course, this is only a starting point. Your template can easily be customized to your particular needs. You can also use the CC and BCC sections to send duplicate emails to other people. It is also possible to place multiple email templates on the same event if you need different emails to go to several recipients.
Defining the Email Subject
Email subjects are an important way to organize incoming emails for the recipient, and with this add-on you have a lot of flexibility in defining the subject of the email. In the add-on settings is a setting for the email subject line. This setting accepts value tags, so you can construct a subject that includes all the information needed to help manage the incoming emails. This means you can include any information from the record the user clicked on.
If you are allowing the user to enter their own subject, that information is available in the tag [pdbcff-subject]. If that tag is included in your subject line setting, the user’s subject will be shown. It is recommended that you also add text to the subject so that the email can be easily identified as coming from the contact form… for instance:
That way, no matter what subject the user enters, the recipient will know this was a submission from the Participants Database contact form.
In the email template, the [pdbcff-subject] tag will show the Global Subject Line.
Using Conditional Sends
The Send on Condition setting can be used to determine if an email template should be used based on the user’s input or data from the record the contact button was attached to.
The typical use for this is if you have more than one contact form. In a setup like that, each contact form field will have a different name. In the conditional setup, one of the fields available is “pdbcff-field” which holds the name of the contact button field that the user clicked on. When you have more than one contact button field, this is how you would attach a different email template to each of your contact button fields.
Field-Specific Configuration Options
Many of this plugin’s configuration settings can be set on a per-field basis by defining the values in the “values” parameter of the contact button field definition on the Manage Database Fields page.
The values are set using the usual syntax for the “values” configuration field. For instance, to set a special title and contact button text, you could use a setting like this:
form_title::Support Request,contact_button::Get Support
Here is the list of options that can be set in the field definition:
- sender_name_label – labels the “sender_name” input
- sender_email_label – labels the “sender_email” input
- message_label – labels the message input
- subject_label – labels the subject input
- subject_line – sets the subject of the email
- placeholder – sets a placeholder text for the message input
- form_title – sets a title for the form
- contact_button – text for the contact button
- submit_button – text for the send button
- sent_message – text shown after a successful send
These configurations can also contain value tags that will be filled with data from the record…for example:
sent_message::your message has been sent to [first_name] [last_name]
F.A.Q.
Can I reposition or hide the Google reCAPTCHA badge?
In the settings, there is a location preference for the badge, but in practice only the “inline” setting is very useful.
You can change the position, size, etc. of the badge when it is in “inline” mode with your own CSS. Be aware that hiding the badge is probably a violation of Google’s terms of use. It may also be a privacy law violation in the EU. Here is a link with some more details on this question.
Can I use the reCAPTCHA without the reCAPTCHA add-on?
Yes, if you use two filters to supply the site key and private key. The filters are:
‘pdbcff-recaptcha_site_key’ for the site key
‘pdbcff-recaptcha_private_key’ for the private key.
If you don’t know how to set up filters, you’re probably better off just using the add-on.
Can I add more fields to the contact form?
Yes, this is possible, you’ll need to have some basic coding ability and a good understanding of HTML form elements.
I’ve written a short tutorial on how to add a phone field to the contact form:
Is it possible to remove the Subject Line and Body from being required in the form? I have attempted to remove them, but I always get the message ‘Message Not Sent’ when they are removed or when they are left blank. If they are left and populated, the message is sent.
I tried to remove them from the array in form_item_definitions()
I have done this successfully in a much earlier version. I have not updated the plugin for a while, but I updated to the latest version and cannot remove them successfully. I am not proficient in php. Any help would be greatly appreciated.
The reason they are requred is that is is not possible to send an email that lacks a body and a subject. Can you describe why you need this?
I apologize for the delay, I was out of the office.
I have set a global subject line and unchecked the user subject line, so that there is not an input field in the contact form. As for the body, I am using additional contact fields plugin to send as the body of the form.
OK, I see that the global subject line feature isn’t working properly. I’ll do some testing with the additional contact fields to see how that can work to replace the body field in the contact form. It looks like I need to issue an update to the Contact Button plugin to fix some issues. You should see that in the next few days.
Oh, another thing: how are you replacing the body of the email with additional fields? I won’t really be able to test this until I can duplicaste what you’re doing there.
Replying to your comments yesterday.
I modified the PDb_Contact_Form_Field.php.
I was able to omit the Subject in the apply_filters array and it will send the message as long I leave the Body/message field in the array and populate in the browser. I changed the type of the Body/Message field to “text” instead of “text area” and moved it above the ‘pdbcff-before_message_area’, in the apply_filters array. I figured I will use the Body/Message field instead of one of the additional fields. Now the only problem I have is that the label that I set up in the Contact Form Settings in the Participants Database Contact Button Settings in WordPress is not being displayed in my form.
I am using the PDb Email templates to send the additional fields information in the body of the email.
OK, well there is an easier way that doesn’t involve modifying the plugins code, which I advise against doing. I am issuing an update to the plugin, when you update, you’ll lose your changes. The message field is not required for sending an email any more, although it will be required in the contact form if present.
A better way to control which of the built-in fields are present in the contact form is to use the pdbcff-form_item_definitions filter, which passes in an array of field definitions that the plugin uses to build the form. To remove a field from the form, you just remove it from the array before returning it. This way, your changes will not be overwritten by plugin updates. You can also use this filter to change the type of field and whether it is required or not. Changes you make this way will not be overwritten when you update and will continue to work.
I’ve added some code that demonstrates the use of this filter in the pdb-contact-form-additions gist.
Thanks for the great database plugin. Really enjoying it so far.
I’ve encountered an odd issue while setting up my contact button, though.
I’ve set up an email address field (Text Line, with “Email” validation) and set it up as my primary email field.
I’ve set up the Recipient Email of the template as “[email]”.
This doesn’t seem to work, though.
WP Mail SMTP gives me an error each time an email delivery is attempted.
The error message is as follows:
“You must provide at least one recipient email address.
Source: /wp-content/plugins/participants-database/classes/xnau_Template_Email.php (line: 143)”
The email delivery works flawlessly when setting a specific email as the Recipient in the template, though. Not with “[email]”, though.
Is this issue related to having set up the primary email adress field wrongly, or does the issue lie in the way the template was set up?
Thanks a lot in advance!
Each contact button that is displayed is attached to a Participants Database record. That record must have an email address in the email field so it can provide the recipient address. Also, make sure the the the tag in the recipient line of the template matches the name of your email address field.
Is there a way to know the location of the page where the contact button was pressed? for example to send the single record id or email if the contact button was pressed from a single record result?
This will require a little php knowledge to set up. It’s possible to add a custom field to your contact form, you can add a hidden field and populate it with the current page. That data will be available to the template, or you can use it as a conditional in your email template.
Adding Fields to the Participants Database Contact Form
I am enjoying your software. It is very well designed.
Is there a convenient way to automatically insert the sender’s name, email address, phone number, etc. from their own record without letting them type in whatever they feel like?
In other words, I want to prevent people from spoofing their name, etc., just let them click on the contact button, select the email template with the desired fields from a dropdown menu, proof the email, and click to send it.
I assume in this case, the user is logged in and so their info is available from their WP user profile.
The plugin does not offer something like this natively. You cqn modify the submission form to omit the fields you want filled in from the user’s profile, and then use a filter to supply the user’s info to the submitted data. If you have the coding skills and want the details on that, let me know.
I have been coding since 1966, but not in php. Generally I use assembly. If you can point me at the hooks, I can pick up php. My biggest problem is that my short term memory is not what it used to be and my eyesight isn’t so great anymore either. LOL.
I am using a MAMP server and SequelPro, so generating SQL is a snap. I have been looking over your database layout with SequelPro and appreciate the design functionality.
Whatever you can do to point me at the hooks would be appreciated.
Regarding the WP profile, the user would only be listed in the Participants Database. I would need to get the data from their record.
The plugin has no way of knowing who the user is unless they are logged in.
The way this contact form works is it gets the data from the currently displayed record (or from the record that was clicked on in a list) as basis for the contact form: the recipient’s info. The user is expected to fill in their own name and email.
I expect to use your login plug-in. Are you saying the login plug in logs the Participant in as a WordPress user or as a Participant Db user?
The Participant Login plugin does not actually log anybody in, it just provides a secure way to edit a record on the frontend.
Now, it does place a cookie on the user’s browser (this is for the persistent login feature), and in theory, you could use that to pre-fill the form, but I have not tried it, so I can’t say how well that will work.
If one can securely modify your own record with a password, I would think that the record could be used to obtain the info about the user.
Can you point me at the cookie for persistent data, etc. as a point of beginning?
In a php script, you can get the current user’s record id with:
$record_id = Participants_Db::$session->get( 'pdbid' );If that returns false, the cookie is not available. If the Participants_Db class is not available, your script is in the wrong context, but just follow normal methods for adding custom scripts to WordPress (a plugin or in the theme), and you’ll be fine.
To get the data from the record, use this:
$record = Participants_Db::get_participant( $record_id );that will give you an associative array of the Participants Database record.
As to modifying the contact form, that is more involved, I did not set up the code to facilitate this kind of modification.
There is a filter pdbcff-form_fields_html you can use to alter the HTML before it is printed. You will need to use string manipulation to alter the form fields.
If you need to alter the data before the email is sent, use the pdbcptet-action_send_email_data_{$template_id} filter, where {$template_id} is the ID number of the email template you’re using.
It sounds like I should force persistent login to be sure the cookie is set or something similar. Al thoughts you have will be appreciated.
The login plugin has a setting “extended access” that will do that.
Hi
The site is for old boys of a school to get in touch.
Sadly many have passed away over time
I would like to make sure the Contact button does not appear for these people now and I have removed the email in the record. Couldn’t see a setting to not show Contact button if no email address.
Thanks in advance
Tony
You bring up a good point, there isn’t any mechanism in place to prevent the contact button showing if there is no destination email….it does make sense it should work that way.
Tony, I just released an update to the Contact Button add-on, there is a new preference that when selected, will not show the contact button if the record’s email address is not defined.