Skip to main content

Configuration

Puzzle pieces (icon)

Change all the things!

Customise the donate form presentation & behavior.

This reference describes all the ways you can configure the donate form.

If you want a quick visual overview and to test these out, have a play with the "knobs" in our storybook.

For more real life examples, you can also see the demos.

There are two ways to configure how the donate form appears. You'll configure most settings directly on the page via HTML attributes, and/or override via URL parameters. For instance, you might set data-amount=10 to ask for a $10 donation by default, but set the URL parameter amount=20 when you want to override that with an ask for $20 when linking to the page.

URL Parameters​

Examples:​

$42 once

https://greenpeace.org.au/donate/?amount=42

$25 every 4 weeks https://greenpeace.org.au/donate?amount=25&intervalCount=4&interval=weekly

Amount​

The Donate Form can be pre-filled with an amount in dollars, via amount URL parameter.

The legacy/DEPRECATED parameter amt should not be used, because we prefer URLs whose meaning is clear.

Frequency​

The form defaults to asking for a one-off donation.

To instead ask for a recurring gift, you specify the time between payments via a combination of a count (like "4") and a interval (like "weekly") which multiply together (4 * "weekly" = 4 weeks).

So to ask for a 4-weekly donation via URL params: intervalCount=4&interval=weekly.

