Welcome to CM Donation’s documentation!¶

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¶

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.

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.

Please remember to enable the plugin.

Create menu item¶

CM Donation component only provides one menu item for Thank You page. This is the page where thankful messages to donor are displayed.

Without menu items for Thank You page, CM Donation still can display thankful pages with no problem, however the addresses of these pages are not nice and user friendly. By creating menu items, you can customize the addresses with the aliases of the menu items.

Because these pages are only available after donor completes or cancels a donation, so we don’t want these pages to be visible to public. To do this you need to put them into a menu which is not assigned to any menu module, so the menu and the menu items will not be displayed anywhere on your site.

You navigate to Menu -> Menus Manager.

Click “New” button on the toolbar to create a new menu.

Give you menu a name and a menu type, for example “Hidden”.

Save the menu and you are taken back to the menu list.

Select this new menu in the menu list, you can see there is no menu items in this menu at the moment, you click “New” button on the toolbar to create a new menu item.

In the next form, you click “Select” button to select menu item type.

In the pop-up, you select CM Donation -> Thank you.

Give your new menu item a new and select “Complete” in “Layout” option to configure this new menu item for completed donation.

Save your new menu item and it is displayed in the list.

Create another new menu item for “Cancel” layout, this menu item is for cancelled donation.

Now you have 2 hidden menu items for thankful messages of completed donation and cancelled donation.

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.

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.