aTreasury & Donatometer v1.0
for PHP-Nuke Version 6.x

Author: Dave Lawrence (aka Thrash)
Web: [ Register or login to view links on this board. ]

Updated for PHPNuke 6.+, 7.+
Fixed some bad coding and cleaned up template.
Telli [ Register or login to view links on this board. ]
http://codezwiz.com/


Intro
-----
This mod will help you manage your organization's income and
expenditures.  The Donatometer is a block you use to display
your current donation goal and what funds have been received
towards that goal.  It also lists the Nuke users who have
contributed so far

The Treasury component is a Nuke admin panel where you can make
basic "check register"-like entries to record your income and
expenditures.  You can also roll up your user contributions as an
entry in the register.

There is a donations module used to plead the necessity for
your users to donate.  The module includes an embedded PayPal
form that will associate the donation with their Nuke username.

The fully functional Donatometer and donations module require the
use of PayPal's Instant Payment Notification, IPN.  You will need
to configure this feature in your PayPal account in order for
these features to work correctly.

The admin panel contains a config button where you can fully
confiugure this mod.  There are tool-tips for every option that
describe their use.  Just hover your mouse over an option to see
the descriptions. 

The Donatometer and Donations module only designed to look at
the current "month".  The "swing-day" allows you to change the
end of the month to be the 6th day, for example.  This is useful
to allow users to make last-minute donation and to display the
contributors for a few days after the month is over.


------------------
Setup Instructions
------------------

======
Files:
======
  Unpack all the file unders "html" into your Nuke root

  Extract the sql/Treasury.sql and drop it into mysql.  Note: the
database for this mod was intended to reside outside of your Nuke
database in a separate database.  The thought here is that the
financial records would require special attention in regards to
backups.  A separate db just makes those backups easier.  You can
put the table inside whatever database you'd like(including Nuke),
however there's no support for a table prefix at this time.

    Edit the modules/Donations/config.inc.php and enter the approporiate
sql credentials.
    Go to the Nuke Admin panel and enable the "Donat_o_Meter" block
and the "Donations" module.  Make sure the Donatometer displays
correctly and check the link to the Donations module on the
"Make a Donation" button.

======
PayPal
======
    In the admin panel, click the Treasury icon and then click on the
"Config" button.  Scroll down towards the bottom in the PayPal
Configuration box and find and find the option "PayPal Receiver Email".
Enter the email address registered in your PayPal account that you
would like to receive donation on.  I highly recommend you have a special
email address for this.  This mod will show all payments made to this
address, whether they came from this mod, or not.  Click on a Submit
button once you have entered the email address.
    This should take you back to the Treasury panel, click onthe config
button again scroll down to the bottom and find the box labeled
"IPN link for PayPal". The URL to the right should be the complete URL
that points to the IPN file PayPal needs.  Click on the link provided
to test the IPN file.  Keep this window open during the next step as we
will need to copy out the IPN URL.
    Assuming the files tests ok, we now want to open up our PayPal
account.  Find your account "Profile" in PayPal and look for:
"Instant Payment Notification Preferences".  In there you should see
2 options: one to enable IPN and the other called:
"Instant Payment Notification (IPN) URL".  In this field you'll enter
the complete URL listed in the previous window on the Treasury config
page.  it should be something like this:

http://www.mywebsite.com/modules/Donations/ipn/ipnppd.php

If your Nuke site is not in the root, then:

http://www.mywebsite.com/nukename/modules/Donations/ipn/ipnppd.php

"nukename" is, of course, whatever folder you have under your site root.

Your IPN is enabled!

==================
Nuke Configuration
==================
    The NukeTreasury includes a plethora of configurable options.
To get started all you need to configure is the "PayPal Receiver Email"
which we did above.  All the other options are gravy.  Each option
has a tool tip that describes it's use.  Practically every option
involved in this mod is configurable.  It was designed so that no
file editing was required.  The Donatometer block and Donations module
are pulled from template files located in modules/Donations.  If you
like you can edit these html templates to further customize this mod.
I tried to lay out the tags as clearly as I could to ease customization.
    The text listed in the Donations module is actually stored in the
database and you can customize it on the Treasury Config page.  This
text block can contain any HTML markup you like and remember it's HTML
(so you need <br>'s for line breaks, for example)


==============
NOTES on usage
==============
-The PayPal IPN is a live transaction and can only occur when the
payment is actually made.  There is no way to receive IPN's for past
transactions.  This is inherent in the PayPal IPN design.
-Refunds are properly handled.  If you have logging enabled, and you
refund a payment you will see a log entry:
"Valid IPN, but not interested in this transaction"
This a normal log entry for a refund.  The PayPal actually sends 2
IPN's that relate to a single refund.  This mod only needs one of the 2.
The log entry is for the second, un-needed IPN.

   

============
Known Issues
============
-The Treasury admin panel can only be accessed with "Super User" privs.
This is primarily because Nuke is not easily adapted to allow customized
admin panel priviledges.  This would require a php code change when
no php code changes are required at all for this mod.
-The IPN transactions and log is only viewable directly from the database,
and through tools such as phpmyadmin.


=======
Testing
=======
-Once you have this mod fully configured you should make a test
donation.  You can do this by making a normal donation that you can
later refund in full.  In PayPal, looking at the details of the
transaction for the donation you just made, you should see a link
where you can refund the payment.  You can make and refund as many
payments as you like without any cash penalty.



Have fun!

The URL to the right should be the complete URL
that points to the IPN file PayPal needs.  Click on the link provided
to test the IPN file.  Keep this window open during the next step as we
will need to copy out the IPN URL.
    Assuming the files tests ok, we now want to open up our PayPal
account.  Find your account "Profile" in PayPal and look for:
"Instant Payment Notification Preferences".  In there you should see
2 options: one to enable IPN and the other called:
"Instant Payment Notification (IPN) URL".  In this field you'll enter
the complete URL listed in the previous window on the Treasury config
page.  it should be something like this:

http://www.mywebsite.com/modules/Donations/ipn/ipnppd.php

If your Nuke site is not in the root, then:

http://www.mywebsite.com/nukename/modules/Donations/ipn/ipnppd.php

"nukename" is, of course, whatever folder you have under your site root.

Your IPN is enabled!

   global $nukeurl;
   $desc = 'This box shows the link to the IPN recorder.
This link must be pasted EXACTLY as it is
into your PayPal IPN profile.  You can click
on the "test" link to the right to verify
that the IPN recorder is functioning correctly.';
$desc = htmlentities($desc);
    echo "<tr>"
     ."<td title =\"$desc\" bgcolor=\"$bgcolor2\" align=\"right\"><b>IPN link for PayPal</b></td>"
     ."<td title =\"$desc\" align=\"left\">&nbsp;$nukeurl/modules/Donations/ipn/ipnppd.php&nbsp;&nbsp;<a href=\"$nukeurl/modules/Donations/ipn/ipnppd.php?dbg=1\" target=\"_blank\"><b><i>Click here to test IPN</i></b></a></td>"
    . "</td></tr>";
   echo "</table><br>";