The legacy/DEPRECATED freq parameter should not be used, because we prefer URLs whose meaning is clear. For historic record: freq=1 is a one-off, and freq=2 is recurring at the default interval/count (which is 4-weekly, but don't rely on this).

URL parameters will override the HTML config. So you generally set the HTML config to data-frequency=once (or omit it; this is the default value) and then override it via the URL parameters, for example for 4-weekly: intervalCount=4&interval=weekly.

Data Attributes - Commonly Used:​

Common usage of the donate form will use some or all of these settings.

id​

string

This is required. It must be "gpap-donate-widget".

Setting the HTML id of the <div> to this specific value above lets our form loader know to insert the form in this exact location on the page.

Example​

The simplest donate form config ever:

<div id="gpap-donate-widget"></div>

amount​

string

The dollar amount to pre-fill in the form. This can also be provided (or overridden) via the amount URL parameter.

Example​

Ask every viewer for a $10.25 donation:

<div
  id="gpap-donate-widget"
  data-amount="10.25"
></div>

features-wizard​

enum

"on" | "off"

Enables the multi-step "wizard" feature, which collects phone numbers for example.

Example: Collect phone numbers using the wizard.

  <div
    id="gpap-donate-widget"
    data-features-wizard="on"
  ></div>

form-variant​

enum

Specifies which variant of the donate form form to use ("power", "large", "medium", "small", "mini", etc).

To see the different sizes in use, open Storybook to the Donate Form container and explore what it looks like using the different variant options (in the "knobs" tab).

In a nutshell, the variants are different sizes of the form:

  • mini: just the amount input, with no frequency control
  • small: the amount input + frequency control (regular or one-off)
  • medium: includes a set of dollar amounts (aka "handles") provided to the donate form
  • large: frequency control + amount input + clickable "dollar handles". If you use this, see also further documentation to see how we configure each dollar handle.
  • power: an 'extra large' version where all amount/frequency inputs are on one screen along with billing details and card input

PRs:

  • Features: large donate widget DE-78 #25
  • Feature: recurring only mini widget DE-149 #20
  • Feature: medium donate form variant #359

Example: Use the mini variant.

  <div
   id="gpap-donate-widget"
   data-form-variant="mini"
  ></div>

frequency​

enum

"once" | "recurring"

Sets the default value for the donation frequency.

Note: you can override this via a legacy URL-parameter: freq=1 for one-off or freq=2 for recurring. We may deprecate or change that at some point (in favor of interval=once / etc which we use for the power variant) - see issue #176.

Example: ask the user for a regular gift.

<div
  id="gpap-donate-widget"
  data-frequency="recurring"
></div>

See also: interval and intervalCount to change the payment cycle from 4-weekly to something else.

string

Example: "Donate Today"

Replaces the default button label ("Donate") with a user-specified string.

<div
  id="gpap-donate-widget"
  data-donate-button-label="Donate Today"
></div>

frequency-once-label​

frequency-recurring-label​

Overrides default frequency toggle switch button labels.

Example: see Storybook.

<div
  id="gpap-donate-widget"
  data-frequency-once-label="Just Today"
  data-frequency-recurring-label="Monthly"
></div>

See what that looks like.

amount-hook​

string

Provides the name of a hook function to call whenever the user changes the inputted or selected amount.

Example:

Below, we have a function which we might use when we're doing matching donations. It shows a paragraph block below the widget if and when there is a non-zero donation amount selected, and keeps the amount and amountDoubled spans updated.

 <script>
      function newAmount(amount) {
        const donationAmount = amount.value || 0;
        amountDoubler.style.display = donationAmount ? 'block' : 'none';
        yourAmount.innerText = donationAmount;
        yourAmountDoubled.innerText = donationAmount * 2;
      }
  </script>

  <div
    id="gpap-donate-widget"
    data-amount-hook='newAmount'
  />

  <p id="amountDoubler">
    Your $<span id="yourAmount"></span> donation will be doubled to $
    <span id="yourAmountDoubled"></span> this month.
  </p>

An example page we used this on was our P2 mask donate page.

Example code.

PR: amount, frequency hooks #7

frequency-hook​

string

Provides the name of a hook function to call whenever the user changes the selected donation frequency.

Example code.

PR

Here's a production-ready example with all the nuts and bolts included:

<!-- Pull in our helper styles -->
<link href="https://unpkg.com/@gp-australia-pacific/gpap-frontend-functions@latest/dist/gp-donate.css" rel="stylesheet">

<!-- Run our helper code which gives you a toggler function -->
<script  data-cfasync="false" src="https://unpkg.com/@gp-australia-pacific/gpap-frontend-functions@latest"></script>

<!-- Create the toggler function and assign it to a function we'll call `newFreq` -->
<script data-cfasync="false">
var oneOffId = 'donate-disclaimer-oo';
var recurringId = 'donate-disclaimer-rg';
var newFreq = donations.getToggler(oneOffId, recurringId);
</script>

<!-- Configure the donate form, letting it know to run the `newFreq` function when
     the user picks a new frequency -->
<div
  id="gpap-donate-widget"
  data-frequency-hook='newFreq'
>
<p id="donate-disclaimer-oo" class="gp-hidden">
  Your generous one-time gift helps fund our campaigns for a better and greener future.
</p>
<p id="donate-disclaimer-rg" class="gp-hidden">
  Your account will be debited today, then every subsequent 4 weeks. <a href="https://www.greenpeace.org.au/contact/">Get in touch with us to</a> arrange an alternative date.
</p>

redirect-meta-var​

string

Names a previously defined, globally scoped, javascript object containing data to send to the thank-you page.

Example: Here we define a javascript object called redirectMeta, populate it with some values our thank-you page expects, and then pass the name of the object to the donate form as a data attribute.

<script>
  var redirectMeta = {
    save: 1,
    appealID: {
      once: '21CG-W',
      recurring: '21RGNew-W',
    },
   productName: '2021 Oceans Donate - Widget',
  };
</script>

<div
  id="gpap-donate-widget"
  data-redirect-meta-var="redirectMeta"
></div>

PR: Pass generic metadata from hosting page to redirect URL #56

redirect-url-success​

string

Provides the URL of the "thank you page".

Note that the URL will automatically have information appended as URL parameters.

Example: on success, redirect to the standard thank-you page

<div
  id="gpap-donate-widget"
  data-redirect-url-success="https://actions.greenpeace.org.au/donate/thank-you"
></div>

PRs:

  • Features: configurable on-success redirect #16
  • add transaction id to url param #72
  • Features: Include some params in thank_you redirect URL #26

salesforce-campaign-id​

The Salesforce Campaign ID. When you are on the Campaign page, find the Campaign ID in the URL. In the following URL, the ID is "7016F000002EdrQQAS": https://...force.com/lightning/r/Campaign/7016F000002EdrQQAS/view.

Example:

<div
 id="gpap-donate-widget"
 data-salesforce-campaign-id="7016F000002EdrQQAS"
>

Data Attributes - Advanced Usage​

Are you a power user or have an edge case? Some of these settings may help.

host​

string

This is the hostname of the GPAP payment controller server/service.

Leave unspecified unless you need to override the value from config.js.

port​

string

This is the port of the GPAP payment processor.

Leave unspecified unless you need to override the value from config.js.

certification-rule​

enum

"AustralianFederalElection" | "None"

Specifies which logic to use for certifying donors/donations.

Example: When setting up a page that should have a certification system enabling the donation form to work in the context of the Australian Federal Election (i.e. donations over $100 must be certified), you might set the configuration as follows:

        data-certification-rule="AustralianFederalElection"
        data-certification-label="I certify that I am not a foreign donor (as defined in the Electoral Act), that I want my donation to go toward Federal electoral campaigns, and that I have not made donations totaling more than $13,800 to Greenpeace during this financial year with the intention that these donations will go towards Federal election campaigns. I understand that my donation will only be used toward Federal electoral campaigns if this box is checked, and will otherwise go toward non-electoral campaigns.

To see the effect, look at knobs in the DonateFormContainer in Storybook or this screenshot.

certification-label​

string

Provides the text/disclaimer to display next to the certification tickbox (aka checkbox). Note that this may or may not immediately appear -- whether and when it does is controlled by the certification-rule configuration option (see above).

Certification disclaimer not showing up? If using the "AustralianFederalElection" rule, note this rule specifies that donations under $100 need no certification. Type "$100" into the amount field and you should see the certification disclaimer text.

features-paypal​

enum

"on" | "off"

Enables or disables PayPal payment option.

Example:

  <div
    id="gpap-donate-widget"
    data-features-paypal="on"
  ></div>

N.b.! Talk to Engineering before enabling this. At the time of writing, there is backend work needed before we can process these donations.

interval & interval-count​

Specifies the donation payment cycle (recurring time period).

Nearly any duration can be created by multiplying the two values together.

Example: one donation every two weeks:

<div
  id="gpap-donate-widget"
  data-interval="weekly"
  data-interval-count="2"
></div>

These can also be specified as equivalent URL parameters: interval=weekly&intervalCount=1.

iterations​

The number of donations to take.

Example: take six donations before cancelling a recurring/regular gift.

<div
  id="gpap-donate-widget"
  data-iterations="6"
></div>

max-acceptable-amount​

string

Sets the maximum amount the donation form will accept. If the user enters more than this amount, the user will be informed that they must enter a smaller amount.

max-acceptable-amount-message​

string

Provides the text to display to the user if they try donating more than the max-acceptable-amount.

Example:

<div
  id="gpap-donate-widget"
  data-max-acceptable-amount="99999.99"
  data-max-acceptable-amount-message="For gifts of $100,000 or more, please call."
></div>

trial-days​

integer

Allows for a regular gift to start some number of days in the future.

For example, if you've just taken a one off gift, and you want someone to sign up to make another gift in about a month, you could use trial-days=28.

See also: daisychain recipe.

form-variant-power-contact-id-validation​

string

Example: "off"

Enable or disable validation of ContactID URL parameter for the Power Form variant. Default, if unspecified, is "on".

Deprecated? These need review - we may not need them anymore.​

Passing tracking information to the thank you page

See also: PR #14 - Features: tracking codes

appeal​

string

Example: "19CG-W"

The "appeal" is an identifier which can be useful for reporting in a financial database. For example, "19CG-W" might record that this was a cash or credit gift made via web in 2019, while "18RGNov-W" could be a recurring gift made during a November appeal period.

package​

string

Example: "UP"

"UP" here stands for "Unprompted" (i.e. the traffic was "organic", or of "unknown" origin). Package codes could also record whether the source was one or another social media system, a certain email communication, etc.

source​

string

Example: "test-tracking-code"

Configuration specific to the large donate form​

In the large variant of the form, users can click "dollar handles", which are each a dollar amount and some associated text and image.

To add the dollar handles, we add each as its own <donate-option> inside the donate form's <div>, like so:

<div
  id="gpap-donate-widget"
>
  <donate-option .../>
  <donate-option .../>
  <donate-option .../>
</div>

A single dollar handle contains info about the amount, description, and image, and looks like this:

<donate-option
  amount="30"
  frequency="once"
  description="could buy the ship's crew a pizza in town"
  imageSrc="https://some-server.org/your-image.jpg"
  imageAlt="A school of fish in the underwater sunlight"
  imageHeight="400"
  imageWidth="225"
/>

The option's attributes, explained:

  • amount: an amount, in dollars. Clicking this sets the desired donation amount.
  • frequency: "once" | "recurring". If the user toggles between expressing an intention to give once or regularly, the corresponding <donate-option>s will be available. Use "once" for one-off, or "recurring" for a regular gift option.
  • description: the (short) text to display along with this donate option.
  • imageSrc: the URL of an image to present, related to this donate option.
  • imageAlt: the alternative text to display for users who rely on accessibility software. Just as you'd want to use a beautiful image, you'll want to use a beautifully descriptive alt text.
  • imageHeight: the image height (in pixels) of the source image; setting this allows the form to calculate layout properly in advance of when the image loads.
  • imageWidth: the iamge width (in pixels) of the source image; setting this allows the form to calculate layout properly in advance of when the image loads.