Welcome to CM Donation’s documentation!¶
CM Donation is a Joomla! component that allows nonprofit organizations to receive one time or recurring donations from people around the world.
This documentation gives you instruction how to install and setup CM Donation on your Joomla! website.
The source of CM Donation is hosted at Github.
Overview¶
CM Donation is a Joomla! component that allows nonprofit organizations to receive one time or recurring donations from people around the world.
CM Donation is easy to setup and use. CM Donation provides a simple donation form and many interesting statistics for end-users.
If you
- use Joomla!
- are a nonprofit organization, are a charity
- need to receive funding from donors
- need to support anonymous donations, one time or recurring donations
then you can give CM Donation a try.
Technical Requirements¶
CM Donation is compatible with Joomla! 2.5.x and 3.x.x. CM Donation is NOT compatible with Joomla! 1.x.x.
Please check Joomla!’s Technical Requirements for more information of Joomla!’s requirements.
Features¶
Front-end¶
- Integration with Joomla! Content: You can easily put donation form and donation statistics into any Joomla! article, Joomla!’s Custom HTML module or any third-party extension which supports Content’s Event System.
- Supports one time and recurring payments (daily, weekly, semimonthly, monthly, annually).
- Support anonymous donation: donor’s name is not displayed in front-end but is still recorded and is only visible to administrators in back-end.
- Display statistics for
- Donation quantity that your campaign receive.
- Total amount donated to your campaign.
- N latest donations.
- Top N donors who donate to your campaign by their total contributions.
- Top N countries which have donors donating to your campaign.
Back-end¶
- Many configuration options.
- Export donor list to CSV.
- Manually create a new donation.
- Edit existing donations.
- Report for every campaign.
Supported payment methods¶
- PayPal Payments Pro (Express Checkout)
Installation¶
Download¶
The installation package of CM Donation can be downloaded from our website or from our Github repository.
The package includes:
- CM Donation component
- CM Donation Content plugin
- PayPal Payments Pro (Express Checkout) payment plugin
Installation¶
In your Joomla! back-end, you navigate to Extensions -> Extension Manager
Click “Browse” button and select the installation package of CM Donation on your computer, click “Upload & Install” button to upload the package to your server and install it.
If the package is installed successfully, you receive the message “Installing package was successful.”
You can see CM Donation in Components menu item.
Go to Extensions -> Plugin Managers, you can see CM Donation Content plugin and PayPal payment plugin are also available in the list of installed plugins.
Configuration¶
CM Donation component¶
In your Joomla!’s back-end, you go to Extensions -> CM Donation to access CM Donation component.
The default page of CM Donation is the dashboard. On the toolbar there is an “Options” button, you click this button to configure the component.
There are the following tags in the configuration page: General, Currency, Donation, Donation form, Donor list, Country list, Statistics, Permission.
General¶
In “General” tab, we have the following options:
- Row number column: Show or hide the first column for row number in statistic tables (top donors, latest donations,...).
- Date format: Date format which is used in both front-end and back-end.
Currency¶
In “Currency” tab, we have the following options to configure the currency used in donation:
- Currency sign: The sign of the currency you use for donation. For example, “$” for United States Dollar.
- Currency sign position: Where currency sign is displayed, before or after the amount.
- Decimals: Number of decimals.
- Decimal point: Character is used as decimal point.
- Thousands separator: Character is used as thousands separator.
Donation¶
In “Donation” tab, we have the following configuration for donation:
- Anonymous donation: Allow anonymous donation.
- Available recurring cycles: Available recurring cycles which are displayed in donation form for donor to select. If there is only 1 cycle available, this option is hidden.
Donation form¶
In “Donation form” tab, we have an option for donation form:
- Hide lone payment option: Hide payment method selection if in donation form there is only 1 payment method to select.
Donor list¶
In “Donor list” tab, we have the following configuration for top donor and latest donation tables:
- Donor name: How donor name is displayed, you can show first name or last name only, or display both.
- Country: Hide country info or display country as flag or name or both flag and name.
- Donated date column: Show or hide donated date column.
Country list¶
In “Country list” tab, we have the following configuration for country table:
- Country info: Show country name or country flag, or show both.
- Contribution percentage column: Show or hide the column for contribution percentage of country.
- Contribution percentage’s decimals: Number of decimals of contribution percentage.
- Lowest amount column: Show or hide the column for lowest donated amount of country.
- Average amount column: Show or hide the column for average donated amount of country.
- Highest amount column: Show or hide the column for highest donated amount of country.
Statistics¶
In “Statistics” tab, there are options for reports and CSV export:
- Country info: Show or hide country info in statistics and CSV file.
- CSV delimiter: The character used to separate fields.
- CSV enclosure character: The character used to enclose field.
Note: If you show country info (name, flag or both name and flag), only country name is displayed in CSV file.
Permissions¶
You should change the options in “Permissions” tab if you have many user groups which can access your Joomla! back-end and you need to give them different permissions. If you are the only administrator on the site, or only administrators can access your back-end, you don’t need to configure these settings.
You can view Access Control List Tutorial for more understand how Joomla!’s access control list works.
CM Donation Content plugin¶
To configure CM Donation Content plugin, you navigate to Extensions -> Plugin Manager.
You search for “CM Donation Content plug-in”.
Click on its name and you are taken to the page as the screenshot below where you can edit its settings.
Because all the information of your campaigns is displayed in Joomla! articles and any place supporting Joomla! Content event (third party extensions, modules...), so everytime a page is loaded, the plugin must search and check if there is any information that you ask to display. The information could be
- Number of donations
- Total amount donated
- Donation form
- Latest donations
- Top donors
- Top countries
If there is any information that you don’t need to display on your site, you should ask the plugin to stop checking for them to speed up your page load. You can do this by switching the option of the information to “Disabled” in the plugin’s setting page.
You need to enable the plugin otherwise it doesn’t run.
PayPal Payments Pro plugin¶
In Plugin Manager you search for PayPal Payments Pro payment plugin. Its name in the list is “CM Donation - PayPal Payments Pro (Express Checkout) payment plugin”. Click on the plugin name to configure it.
In “Payment option title” you enter your custom name for this payment method, this is displayed in donation form. If you leave this field empty, the name “PayPal Payments Pro (Express Checkout)” will be used.
If you want to use PayPal Sandbox for testing, you switch “Sandbox” option to “Yes” and enter your API username, API password, and API signature of your PayPal Sandbox into “Sandbox API Username”, “Sandbox API Password”, “Sandbox API Signature” fields.
If you want to accept real transactions, you set “Sandbox” to “No” and enter your PayPal’s info into “API Username”, “API Password”, “API Signature” fields.
You need to select the currency that is used in your donations in “Currency” option. You only can select the currency that PayPal’s supported. Please note that your PayPal account must also support the selected currency.
With “Locale” option, you can select the language of PayPal’s transaction page. If your site is a multilanguage site, you can use the Joomla!’s‘ locale that donor uses. For example, if your site is in English and French, donor views your site in French and decides to donate, French is the locale of PayPal’s donation page after donor is taken to PayPal. If your site is only in 1 language, you should choose another option in the list.
Please remember to enable the plugin.
Campaigns¶
Create new campaign¶
To create a new campaign, you navigate to Extensions -> CM Donation in your Joomla!’s back-end.
On CM Donation’s Dashboard page, you click “Campaigns” on the toolbar.
In the list of campaigns, you click “New” button on the toolbar to create a new campaign.
In there form, there are 3 fields you need to provide information:
- Name: The name of the campagain you want to create.
- Thankful message for completed donation: Your thankful message to donor, this message is displayed after donor makes a successful donation on payment service’s website (eg. PayPal).
- Thankful message for cancelled donation: Your thankful message to donor after donor cancels donation, this message is displayed after donor cancels donation on payment service website.
Other fields in the form:
- Created by: The user who creates the campaign.
- Created date: The date when the campaign is created.
- Modified by: The user who makes the last modification for the campaign.
- Modified date: The date when the last modification is made.
- ID: The ID of the campaign.
After your new campaign is saved successfully, you are taken back to the campaign list.
In the list, there is a column for campaign ID, you will need campaign ID for display campaign’s donation form or other statistic information.
Display campaign’s form¶
To allow people to donate to your campaign you need to display the campaign’s donation form on your site.
In your Joomla!’s back-end you go to Content -> Article Manager. If you want to display the form in an existing article, you edit that article, otherwise you create a new article.
In the content of your article, you enter the tag (shortcode)
{donation-form:X}
where you want the form to be displayed. X is the ID of the campaign you want to display its form.
Visit your article on your site’s front-end, you can see the donation form is displayed in your article.
Donate¶
Before test your donation form, please make sure that you have already enabled and configured PayPal Payments Pro plugin.
Enter the amount you want to donate, select the options in the form and click “Donate” button.
If there is no validation errors, you will be taken to PayPal to complete the transaction.
On PayPal website, you can login with your PayPal account or use your credit card to donate.
You follow the next steps to complete your transaction.
If your transation is completed successfully, you will be taken to the menu item for completed donation.
If you cancel the transaction by clicking the link “Cancel and return to...” at the bottom of the page, you will be taken to the menu item for cancelled donation.
Statistics in front-end¶
You can display the following information in your front-end:
- The number of donations of a campaign.
- Total amount donated of a campaign.
- Latest donations of a campaign.
- Top donors of a campaign.
- Top countries of a campaign.
Donation quantity¶
Edit the Joomla! article which you want to display donation quantity of your campaign, you put the tag
{donations:X}
where you want the number is displayed. X is the ID of the campaign.
View the article in front-end to check if the number of donations is displayed.
Total amount donated¶
To display the total amount that donors donated to your campaign, you put the tag
{amount:X}
where you want to display the value in your article. X is the ID of the campaign.
The tag will be replaced by the value of your campaign’s total amount of donated money.
Latest donations¶
You can display the latest donations of your campaign by putting the tag
{latest-donations:X:Y}
where you want to display the value in your article. X is the ID of the campaign and Y is the number of donations you want to display.
The tag will be replaced by the value of your campaign’s total amount of donated money.
Top donors¶
A donor can donate to your campaign many times. You can hornor the donors by listing them in top donors table. You use the tag
{top-donors:X:Y}
where you want to display the table. X is the ID of the campaign and Y is the number of donors you want to display.
The plugin automatically calculates the donor’s contributions and display the donors who contributed the most on the top of the list.
Top countries¶
We can know where donors come from via the PayPal transactions. The plugin can collect this data and make a statistic table to listing what countries that have donors contributing to your campaign the most. The tag for this table is
{top-countries:X:Y}
where you want to display the table. X is the ID of the campaign and Y is the number of countries you want to display.
The result in your article similar to the following screenshot.
Statistics in back-end¶
To view statistics of your campaigns, you go to Extensions -> CM Donation in your Joomla!’s back-end.
On CM Donation’s Dashboard page, you click “Statistics” on the toolbar.
Select the campaign you want to view its statistics then click “View” button.
In the next page the statistics are displayed similar to the screenshot below.
If you want to export the list of donors of this campaign, you click the button “Export donors (CSV)” on the toolbar. Download the CSV file and open it with your favorite spreadsheet application which supports CSV.