Skip to main content

Giving Forms for Developers

Giving Forms can be configured programmatically on page for exceptional giving experiences.

Written by Tony Sasso

🤓 For Web Developers

The content in this article is for web developers looking to do advanced things with the Funraise Giving Form. For standard form implementations, you'll just follow a few easy steps.

Add Giving Forms to your website

In this article

  1. Embed Code Elements

  2. Placed Forms

  3. HTML Button Attributes

  4. JS Configs

  5. Translations

  6. Event Handlers

  7. URL Parameters

  8. Test Mode

Embed Code Elements

Funraise Giving Form embed code includes three blocks that must be placed in order.

1 | Funraise Aware Code

The Funraise Aware Code enables Funraise features on your website. This code is unique for your Funraise account. Copy your Funraise Aware Code from the publish tab of your Giving Form editor. Place this in the <head> of your site. 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. This can be placed in the site <head> or in the <body> as long as it's placed below the Funraise Aware Code.

3 | Button Code

A form can be launched with an HTML button. Place the in your page <body> where you want the button to appear. You can use your own buttons to launch the form by adding a single attribute: data-formId="xxxxx".‍ You can also place a form open on your page; we’ll cover this option below.

All together now!

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

Sandbox Example ↗

<head>
  <!-- Funraise Aware Code -->
  <script>
    (function(f,u,n,r,a,i,s,e){var data={window:window,document:document,tag:"script",data:"funraise",orgId:f,uri:u,common:n,client:r,script:a};var scripts;var funraiseScript;data.window[data.data]=data.window[data.data]||[];if(data.window[data.data].scriptIsLoading||data.window[data.data].scriptIsLoaded)return;data.window[data.data].loading=true;data.window[data.data].push("init",data);scripts=data.document.getElementsByTagName(data.tag)[0];funraiseScript=data.document.createElement(data.tag);funraiseScript.async=true;funraiseScript.src=data.uri+data.common+data.script+"?orgId="+data.orgId;scripts.parentNode.insertBefore(funraiseScript,scripts)})("67790fed-aa86-4965-b00d-0138ace5c5bd","https://assets-demo-2.funraise.io","/widget/common/2.0","/widget/client","/inject-form.js");
   </script>
</head>
<body>
  <!-- Form Configuration Code -->
  <script>
    window.funraise.push('create', {form: 271});
  </script>
<!-- Button Code -->
  <button type="button" data-formId="271">Click Me</button>
</body>

Config Heirarchy

Much of this documentation details advanced 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

Placed forms

In almost all cases, we recommend the popup variation of the form because it has a high conversion rate and is mobile responsive out-of-the-box. You can also choose to use the placed variation, which will embed the form open, directly into your page layout.

Sandbox Example ↗

Placed forms may require some additional configuration based on your needs.

Placed form types


In most cases, you'll use grow_contained

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

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.

Sandbox Example ↗

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.

Sandbox Example ↗

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.

Sandbox Example ↗

HTML Button Attributes

Launch a form with custom defaults adding HTML data attributes to your launch buttons. 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.

For example, the button code below will launch a form with an amount of $50 and a frequency of monthly preselected:

<button data-formId="xxxxx" data-amount="50" data-frequency="m">Donate</button>

Good to know: You can also pass values to the form via URL parameters — very easy! We have a non-developery article where you can learn about using URL Parameters with the Giving Form.

Attribute

Details

Code Sandbox

Allocation

data-allocation=“FormAllocationID”

  • Allocation must exist on the form.

  • Form Allocation Ids are form-specific. To access the Form Allocation Id, open a form's editor and find the form's allocations.

Sandbox ↗

Amount

data-amount=“xxxx”

Sandbox ↗

Ask String

data-ask=“x,x,x,x”

Sandbox ↗

Frequency

data-frequency=“m”

  • Frequency must exist on the form.

  • o=one-time, w=weekly, m=monthly, q=quarterly, y=yearly.

Sandbox ↗

Minimum

data-minAmount="xxxx"

Sandbox ↗

Maximum

data-maxAmount="xxxx"

Sandbox ↗

Transaction Tags

