DEPRECATION WARNING
This documentation is not using the current rendering mechanism and is probably outdated. The extension maintainer should switch to the new system. Details on how to use the rendering mechanism can be found here.
EXT: Donations¶
Author: | Kasper Skårhøj |
---|---|
Created: | 2002-11-01T00:32:00 |
Changed by: | François Suter |
Changed: | 2008-06-23T21:55:45 |
Email: | typo3@cobweb.ch |
Info 2: | |
Info 3: | |
Info 4: |
EXT: Donations¶
Extension Key: donations
Copyright 2007, typo3@cobweb.ch, <typo3@cobweb.ch>
This document is published under the Open Content License
available from http://www.opencontent.org/opl.shtml
The content of this document is related to TYPO3
- a GNU/GPL CMS/Framework available from www.typo3.com
Table of Contents¶
EXT: Donations 1
Introduction 1
What does it do? 1
Screenshots 1
Credits 1
Questions and support 1
Users manual 2
Installation 2
Setup 2
Donation process 4
Administration 6
Configuration 7
TypoScript Reference 7
Template 8
To Do List 11
Known problems 11
Changelog 11
Introduction¶
What does it do?¶
This extension is designed to collect donations on a web site, either for specific projects or in a general way. Using payment extensions (see Installation below) donations can be collected using on-line payment solutions.
Although perfectly functional this is still a work in progress so you may have trouble fitting it exactly to your needs. See the To Do List below for details on missing features and future developments.
Screenshots¶
No single screenshot can really sum up what this extension does. Please browse this manual, many screenshots are included. In particular, you may want to refer to the “Donation process” part of the “Users manual” chapter for an overview.
Credits¶
This extension was originally created by Tonni Aagesen. Much of the code is still his as well as the application logic so many thanks go to him. His work got me very nicely kickstarted.
The icons used in this extension come from the Silk Icons library ( http://www.famfamfam.com/lab/icon/silk/ ), a beatiful set of icons developed under the Creative Commons license by Mark James, of Birmingham, UK.
Questions and support¶
If you have questions about this extension please ask them in the general mailing list, so that everyone can benefit from the answers. If you find a bug or want to submit a feature request, use the dedicated bug tracker on the project's home page: http://forge.typo3.org/projects/show/extension-donations.
Users manual¶
Installation¶
This extension requires a few other extensions for working properly:
Payment Library (paymentlib), for on-line payment
Money Library (moneylib), for formatting currency display
Static Info Tables (static_info_tables), for information about currencies
It also requires PHP 5 to run because of its dependency on paymentlib.
In itself Payment Library is not enough. An implementation for a specific payment gateway is necessary, like paymentlib_ipayment or paymentlib_quickpay.
Setup¶
After installing the extension several steps must be taken before it can to work correctly.
Static template
First of all it is necessary to include the static setup template.
Projects
If projects are to be used, then at least one must be defined in the TYPO3 backend. Create a new record in the backend and choose the type “Projects”.
It is not necessary to fill out all the fields, but at least a title and an amount must be entered. The amount is the total quantity of money that needs to be raised for the project.
TypoScript setup
A number of properties can be set via TypoScript, besides the defaults found in the static template. However, one setup is absolutely necessary: the definition of the payment methods that will be used for the donations. Without that, it will be impossible to perform donations.
The static template contains a list of payment methods (the “paymethods” property) that correspond to the paymentlib_offline extension. This is just an example and serious values should definitely be set for this property.
Please refer to the TypoScript Reference below.
Templates
An example template is provided with the donations extension (pi1/example.tmpl). Copy it and transform it according to your needs, without forgetting to change the “template” property in the TypoScript setup accordingly.
Content element
Last but not least, a content element for donations must be inserted in the page where the donations process is going to take place.
First choose the type “Insert plugin”, then choose the plugin “Donations”. The starting point is optional. If defined, only projects found in the selected page will be displayed in the list. If not, all projects will be displayed.
You should now be able to go through a complete donation process, as detailed next.
Donation process¶
A complete example donation process is described here so that every step can be properly understood. Sample screenshots are shown where appropriate.
List of projects
When projects are used, this is the default view. It lists all projects available for donation. If projects are not being used, this view will never appear (it redirects to the donation view). Projects whose maximum amount has already been reached do not appear in this list.
Project details
This view displays all the details about a single project. It is reached by clicking on the details link of the list view above. If projects are not being used, this view will never appear (it redirects to the donation view). It is possible to go back to the projects list.
Donation view
This page displays the form where the donation data is entered: payment information, personal data and donation amount. The payment information comes directly from paymentlib and depends on the installed and configured payment gateways. From here, it is possible either to proceed with the payment or to go back to the projects list.
Confirmation view
The confirmation view displays the data entered in the previous step for validation before the payment process is launched. It also checks the input values and redirects to the donation view in case of errors. In such a case, the donation view is called with an error code and displays the appropriate error message.
Receipt view
If the online payment is successful the user is sent to the receipt view (if it fails, the user is redirect to the confirm view with an error message). This view does not only display a visual confirmation of success, it also stores the donation in the database and sends e-mails as configured.
Mails
If so configured, the donations extensions can send an e-mail both to the donator and to the site administrator. These e-mails are simple text mails, with donation information listed according to the chosen template.
Administration¶
There's not much to administer in the backend regarding this extension. It is just necessary to know that three types of database entries are used:
projects (table tx_donations_projects), for describing which projects can be donated to. As was said before, it is possible to do without projects.
deposits (table tx_donations_deposits), which stores individual donations.
transactions (table tx_paymentlib_transactions), generated by paymentlib for each payment transaction
If you have configured both the donations and the paymentlib extensions to store everything at the same place, you should see a view similar to the one above (in List view).
Configuration¶
TypoScript Reference¶
template¶
Property
template
Data type
resource
Description
HTML template to be used for displaying the projects list, a project's detail view, the various screens of the donation process and the mails sent to user and admin
Default
typo3conf/ext/donations/example.tmpl
depositsPID¶
Property
depositsPID
Data type
int
Description
uid of the page where the receipts should be stored
Default
0
disableProjects¶
Property
disableProjects
Data type
boolean
Description
Disable the use of projects. In this case donations are general and not dedicated to a specific project
Default
0
defaultCurrency¶
Property
defaultCurrency
Data type
string
Description
Each project can have a currency associated with it. However you may also define a default currency to be used for all projects or when projects are not used.
Value must be the 3-letter ISO code of a currency
Default
USD
errorWrap¶
Property
errorWrap
Data type
stdWrap
Description
Wrap for the error messages issued by the plugin
Default
wrap = <div class="error">|</div>
formName¶
Property
formName
Data type
string
Description
Name of the form (to put in the name or id attribute of the form in the template)
Default
donateForm
paymethods¶
Property
paymethods
Data type
string
Description
Comma-separated list of all payment methods available (see Setup)
Default values correspond to the paymentlib_offline extension
Default
paymentlib_offline_bank_check,
paymentlib_offline_giro,
paymentlib_offline_cod,
paymentlib_offline_cash,
donateView¶
Property
donateView
Data type
->donateView
Description
Parameters for the donation view
Default
confirmView¶
Property
confirmView
Data type
->confirmView
Description
Parameters for the confirmation view
Default
receiptView¶
Property
receiptView
Data type
->receiptView
Description
Parameters for the receipt view
Default
thankMessage¶
Property
thankMessage
Data type
cObj
Description
Thank you message to be displayed at the end of the donation process
Default
thankMessage = TEXT
thankMessage.value = Thank you for your donation!
thankMessage.wrap = <p>|</p>
mail¶
Property
Data type
Description
Mail configuration
Default
baseWrap¶
Property
baseWrap
Data type
stdWrap
Description
This can be used to replace the default wrap of the plugin (<div class =”tx-donations”>|</div>)
Default
[tsref:plugin.tx_donations_pi1]
Donate View parameters
projectTitle¶
Property
projectTitle
Data type
stdWrap
Description
Wrap for displaying the project title
A “project” field is available containing the project title
Empty it to display nothing
Default
projectTitle.field = project
projectTitle.wrap = <h2>Make a donation to project "|"</h2>
amountMin¶
Property
amountMin
Data type
int
Description
Wrap for displaying the minimum amount for donation
Default
amountMin.wrap = (Min: |,
amountMax¶
Property
amountMax
Data type
int
Description
Wrap for displaying the maximum amount for donation
Default
amountMax.wrap = Max: |)
[tsref:plugin.tx_donations_pi1.donateView]
Confirm View parameters
projectTitle¶
Property
projectTitle
Data type
stdWrap
Description
Wrap for displaying the project title
A “project” field is available containing the project title
Empty it to display nothing
Default
projectTitle.field = project
projectTitle.wrap = <h2>Confirm details for donation to "|"</h2>
[tsref:plugin.tx_donations_pi1.confirmView]
Receipt View parameters
projectTitle¶
Property
projectTitle
Data type
stdWrap
Description
Wrap for displaying the project title
A “project” field is available containing the project title
Empty it to display nothing
Default
projectTitle.field = project
projectTitle.wrap = <h2>Receipt for donation to "|"</h2>
[tsref:plugin.tx_donations_pi1.receiptView]
Mail parameters
sendToAdmin¶
Property
sendToAdmin
Data type
boolean
Description
Enable the sending of a mail to the administrator when a donation is done
Default
1
sendToUser¶
Property
sendToUser
Data type
boolean
Description
Enable the sending of a confirmation mail to the donor
Default
1
senderMail¶
Property
senderMail
Data type
string
Description
E-mail address that should appear in the From field of the mails sent to both admin and user
Default
senderName¶
Property
senderName
Data type
string
Description
Name that should appear in the From field of the mails sent to both admin and user
Default
Site Admin
adminMail¶
Property
adminMail
Data type
string
Description
E-mail of the administrator
Default
adminMessage¶
Property
adminMessage
Data type
string
Description
Introductory text at the start of the email to the administrator
Default
The following donation has been received:
adminSubject¶
Property
adminSubject
Data type
string
Description
Subject of the mail received by the administrator
Default
New donation received
userMessage¶
Property
userMessage
Data type
string
Description
Introductory text at the start of the email to the donor
Default
Thank you for your donation! Here is your receipt:
userSubject¶
Property
userSubject
Data type
string
Description
Subject of the mail received by the donor
Default
Donation confirmation
dateWrap¶
Property
dateWrap
Data type
stdWrap
Description
Formatting for dates inside the mails
Default
dateWrap.strftime = %Y-%m-%d
[tsref:plugin.tx_donations_pi1.mail]
Template¶
A template is used to format the output of the donations extension. It is comprised of several views which are detailed below along with their respective markers.
List view (###LISTVIEW###)
This produces a list of all the projects available for donation.
###ITEMS###¶
Marker
###ITEMS###
Function
List of all projects
Item for list view (###LISTVIEW_ITEM###)
This is the subtemplate for each item (project) inside the list view.
###LOGO###¶
Marker
###LOGO###
Function
Logo of the project (image tag)
###TITLE###¶
Marker
###TITLE###
Function
Title of the project
###SHORT_DESC###¶
Marker
###SHORT_DESC###
Function
Short description of the project
###DETAILS_LINK###¶
Marker
###DETAILS_LINK###
Function
Link to details view
###AMOUNT_MIN###¶
Marker
###AMOUNT_MIN###
Function
The minimum amount of money that must be donated
###AMOUNT_DONATED###¶
Marker
###AMOUNT_DONATED###
Function
The amount of money donated so far for this project
###AMOUNT_NEEDED###¶
Marker
###AMOUNT_NEEDED###
Function
The amount of money needed for the project
###CURRENCY###¶
Marker
###CURRENCY###
Function
Currency for donation
###DONATE_LINK###¶
Marker
###DONATE_LINK###
Function
Link to the donate view
Details view (###SINGLEVIEW###)
This template is used to show the complete information about a given project.
###LOGO###¶
Marker
###LOGO###
Function
Logo of the project (image tag)
###TITLE###¶
Marker
###TITLE###
Function
Title of the project
###SHORT_DESC###¶
Marker
###SHORT_DESC###
Function
Short description of the project
###DETAILS_LINK###¶
Marker
###DETAILS_LINK###
Function
Link to details view
###AMOUNT_MIN###¶
Marker
###AMOUNT_MIN###
Function
The minimum amount of money that must be donated
###AMOUNT_DONATED###¶
Marker
###AMOUNT_DONATED###
Function
The amount of money donated so far for this project
###AMOUNT_NEEDED###¶
Marker
###AMOUNT_NEEDED###
Function
The amount of money needed for the project
###CURRENCY###¶
Marker
###CURRENCY###
Function
Currency for donation
###DONATE_LINK###¶
Marker
###DONATE_LINK###
Function
Link to the donate view
###LONG_DESC###¶
Marker
###LONG_DESC###
Function
Long description of the project
###BACK_LINK###¶
Marker
###BACK_LINK###
Function
Link back to the list view
Donate view (###DONATEVIEW###)
Input form for a donation.
###PROJECT_TITLE###¶
Marker
###PROJECT_TITLE###
Function
Form title, possibly including the project's name
###ERROR_MESSAGE###¶
Marker
###ERROR_MESSAGE###
Function
Placeholder for a possible error message
###FORM_URL###¶
Marker
###FORM_URL###
Function
URL for submitting the form
###FORM_NAME###¶
Marker
###FORM_NAME###
Function
Name of the form
###PAYMETHODS###¶
Marker
###PAYMETHODS###
Function
Placeholder for the list of payment methods available (set of radio buttons)
###AMOUNT_MIN###¶
Marker
###AMOUNT_MIN###
Function
Minimum amount of money that can be donated
###AMOUNT_MAX###¶
Marker
###AMOUNT_MAX###
Function
Maximum amount of money that can be donated
###AMOUNT_VAL###¶
Marker
###AMOUNT_VAL###
Function
Donation amount entered by the user
###COMPANY_VAL###¶
Marker
###COMPANY_VAL###
Function
Name of the company entered by the user
###NAME_VAL###¶
Marker
###NAME_VAL###
Function
Name entered by the user
###ADDR_VAL###¶
Marker
###ADDR_VAL###
Function
Address entered by the user
###ZIP_VAL###¶
Marker
###ZIP_VAL###
Function
Zip code entered by the user
###CITY_VAL###¶
Marker
###CITY_VAL###
Function
City name entered by the user
###COUNTRY_VAL###¶
Marker
###COUNTRY_VAL###
Function
Country name entered by the user
###EMAIL_VAL###¶
Marker
###EMAIL_VAL###
Function
E-mail address entered by the user
###BUTTONS###¶
Marker
###BUTTONS###
Function
Placeholder for the form buttons
###BACK_LINK###¶
Marker
###BACK_LINK###
Function
Link back to the project details (displayed only if projects are used)
Confirmation view (###CONFIRMVIEW###)
Confirmation view of the donation before starting the payment process.
###PROJECT_TITLE###¶
Marker
###PROJECT_TITLE###
Function
Form title, possibly including the project's name
###ERROR_MESSAGE###¶
Marker
###ERROR_MESSAGE###
Function
Placeholder for a possible error message
###FORM_URL###¶
Marker
###FORM_URL###
Function
URL for submitting the form
###FORM_NAME###¶
Marker
###FORM_NAME###
Function
Name of the form
###FORM_FORM_PARAMS###¶
Marker
###FORM_FORM_PARAMS###
Function
Placeholder for the additional form parameters defined by the chosen payment method
###HIDDEN_FIELDS###¶
Marker
###HIDDEN_FIELDS###
Function
Placeholder for hidden fields containing all the input values
###PAYMETHOD###¶
Marker
###PAYMETHOD###
Function
Chosen payment method
###AMOUNT_VAL###¶
Marker
###AMOUNT_VAL###
Function
Donation amount entered by the user
###CURRENCY###¶
Marker
###CURRENCY###
Function
Chosen currency of the transaction
###PAYMENT_DETAILS###¶
Marker
###PAYMENT_DETAILS###
Function
Placeholder for all the input fields necessary for the chosen payment method
###COMPANY_VAL###¶
Marker
###COMPANY_VAL###
Function
Name of the company entered by the user
###NAME_VAL###¶
Marker
###NAME_VAL###
Function
Name entered by the user
###ADDR_VAL###¶
Marker
###ADDR_VAL###
Function
Address entered by the user
###ZIP_VAL###¶
Marker
###ZIP_VAL###
Function
Zip code entered by the user
###CITY_VAL###¶
Marker
###CITY_VAL###
Function
City name entered by the user
###COUNTRY_VAL###¶
Marker
###COUNTRY_VAL###
Function
Country name entered by the user
###EMAIL_VAL###¶
Marker
###EMAIL_VAL###
Function
E-mail address entered by the user
###BUTTONS###¶
Marker
###BUTTONS###
Function
Placeholder for the form buttons
Receipt view (###RECEIPTVIEW###)
Confirmation (receipt) view displayed after the payment process is successfully completed.
###PROJECT_TITLE###¶
Marker
###PROJECT_TITLE###
Function
Form title, possibly including the project's name
###ERROR_MESSAGE###¶
Marker
###ERROR_MESSAGE###
Function
Placeholder for a possible error message
###PAYMENT_REFERENCE###¶
Marker
###PAYMENT_REFERENCE###
Function
ID of the payment transaction
###PAYMETHOD###¶
Marker
###PAYMETHOD###
Function
Chosen payment method
###AMOUNT_VAL###¶
Marker
###AMOUNT_VAL###
Function
Donation amount entered by the user
###CURRENCY###¶
Marker
###CURRENCY###
Function
Chosen currency of the transaction
###PAYMENT_DETAILS###¶
Marker
###PAYMENT_DETAILS###
Function
Placeholder for all the input fields necessary for the chosen payment method
###COMPANY_VAL###¶
Marker
###COMPANY_VAL###
Function
Name of the company entered by the user
###NAME_VAL###¶
Marker
###NAME_VAL###
Function
Name entered by the user
###ADDR_VAL###¶
Marker
###ADDR_VAL###
Function
Address entered by the user
###ZIP_VAL###¶
Marker
###ZIP_VAL###
Function
Zip code entered by the user
###CITY_VAL###¶
Marker
###CITY_VAL###
Function
City name entered by the user
###COUNTRY_VAL###¶
Marker
###COUNTRY_VAL###
Function
Country name entered by the user
###EMAIL_VAL###¶
Marker
###EMAIL_VAL###
Function
E-mail address entered by the user
Mail to administrator (###ADMINMAIL###)
Information mail sent to donation recipient.
###MESSAGE###¶
Marker
###MESSAGE###
Function
Introductory message
###PROJECT_TITLE###¶
Marker
###PROJECT_TITLE###
Function
Form title, possibly including the project's name
###PAYMENT_REFERENCE###¶
Marker
###PAYMENT_REFERENCE###
Function
ID of the payment transaction
###PAYMETHOD###¶
Marker
###PAYMETHOD###
Function
Chosen payment method
###AMOUNT_VAL###¶
Marker
###AMOUNT_VAL###
Function
Donation amount entered by the user
###CURRENCY###¶
Marker
###CURRENCY###
Function
Chosen currency of the transaction
###COMPANY_VAL###¶
Marker
###COMPANY_VAL###
Function
Name of the company entered by the user
###NAME_VAL###¶
Marker
###NAME_VAL###
Function
Name entered by the user
###ADDR_VAL###¶
Marker
###ADDR_VAL###
Function
Address entered by the user
###ZIP_VAL###¶
Marker
###ZIP_VAL###
Function
Zip code entered by the user
###CITY_VAL###¶
Marker
###CITY_VAL###
Function
City name entered by the user
###COUNTRY_VAL###¶
Marker
###COUNTRY_VAL###
Function
Country name entered by the user
###EMAIL_VAL###¶
Marker
###EMAIL_VAL###
Function
E-mail address entered by the user
###DATE_VAL###¶
Marker
###DATE_VAL###
Function
Date of the transaction
Mail to user (###USERMAIL###)
Confirmation mail sent to donor.
###MESSAGE###¶
Marker
###MESSAGE###
Function
Introductory message
###PROJECT_TITLE###¶
Marker
###PROJECT_TITLE###
Function
Form title, possibly including the project's name
###PAYMENT_REFERENCE###¶
Marker
###PAYMENT_REFERENCE###
Function
ID of the payment transaction
###PAYMETHOD###¶
Marker
###PAYMETHOD###
Function
Chosen payment method
###AMOUNT_VAL###¶
Marker
###AMOUNT_VAL###
Function
Donation amount entered by the user
###CURRENCY###¶
Marker
###CURRENCY###
Function
Chosen currency of the transaction
###COMPANY_VAL###¶
Marker
###COMPANY_VAL###
Function
Name of the company entered by the user
###NAME_VAL###¶
Marker
###NAME_VAL###
Function
Name entered by the user
###ADDR_VAL###¶
Marker
###ADDR_VAL###
Function
Address entered by the user
###ZIP_VAL###¶
Marker
###ZIP_VAL###
Function
Zip code entered by the user
###CITY_VAL###¶
Marker
###CITY_VAL###
Function
City name entered by the user
###COUNTRY_VAL###¶
Marker
###COUNTRY_VAL###
Function
Country name entered by the user
###EMAIL_VAL###¶
Marker
###EMAIL_VAL###
Function
E-mail address entered by the user
###DATE_VAL###¶
Marker
###DATE_VAL###
Function
Date of the transaction
To Do List¶
As said in the introduction, although functional this version of the extension is still rather rough in some areas. Here is a list of planned or desirable improvements. Don't hesitate to add to that wish list.
- Handle multiple languages for projects.
- Better and uniform handling of error messages.
- More uniform handling of currency formatting.
- More flexible input form. It should be possible to define whatever fields are desired (beyond those from paymentlib) and store those field in any DB table.
- Better templating with localized labels.
- Input error-handling (client-side).
- Use multiple currencies both for projects and as default value.
Known problems¶
None to date. Please report any to typo3@cobweb.ch.
Changelog¶
0.6.0¶
Version
0.6.0
Changes
- Corrected use of $this->conf (thanks to Benni Mack)
- Added German translation (thanks to Benni Mack)
- Fixed bug in handling of min and max amount (thanks to Benni Mack)
- Fixed bug in sending mails (thanks to Benni Mack)
- Cleaned up a lot of code
- Added security checks against XSS and email injection
- Improved TYPO3 4.2 compatibility
- Moved project to forge.typo3.org
0.5.0¶
Version
0.5.0
Changes
First fully functional release:
- complete donation process (with back buttons where appropriate)
- input error handling (server-side)
- localization of messages
- possibility to not use projects
- correct UTF-8 handling for template
- send mail to donor and recipient
- manual
- many other small improvements