We have a few recommendations for developing forms using Bloomeang.js or starting from the beginning.
To use Bloomerang.js, we recommend this process:
- Create a form within Bloomerang.
- Put the form in Self-Hosted mode and copy the generated code.
- Tweak the functionality of the form as you desire. See Bloomerang.js for reference.
From the Beginning
If you really want to start from the beginning, here is the general process and some things to remember.
Create the Form in Bloomerang
Bloomerang needs to know about your form. If the form processes donations, it needs to know which processor it should use. Create a form within Bloomerang first.
Include Bloomerang.js in Your Page
<script> tag on your website page that pulls in the newest version of Bloomerang.js. To get the correct version:
- Open the form you created.
- Put it in Self-Hosted mode.
- Copy the URL from the code.
Initialize the Form
Make sure Bloomerang.js is fully loaded. Then call
to register your form with Bloomerang.js.
If you are developing a transaction form, also call:
Register Bloomerang Event Handlers
Define handlers for the following Bloomerang-fired events.
Bloomerang fires this just before the form is submitted. This is where you call all the appropriate data functions to set information for the account, donation, custom fields, and so on. Perform any validation here. If the function returns false, the donation is cancelled.
All Bloomerang forms on the page will fire this event. This is a problem if you have multiple forms on the same page (such as an email sign-up form and a donation form). In this case, you need to do two things:
- When the form is loaded, define your own
OnSubmit function specific to this form.
- When submitting the form, set
Blooomerang.Api.OnSubmit to be your form’s
Bloomerang fires this when the form is successfully submitted. Here you display whatever thank-you message you want to show the constituents.
Bloomerang fires this if there is an error and the submission is not successful. The
Message property of the response argument tells you what the problem is. You may display this error message to the constituent or log it for your own purposes. Call
Bloomerang.cancelFinancialSubmission() if you want the constituent to be able to retry the submission.
Define Your Submit Handler
Add a submit handler to your form to set everything up before submitting the form using Bloomerang.js.
If you are developing a transaction form, your submit handler must:
Keep these things in mind when developing your form:
- Wait for Bloomerang.js, Spreedly.js, jQuery, and any other dependencies to load before you enable the form. Otherwise, constituents may see errors and be unable to donate. For this reason, basic Bloomerang forms aren’t shown on the page until everything is ready to go.
- Multiple forms on the same page can cause problems. For example, each form has its own
Bloomerang.Api.OnSubmit handler. However, only the last one is used. If the page must have multiple forms, make sure they don’t interfere with each other when calling functions on Bloomerang.js.
Test your forms thoroughly before putting them on a public site. See Test Forms with Interactions and Test Forms with Transactions.