Content Management

Donation Amounts

Site Creators can use the Donation Amounts feature to allow non-developers to manage the amounts and the associated descriptions that appear on donation pages alongside them.

Donation Amounts are managed in the Campaign section by clicking the money icon.

The Donation Amounts feature is only responsible for the inclusion of the amounts as JSON inside the page. The supplied Dijon templates include donation amounts from this Javascript, however, there are many innovative ways to implement Donation Amounts in your campaign and Donation Amounts are just the building blocks to manage this content inside the administration system.

Implementation

To set up Donation Amounts, the Site Creator should create an array containing the default values to be made available. Each of the entries will include an array that contains the default values that should be used if there are no campaign-specific Donation Amounts.

Donation Amounts are named. This is to allow more than one set of amounts to be used on a single page. For example, you may wish to have a set called "one-off" for single payment amounts and one called "subscription" for subscription amounts.

Step One - Add the following to your site_config.php file

This sets up defaults for the donation amounts you customise in the Administration system.

$donationAmountsWithDescriptions = [
  ['GBP',  5,  'Five pounds buys a meal'   ],
  ['GBP',  10, 'Ten pounds buys two meals' ],
  ['USD',  10, '20 dollars buys a meal'    ],
  ['USD',  20, '20 dollars buys two meals' ],
];

$config->setNamedDonationAmounts(
    'payment', $donationAmountsWithDescriptions
);

Step Two - Add the following to your template

This will include the default Donation Amounts in the page, or if there are amounts specified in the administration menu, it will include those relevant to the campaign, country and language that Dijon is displaying.

<script type="text/javascript">

  try {
    window.donation_amounts = {{ donation_amounts('payment') }};
  }

  catch (error) {
    // this should never fail, but just in case...
  }

</script>

Step Three - Make sure the following site_config.php options are set

Donation amounts rely on the following site_config.php configuration options being set:

• setDefaultCurrency
  Use this to set the default currency for your site. If setDonationAmountsDefaultConversion is set, Dijon uses this as the source currency for the convered amounts.
• setDonationAmountsDefaultConversion
  Convert the default currency donation amounts where the language is not defined.
• setCurrencies
  use this to set the currencies for each country. Dijon will include donation amounts in pages for currencies set here only.

If setDonationAmountsDefaultConversion is set to true, which is the case by default, you should remember to run the following command to populate your exchange rate data.

docker exec -it dijon_php_1 php cli.php process:fetch_currency_data

Precedence

Donation Amounts are loaded in the following order:

• Donation amounts matching currency, campaign, language and country
• Donation amounts matching currency, campaign and language
• Donation amounts matching currency and campaign
• Default donation amounts specified in site_config.php for this currency

If you have the configuration option setDonationAmountsDefaultConversion set to true (which is the default), Dijon will also convert from the default currency (set via setDefaultCurrency) to each currency defined for the country which it is displaying (set via setCurrencies).

The order used when converting is as follows:

• Donation amounts matching default currency, campaign, language and country
• Donation amounts matching default currency, campaign and language
• Donation amounts matching default currency and campaign
• Default donation amounts specified in site_config.php for default currency