This article walks through how to integrate an online volunteer registration with Double the Donation Volunteering.
The integration will collect information during the registration process and log that information with Double the Donation Volunteering after the registration is complete.
Registration Page
Step 1: Include CSS and JavaScript on the page.
Include the following CSS and JavaScript somewhere on the page:
<!--Listing 1-->
<script src="https://doublethedonation.com/api/js/ddplugin.js"></script>
<link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />
Step 2: Insert the streamlined search tool.
Insert the following div element in the form where the streamlined search field should appear. Ensure that it is placed within the form tag of the registration form.
<!--Listing 2-->
<div id='dd-company-name-input'></div>
<script>window.DDCONF = {API_KEY: "360MATCHPRO_PUBLIC_KEY"};</script>
The streamlined search field should appear on the registration form.
As soon as a volunteer starts typing into the streamlined search field, data begins to be captured. The data is stored in hidden input elements in the nearest enclosing form:
-
The volunteer's search text is stored in the doublethedonation_entered_text input element.
-
The search status (e.g., no interaction, entered text, not found, found) is stored in the doublethedonation_status input element.
-
When a company is found, the company ID is stored in the doublethedonation_company_id input element.
This data is stored in the browser's DOM but is not submitted to 360MatchPro from the registration page. Instead, this data must be passed to the confirmation page after the registration form is submitted.
Confirmation Page
Step 1: Include CSS and JavaScript on the page.
Include the following CSS and JavaScript somewhere on the page:
<!--Listing 1-->
<script src="https://doublethedonation.com/api/js/ddplugin.js"></script>
<link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />
Register the donation with Double the Donation using the volunteer_registration JavaScript function that is loaded into the browser in Step 1, OR
Send an API POST request to the volunteer-registration endpoint to send the registration data.
NOTE: You must register ALL registrations with 360MatchPro, even when "doublethedonation_company_id" and "doublethedonation_entered_text" are not available (e.g. when the volunteer skipped the search in the plugin). More information here.
A sample submission follows:
//Listing 2
if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason
doublethedonation.integrations.core.volunteer_registration({
"360matchpro_public_key": "XXXXXXXXXXXXXXXX", // Replace this key with the client's 360MatchPro public key.
"partner_identifier": "XXXXX-123456789", // Replace this with your partner identifier. This will be securely provided to you by the Double the Donation Partnerships Team and is NOT the same as your partner API key.
"campaign": "EY_2024_Fall", // You should use a field that your clients would easily recognize as the volunteering event or campaign.
"registration_identifier": "test-12345", // This is a unique identifier that you must specify.
"event_at": "2025-01-02", // A datetime representing when the volunteering event starts.
"registered_at": "2024-07-01T00:00:00Z", // A datetime representing when the volunteer registered for the event
"volunteer_first_name": "Ben",
"volunteer_last_name": "Ihana",
"volunteer_email": "benihana@test.test"
"volunteer_phone": "123-456-7890",
"doublethedonation_company_id": 50, // Only needed if the volunteer used the streamlined search field.
"doublethedonation_entered_text": "Home Depot" // Only needed if the volunteer used the streamlined search field.
});
};
Reference the Double the Donation Schema for guidance.
In most cases, this code may be placed in the JQuery.ready() callback (if using JQuery) or the DomContentLoaded Event, since the code must execute after the ddplugin.js file (Step 1) is fully loaded and executed.
Step 3: Insert and initialize the volunteer plugin.
Insert the following div element on the confirmation page where the volunteer plugin should appear.
<!--Listing 3 -->
<div id="dd-container"></div>
Include the following code on the confirmation page, replacing some fields as indicated below with the values from Step 2.
//Listing 4
// Initialize the following variable to be the doublethedonation_company_id
// if a streamlined search is used and a company was found. Otherwise, set it to null.
var dtd_selected_company = DOUBLETHEDONATION_COMPANY_ID;
window.DDCONF = {API_KEY: "360MATCHPRO_PUBLIC_KEY", COMPANY: dtd_selected_company, VOLUNTEER_GRANT_SPECIFIC: true};
if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason
doublethedonation.plugin.set_registration_identifier("REGISTRATION_IDENTIFIER"); // Replace with actual identifier or an empty string.
if (dtd_selected_company) {
doublethedonation.plugin.set_company(dtd_selected_company);
} else {
var domain = doublethedonation.integrations.core.strip_domain("VOLUNTEER_EMAIL_ADDRESS") ; // Replace with actual email.
doublethedonation.plugin.email_domain( domain ); // Checks for a company based on the email address.
}
}
If the volunteer selected a company from the streamlined search field or if the volunteer email address has a corporate domain that matches a company entity in the Double the Donation database, the volunteer plugin presents volunteer grant and volunteer PTO information about that company. If not, the volunteer plugin appears blank and prompts the volunteer to select their company. The plugin tracks what the volunteer selects at this stage.
Troubleshooting
Page Reload
We detected input errors on the registration form and refreshed the page. Can we reload the streamlined search tool so that it shows the company that was selected before the volunteer attempted to submit the registration?
Yes. Use the doublethedonation.plugin.set_company_name_input(string) function, calling the function with the search string that the user typed in. If the volunteer had selected a company, call the doublethedonation.plugin.set_company(string) function with the doublethedonation_company_id corresponding to the company selected.
The search text and doublethedonation_company_id are stored in the browser's localStorage. You can use the following code: JSON.parse(localStorage.doublethedonation || "{}"); to retrieve these values. In the JSON, look for the doublethedonation_entered_text and doublethedonation_company_id properties. These properties will be missing if the volunteer does not use the streamlined search tool.
Alternatively, you can find these values in hidden input elements (see Step 3 above) in the DOM.
Dynamically Generated Forms
My registration form is dynamically generated with JavaScript, so the plugin doesn't appear after steps 1 and 2 above. How do I embed the streamlined search in this scenario?
Continue to follow steps 1 and 2 above, but also run the following JavaScript after the registration form has been inserted into the DOM.
if (window.doublethedonation) {
//Load the search into a DOM element with id="dd-company-name-input"
doublethedonation.plugin.load_streamlined_input();
}
// The preceding code block is wrapped in an if statement so your
// page doesn't break if the ddplugin.js script doesn't load for any reason.
Make sure that the preceding code runs after the registration form is inserted into the DOM. Just place the code in an appropriate callback function that will be invoked after the DOM loads. For JQuery users, consider $(document).ready. Otherwise, consider using a browser event like DOMContentLoaded or readystatechange
What if I can't add elements to the HTML markup (step 2 above)?
If you are not able to add <div id="dd-company-name-input"></div> per step 2 above, consider creating the div using JavaScript, attaching it to the DOM, and calling the overloaded load_streamlined_input method, as follows:
//This example uses JQuery, just to keep things simple.
if (window.doublethedonation) {
//Create Element
var streamlined_search = jQuery("<div id='dd-container'></div>");
//Inject element into DOM. Assumes DOM element with id 'placeholder' exists
streamlined_search.insertAfter("#placeholder");
//Call overloaded method, passing in the newly created element
doublethedonation.plugin.load_streamlined_input(streamlined_search[0]);
}
If the streamlined search field is still not appearing on the registration form, load the registration form into your browser. Go into the Developer Tools (F12 on most browsers), and then go into the Console tab. In your console, type doublethedonation.plugin.load_streamlined_input() and press enter. Consider the following outcomes:
-
Outcome: The streamlined search plugin DOES NOT appear, and I get an error that indicates that doublethedonation is not defined.
Try this: Make sure you load ddplugin.js and ddplugin.css per step 1 above.
-
Outcome: The streamlined search plugin DOES NOT appear on the page, and I don't get a console error.
Try this: Make sure there is a div element with id='dd-company-name-input' somewhere in the DOM.
-
Outcome: The streamlined search plugin appeared on the page.
Success: The ddplugin.js script loaded successfully, but there is a timing issue. Consider using the Dynamically Generated Forms method in the Troubleshooting section.
Unlikely async issues:
If you use a third-party site builder platform that allows you to fetch external scripts or write inline JavaScript, the provider may append an async or defer attribute to the external JavaScript file. The defer attribute shouldn't cause problems because it blocks events that you likely rely upon, like the DOMContentLoaded. But the async attribute doesn't block any of these events, so you may have to rely on the window.onload instead. If you suspect that you are having async issues, consider injecting the code in the Dynamically Generated Forms section under Troubleshooting into the callback function of your window.onload event.
In some cases, providers explicitly hard code timeouts to inlined JavaScript code, which may be the source of the async issues. When debugging your code, please be cognizant of this possibility.
If external scripts are not loaded using the async attribute and inline JavaScript isn't wrapped in a timeout function, then you probably are not having async challenges.