Introduction

The following article will explain how to use JavaScript to install the Quick Action Donation Form.  To see an example of a form embedded using Javascript, click on the Donate Now button on this site

Instructions

1. Loading the Quick Action Form:

   The following code shows how to initialize your Quick Action Forms

   <script type="text/javascript">

       CE_API.SetApiKey('Your API Key');

       CE_API.AddListener('Authenticated', function () {

               CE_API.DonationForm.Load(Your Form Id, function () { console.log('loaded call back'); });
    });

       CE_API.AddListener('AuthorizationDenied', function () { console.log('authentication failed'); });

   </script>

   
   Note: You must also add your website domain name(s) to the list of authorized applications in order for the API key to work. To learn more about installing the CharityEngine Web API, click here.

2. Opening the Quick Action Form:

   The following code shows how to open Quick Action Forms

   <script type="text/javascript">

       CE_API.DonationForm.Show();

   </script>

   
   

   For example, you can add the Show method to a button's onclick attribute to show the form:

   <button onclick="CE_API.DonationForm.Show()">Donate Now</button>

3. Closing the Quick Action Form:

   The following code shows how to close Quick Action Forms

   <script type="text/javascript">

       CE_API.DonationForm.Hide();

   </script>

4. Show/Hide Giving options on the fly:

   <script type="text/javascript">

       CE_API.DonationForm.EnableOneTimeGiftOption();
       CE_API.DonationForm.DisableOneTimeGiftOption();
      
       CE_API.DonationForm.EnableMonthlyGiftOption();
       CE_API.DonationForm.DisableMonthlyGiftOption();

   </script>

5. Additional Configuration:

   You can also set the banner image, default frequency, show/hide giving options, or set custom messaging using Javascript before loading the form:

   <script type="text/javascript">

       CE_API.DonationForm.BannerImageUrl = 'https://the.url.of.the.image.you.want.to.use.com';
      
       CE_API.DonationForm.DefaultGiftFrequencyId = 0; //one-time is set as default
       CE_API.DonationForm.DefaultGiftFrequencyId = 4; //monthly is set as default
   
       CE_API.DonationForm.ShowOneTimeGiftOption = false; //hide the one-time option (both options show by default)
       CE_API.DonationForm.ShowMonthlyGiftOption = false; //hide the monthly option
   
       CE_API.DonationForm.SetCommunicationOptInLabel('Opt-In Label');
   
       CE_API.DonationForm.SetSuccessMessage('Custom Receipt Message');
       CE_API.DonationForm.SetFailureMessage('Custom Failure Message');
   

   </script>
   

   
   
   

   You can also assign funds:
   
   Below, the AvailableFundsList property is a comma separated list of fund aliases and fund ids. The Id values must be valid fund ids but the Aliases can be whatever you want to appear on the form.

   <script type="text/javascript">

       CE_API.DonationForm.ShowFundDesignationOption = true; //optional - default true
   
       CE_API.DonationForm.FundDesignationMode = 'single'; //optional - default multiple
   
       CE_API.DonationForm.AvailableFundsList = 'Test Fund 1=1234,Test Fund 2=5678'; //required to define funds
   

   </script>

   
   
   Lastly, you can assign custom codes:

   <script type="text/javascript">

       CE_API.DonationForm.CustomCode1 = 'code 1';
   

       CE_API.DonationForm.CustomCode2 = 'code 2';
   
       ...
   

       CE_API.DonationForm.CustomCode8 = 'code 8';

   </script>

Quick Action Forms API Events 

Whether you are troubleshooting your installation or customizing the functionality of CharityEngine’s Quick Action Forms , the following API events make either task easy and make the CharityEngine Framework extremely extensible.
To listen to any event, just add an event listener to your JavaScript Code as follows:

The following events are available for Quick Action Forms:

1. Authenticated
2. AuthorizationDenied
3. FormLoaded
4. DonationFormClosed
5. DonationSucceeded
6. DonationFailed

Adding Conversion Tracking

The following example shows how to add conversion tracking code to your website when a successful donation is processed on a CharityEngine Quick Action Form.

To learn how to install the embeddable form using HTML, click here.