data-tags=“xxxx”

  • In addition to any tags set in platform

  • For multiple tags use # as a delimiter, for example: data-tags="#tag1#tag2"

Sandbox ↗

Tickets

data-tickets=“[ticketId]|[qty],[ticketId]|[qty]”

  • Launches the form with specific tickets and quantities selected

  • To default a Ticket selection, the Ticket must be added to the form in platform.

Sandbox ↗

JS Configs

You can also set default form values with javascript with the Form Configuration Code. JS configs are slightly more advanced than a simple button attribute. These configurations allow for extra control per form instance. For example, you may want to use a single form, but configure one form uniquely based on the page it’s added to. JS configs can be used with a popup form or with a placed form.

Good to know: You can also pass values to the form via URL parameters — very easy! We have a non-developery article where you can learn about using URL Parameters with the Giving Form.

Config

Details

Code Previews

Allocation

defaultValues: { 
  allocation: xxxxx,
}

  • Allocation must exist on the form.

  • Form Allocation Ids are form-specific. To access the Form Allocation Id, open a form's editor and find the form's allocations.

Sandbox ↗

Amount

defaultValues: { 
  amount: x,
}

Sandbox ↗

Ask String

defaultValues: { 
  ask: 'x,x,x,x',
}

Sandbox ↗

Currency

payment: {
  currencies: {   
    USD: { "$",
      defaultAmount: 45,
      defaultButton: 4,
      presets: [25,45,125,250],
      name: 'USD'
    },
    CAD: {
      symbol:"$",
      defaultAmount: 35,
      defaultButton: 4,
      presets: [15,35,100,200],
      name: 'CAD'
    },
    GBP: {
      symbol:"£",
      defaultAmount: 25,
      defaultButton: 3,
      presets: [10,15,25,50],
      name: 'GBP'
    }
  }
}

  • 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.

  • Tickets will always use your platform currency and can not have multiple currencies configured.

Sandbox ↗

Frequency

defaultValues: { 
  frequency: 'm',
}

  • Frequency must exist on the form.

  • o=one-time, w=weekly, m=monthly, q=quarterly, y=yearly.

Sandbox ↗

Min/Max

validations: { 
  minAmount: 50,
  maxAmount: 500,
}

  • If you are using multiple currencies on your form, you can set a min/max for each currency.

Sandbox ↗

Page Goal

pageId: "5032dfba-548d-43a7-beeb-536a9df75f69"

  • 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.

Sandbox ↗

Transaction Tags

defaultValues: { 
  tags: 'exampleTag',
}

  • In addition to any tags set in platform

  • For multiple tags use # as a delimiter, for example: tags:'#tag1#tag2'

Sandbox ↗

Tickets

defaultValues: { 
  tickets: '[ticketId]|[qty],[ticketId]|[qty]',
}

  • Launches the form with specific tickets and quantities selected

  • To default a Ticket selection, the Ticket must be added to the form in platform.

Sandbox ↗

Ticket Limits

ticketOptions: [
  { id: xxxxxx, limit: x },
  { id: xxxxxx, limit: x },
],

  • 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.

Sandbox ↗

Translations

☝️ Funraise Giving Forms are automatically translated into the following languages: English, Mandarin Chinese, French, Hindi, Italian, Portuguese, and Spanish. The form will automatically display the appropriate language based on the browser’s language setting (window.navigator.language). You do not need to apply any translation configurations for these languages.

You can use the translation configuration to change a single phrase on the form or to provide additional languages for the form.

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.

Sandbox Example ↗

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.
​
Common uses of event handlers:

Event

When

Properties

onSetup

Called when the donation form is loaded on a page

None

onInfo

Called when the donor submits the contact information screen of the form

Donor

onSuccess

Called when a transaction completes successfully

Donor & Donation

onFailure

Called when a transaction fails

Donor & Donation

Donation propertires

  • 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

Donors propertires

  • donor.address

  • donor.city

  • donor.country

  • donor.email

  • donor.firstName

  • donor.lastName

  • donor.phone

  • donor.postalCode

  • donor.state

  • donor.ua

Did this answer your question?