Giving Form V2

Good to Know
The example code on this page is for demo purposes only. Be sure to copy form code directly from your platform and then configure using the tips below.
Looking For Form v1?
Form V1 is a deprecated legacy version of the form that is no longer supported or suggested. You can access the Form V1 documentation here.

Elements of the Form Code

Funraise Giving Form embed code provides an infrastructure for dynamic and scalable donation experiences across your entire site. The unique elements of the form code make that possible.
1 | Funraise Aware Code
The Funraise Aware Code enables Funraise features on your website. This code is unique for your Funraise account. You'll copy your Funraise Aware Code from the publish tab of your Giving Form editor. Place this in the <head></head> of your pages. Only load this code once on a page.
2 | Form Configuration Code
The Form Configuration Code creates or configures a particular form on a page. Place this in the <head></head> of the page below the Funraise Aware Code. You can add JS configs to the Form Configuration Code to prefill or default items for a particular form instance.
3 | Button Code
A form can be launched with an HTML button. Place this in your page <body></body> where you want the button to appear. You can add attributes to a button to open the form with prefills or defaulted items. You can edit the inline styles of the default button or use your own buttons. Add data-formId="xxxx" to a button to target a particular form.

You can also place a form open on your page; we’ll cover this option below.

Example Form Embed

This complete example follows the steps above for best practices when embedding a form on your page. This form uses the button launcher.

Placed Form

A form can also be embedded open on your page. You can copy the placed form code elements from your Giving Form Publish page.
Placed form Display Types
grow_contained
  • Form appears where it’s inserted into the page
  • Content below the form will be pushed as the form height changes throughout the donation flow
  • Recommended for most donation pages
grow_overflow
  • Form appears where it’s inserted into the page
  • Content below the form will be overlapped as the form height changes throughout the donation flow
overlay
  • Form appears centered as the topmost layer on your page
  • Good option when you want to center the form over a fullscreen background image or video
overlay_background
  • Form appears centered as the topmost layer on your page
  • Similar to overlay, but with a fullscreen color overlay behind the form
  • This is most like the normal popup version of the form
Show button on mobile
The placed form is not responsive on mobile like the popup form. On mobile, you may want to hide a placed form and show a popup button instead. This example uses CSS media queries.
Align a placed form
If you're inserting the form into your page layout (and not using an overlay method), the form has no alignment styles. You can align the form by targeting the element inside the placed form container <div></div>. The example below shows a centered placed form.
Squarespace Ajax loading
Squarespace offers Ajax loading, which can interfere with the rendering of a placed form. If your Squarespace site has Ajax enabled, you can use the method below to ensure your forms render as expected.

Config Hierarchy

Much of this documentation details further configurations for your forms. Because there are many ways to configure your forms, the hierarchy of how each level of configuration is applied is important. Configurations at a lower level will not override those at a higher level (1 overrides all, 2 overrides 3 and 4, etc.) Configurations are applied in the following order:
  1. URL parameters
  2. HTML button attributes
  3. JS configuration
  4. Form settings in platform

HTML Button Attributes

Launch a form with custom prefills and defaults using HTML button data attributes. For example, you might want to open the same form with two buttons: donate now and donate monthly. This is easy to accomplish with the frequency attribute.

Allocation

Default the Allocation by adding data-allocation=“xxxx” to your launch button. Use the Allocation Id for the value. To default an Allocation, the Allocation must be added to the form in platform.
Form Allocation Ids are form-specific. To access the Form Allocation Id, open a form's editor and find the form's allocations.

Amount

Default the amount by adding data-amount=“xxxx” to your launch button.

Ask String

Default the ask string by adding data-ask=“x,x,x,x” to your launch button.

Frequency

Default the frequency by adding data-frequency=“x” to your launch button. Use o, w, m, q, and y for one-time, weekly, monthly, quarterly, and yearly. To default a frequency selection, the frequency must be added to the form in platform.

Min/Max

Set the minimum and maximum amounts allowed by adding data-minAmount="xxxx" and/or data-maxAmount="xxxx" to your launch button.

Payment Method

Default the payment method by adding data-paymentmethod=“xxxx” to your launch button. Available options include: card, check, paypal, bitcoin. To default a payment method, the payment method must be added to the form in platform.

Transaction Tags

Add transaction tags to a form with data-tags=“xxxx” in your launch button. Tags added through a button are in addition to tags set in platform.

Tickets

Launch the form with specific tickets and quantities selected by adding data-tickets=“xxxx|1,xxxx|2” to your launch button. The format for this attribute is “ticket id|quantity,ticket id|quantity,…” To default a Ticket selection, the Ticket must be added to the form in platform.

JS Config

You can set default form values with javascript in the Form Configuration Code. This will initiate the form with your set defaults. These configurations allow for extra control per form instance. For example, you may want to use a single form, but configure this form uniquely based on the page it’s added to.
Good to Know
These examples are using a button launcher to open the form, but you can also use JS configs for a placed form.

Allocation

Default the Allocation by adding allocation:xxxx to your form config code.
Form Allocation Ids are form-specific. To access the Form Allocation Id, open a form's editor and find the form's allocations.

Amount

Default the Allocation amount by adding amount:xxxx to your form config code.

Ask String

Default the ask string by adding ask:'x,x,x,x' to your form config code. The ask string is the four suggested donation amounts.

Currency

By default, your form uses your platform currency. You can override the default currency or add multiple currencies to your forms. You can also configure the ask string for each currency.

Be sure to check that your payment gateway can process the currencies you make available on your form.

