Online Volunteer Registrations (Required for Online Volunteer Management Platforms)

This article walks through how to integrate an online volunteer registration with Double the Donation Volunteering.

Registration Form

Confirmation Page

Troubleshooting

Page Reload

The integration will collect information during the registration process and log that information with Double the Donation Volunteering after the registration is complete.

Registration Form

Step 1: Include CSS and JavaScript on the page. 

Include the following CSS and JavaScript somewhere on the page:

1. <!--Listing 1-->

2. <script src="https://doublethedonation.com/api/js/ddplugin.js"></script>

3. <link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />

Step 2: Insert the streamlined search field. 

Call this function to load the streamlined search tool in a specified DOM element. 

1. <!--Listing 2-->

2. doublethedonation.plugin.v2.load_streamlined_search(dom_node, public_key, config);

Arguments

1. dom_node (HTMLElement, required): The HTML element where the streamlined search tool will be rendered.
2. public_key (string, required): Public key for the organization's Double the Donation account.
3. config (object, recommended): A configuration JSON object that may contain the following keys:
   • on_text_changed (callback function, highly recommended): A callback function triggered on each keystroke as the user types into the search input field. The function receives the current input value as its only argument.
   • on_company_changed (callback function, highly recommended): A callback function triggered when a company is selected or changed in the search results. The function receives an object representing the selected company as its only argument.

The streamlined search tool's data is not submitted to Double the Donation from the registration page. Instead, capture it using the on_text_changed and on_company_changed callbacks and pass it to the confirmation page after the registration form is submitted. 

Confirmation Page

Step 1: Include the CSS and JavaScript on the page. 

Include the following CSS and JavaScript somewhere on the page. 

1. <!--Listing 3-->

2. <script src="https://doublethedonation.com/api/js/ddplugin.js"></script>

3. <link href="https://doublethedonation.com/api/css/ddplugin.css" rel="stylesheet" />

    

Step 2: Transfer data to Double the Donation. 

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. 

A sample submission follows:

1. //Listing 4

2. if (window.doublethedonation) { // Don't break your page if our plugin doesn't load for any reason

3. doublethedonation.integrations.core.volunteer_registration({

4.     "360matchpro_public_key": "XXXXXXXXXXXXXXXX",    // Replace this key with the client's Double the Donation public key.

5.     "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.

6.     "campaign": "EY_2024_Fall", // You should use a field that your clients would easily recognize as the volunteering event or campaign.

7.     "registration_identifier": "test-12345", // This is a unique identifier that you must specify.

8.     "event_at": "2025-01-02",   // A datetime representing when the volunteering event starts.

9.     "registered_at": "2024-07-01T00:00:00Z",    // A datetime representing when the volunteer registered for the event

10.     "volunteer_first_name": "Ben",

11.     "volunteer_last_name": "Ihana",

12.     "volunteer_email": "benihana@test.test",

13.     "volunteer_phone": "123-456-7890",

14.     "doublethedonation_company_id": 50,    // Only needed if the volunteer used the streamlined search field.

15.     "doublethedonation_entered_text": "Home Depot"    // Only needed if the volunteer used the streamlined search field.

16.     });

17. };

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 workplace giving company search plugin. 

Call this function to load the plugin in a specified DOM element. 

1. <!--Listing 5 -->

2. doublethedonation.plugin.v2.load_plugin(dom_node, public_key, config);

Arguments

1. dom_node (HTMLElement, required): The HTML element where the streamlined search tool will be rendered.
2. public_key (string, required): Public key for the organization's Double the Donation account.
3. config (object, recommended): A configuration JSON object that may contain the following keys:

• registration_identifier (string, recommended): A unique identifier for the volunteer registration record. This is used to track volunteer actions on the plugin.
• dtd_company_id (integer, optional): Preloads the plugin with a company ID from Double the Donation’s database. Used primarily to load the plugin with the company that was selected on the streamlined search. See on_company_changed in Donation Form -> Step 2 above.
• sections (array of strings, optional): An array containing the name of the workplace giving program details you wish to display. The order of the array determines the rendering order, with the first section listed appearing at the top of the plugin and the next section listed appearing below it, etc. Currently available options: "match" and "volunteer." For volunteer platform integrations, “volunteer” should be listed as the first section in this array. The “match” section is optional if you would like to display matching gift program information in addition to volunteer grant information.
• prioritize_available_programs (boolean, optional, default=false): Overrides the order in the sections array to prioritize sections with available workplace giving programs. If all sections have available programs, the order in the sections array is preserved. For example: If the sections array is ordered with the "volunteer" section first and the "match" section second, but the company selected does not have a volunteer grant program and does have a matching gift program, setting "prioritize_available_programs" to "true" will display the matching gift section first.
• size (string, optional): Renders either the "small" or "large" version of the plugin. The "large" version provides more visual design for program details but occupies more space. The "small" version, with more plain-text program details, is recommended for modal-style forms or mobile-first platforms. By default, the plugin is responsive and will load in the most appropriate size for the container. 
• on_text_changed (callback function, optional): A callback function triggered on each keystroke as the user types into the search input field. The function receives the current input value as its only argument.
• on_company_changed (callback function, optional): A callback function triggered when a company is selected or changed in the search results. The function receives an object representing the selected company as its only argument.

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 workplace giving plugin presents information about that company. If not, the workplace giving 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. Pass the search string that the user typed as the company_name property in the config (refer to Registration Form -> Step 2 -> Arguments). If the volunteer had selected a company, pass the doublethedonation_company_id corresponding to the company selected to the dtd_company_id property in the config.

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 and will be cleared after the volunteer registration is registered to avoid overlap with future transactions. If needed, ensure you access this data from localStorage before registering the volunteer registration during Confirmation Page -> Step 2.

Code Example

<!DOCTYPE html>
<html lang="en">
<head>
   <script src="/api/js/ddplugin.js"></script>
</head>

<body>
<div>
   <div>
       <div id="plugin"></div>
       <div id="streamlined-search"></div>
   </div>
</div>

<script>
   var public_key = "N2I1ODhjY2UtZTJh";

   function text_changed_callback(entered_text){
       console.log("Entered: " + entered_text);
   };

   function company_selected_callback(company){
       console.log("Company Selected");
       console.log(company);

   };


   // Load streamlined search
   var search_elem = document.getElementById("streamlined-search");
   var search_config = {
           "dtd_company_id": 50,   // Home Depot
           "on_text_changed": text_changed_callback,
           "on_company_changed": company_selected_callback};
   doublethedonation.plugin.v2.load_streamlined_search(search_elem, public_key, search_config);

   // Load plugin
   var plugin_elem = document.getElementById("plugin");
   var plugin_config = {
           "registration_identifier": "id-1",
           "dtd_company_id": 50,   // Home Depot
           "on_text_changed": text_changed_callback,
           "on_company_changed": company_selected_callback,
           "size": "large",
           "sections": ["volunteer," “match”],
           "prioritize_available_programs": true};
   doublethedonation.plugin.v2.load_plugin(plugin_elem, public_key, plugin_config);
</script>

</body>
</html>