Frequency

Default the frequency by adding frequency:'x' to your form config code. Use o, w, m, q, and y for one-time, weekly, monthly, quarterly, and yearly. To default a frequency selection, the frequency must be added to the form in platform.

Min/Max

Set the minimum and maximum amounts allowed by adding minAmount: xxxx and/or maxAmount: xxxx to your form config code.
Min/Max per currency
If you are using multiple currencies on your form, you can set a min/max for each currency.

Page Goal

By default, the native Giving Form on a Campaign Site adds Transactions to the appropriate goal progress bars on your site. You can additionally configure any form to impact a site’s progress bar by assigning a Page Id to the form.

Payment Methods

Default the payment method by adding data-paymentmethod:'xxxx' to your form config code. Available options include: card, check, paypal, bitcoin. To default a payment method, the payment method must be added to the form in platform.

Tags - Transactions

Default the Transaction tags captured with a Transaction by adding tags:'x' to your config code. Tags added through the config code are in addition to any tags added to the form in platform.

Test Mode

You can conduct test transactions through a "live" form by adding  mode: 'test' to your form configuration code. With a test transaction you can view the donor experience and test marketing automation scripts added to your event handlers. Please note:  Transaction and Supporter records are not created with test transactions. As well, donation receipts are not sent with test transactions.

Tickets

Default the form with specific tickets and quantities selected by adding tickets:'xxxx|1,xxxx|2' to your form config code. The format for this attribute is 'ticket id|quantity,ticket id|quantity,…' To default a Ticket selection, the Ticket must be added to the form in platform.

Ticket Limits

You can limit the quantity of a particular Ticket that can be purchased with a single Transaction. For example, you might have 10 sponsorship tickets, but you only want to allow one sponsorship ticket to be purchased at a time. Please note: The purpose of this configuration is to limit quantity PER transaction. The overall number of Tickets available is set in platform.

Translation

Each phrase of the Giving Form can be overridden. Use this feature to change a single phrase or to provide additional languages for the form.
When translating a form, provide phrases for each language you wish to make available. The form will automatically display the appropriate language based on the browser’s language setting(window.navigator.language).
When using language codes, we recommend only defining the root language tag and not including a region subtag. For example use en, not en-US. When you only declare the root language tag, your text overrides can be applied to a variety of region subtags.
When greater specificity is required, you can define a region subtag. When a region is defined, your text override will only apply to exact language code matches.

More

Event Handlers

Use Event Handlers, onSetup, onInfo, onSuccess, and onFailure to run custom functions or pass data to other systems. Pass donor and donation properties into your custom functions as arguments, based on the stage of the donation process.

For example, you might use Event Handlers for marketing analytics and tracking.
Events
onSetup
  • Called when the donation form is loaded on a page
onInfo
  • Called when the donor submits the contact information screen of the form
  • Donor properties passed in as arguments
onSuccess
  • Called when a donation succeeds
  • Donor and Donation properties passed in as arguments
onFailure
  • Called when a donation fails
  • Donor and Donation properties passed in as arguments
Properties
These properties can be passed through Event Handlers.
donation.amount
donation.anonymous
donation.baseAmount
donation.comment
donation.company
donation.companyId
donation.companyMatch
donation.currency.name
donation.currency.symbol
donation.dedicationEmail
donation.dedicationMessage
donation.dedicationName
donation.dedicationType
donation.formAllocationId
donation.formId
donation.formName
donation.frequency
donation.transactionId
donation.organizationId
donation.pageId
donation.paymentType
donation.recurring
donation.referrer
donation.sourceUrl
donation.tipAmount
donor.address
donor.city
donor.country
donor.email
donor.firstName
donor.lastName
donor.phone
donor.postalCode
donor.state
donor.ua

Redirection

With Event Handlers, you can redirect the donor to a new page after a successful donation. This can be used for a special "Thank You" page or for analytics tracking. Please keep in mind, as with all custom implementations, this is only an example and not all browsers will treat this the same way. Be sure to fully test your unique solution.
Please Note
  • Bitcoin can not be redirected with this configuration. In the example below, we've applied a redirection rule to all payment methods except Bitcoin.
  • Legacy PayPal Integrations (PayPal connections made before 9/1/21) also need to be excluded from a redirection onSuccess. With a Legacy PayPal integration, you can add a redirection link for a PayPal transaction from within the Giving Form editor. PayPal connections made after 9/1/21 can be redirected with the example below.

URL Parameters

You can default form values with URL parameters. Add one or many parameters to the end of your URL to configure form defaults. To default allocation, frequency, payment method or tickets, the item must be added to the form in platform.
Form Allocation Ids are form-specific. To access the Form Allocation Id, open a form's editor and find the form's allocations.
Parameters
  • x_allocation=12345 (Allocation Id)
  • x_amount=500
  • x_ask=5,10,15,20
  • x_frequency=x (o=one-time, w=weekly, m=monthly, q=quarterly, y=yearly)
  • x_tickets=xxxx|3,xxxx|4 (format: ticket id|quantity,ticket id|quantity,…)
  • x_tags=example (For multiple tags use # as a delimiter, for example: tags: '#example1#example2')
  • x_paymentmethod=card (options: card, paypal, check, bitcoin)
  • x_firstName=Janis
  • x_lastName=Wallis
  • x_email=janis%40example.org
Examples
Single parameter
  • example.org?x_frequency=m
Multiple parameters
  • example.org?x_amount=50&x_frequency=m&x_firstName=Janis&x_lastName=Wallis