README.txt for pm_email_notify (last updated: Feb 10, 2009)


pm_email_notify Versions
----------------
Version:        1.0
Released On:	Feb 8, 2009
Notes:
1. First build, not part of Drupal versioning system yet.
2. Installed and working on my site (www.lbshooters.com).  
3. Needs to be tested by other members of Drupal community.

Version:        1.1
Released On:	Feb 9, 2009
Notes:
1. Removed dependency on Subscriptions module by adding own mail function.
2. Removed the need to enter your own Domain in the DEFINE section (using !site instead).
3. To update from version 1.0 simply overwrite .txt, .info, and .module files,
    settings won't be affected.

Version:        1.2
Released On:	Feb 10, 2009
Notes:
1. Fixed email message text, by using !uri instead of !site (I went with Rachel's template).
2. Fixed indentation and {} placements to adhere to Drupal coding standard.
3. Run the code through coder module and fixed all warnings.
4. To upgrade from version 1.1, simply overwrite all the files, previous settings
   won't be affected.

Wishlist
----------------
1. Implement changes pointed out by Berdir:
    a) convert default email notification variable to a privatemsg setting
    b) get rid of helper function for form notification page
    c) use message_submit hook once its commited

Intro
----------------
The original thread discussing pm_email_notify can be found here:
http://drupal.org/node/357093

I (Eternal21) decided to write the pm_email_notify module, 
after porting my site from phpBB forum to drupal, and realizing 
that Drupal misses many of the features I took for granted in phpBB environment.
  
This is my first Drupal module, so I'm sure there are better ways
of accomplishing the end result.

Since I'm new to Drupal development, I basically looked at other modules
interacting with privatemsg module (like pm_block_user or privatemsg_filter),
and based interactions of my module on those.


Code Overview
----------------
pm_notify_module performs two basic tasks:
1. It stores whether user wants to be notified of PM's via email or not.
2. It notifies the user of incomming PM's.

The first task is accomplished by storing the preference in pm_email_notify
table inside drupal database.  There are two fields - user_id, and
email_notify_is_enabled (1 = enabled, 0 = disabled).

The second task is done through Subscriptions module, by calling it's
mail function.

The call to pm_notify_module email notification hook is placed right after
privatemsg module sends PM.  That way email notifications are sent only when
PM is succesfully sent.


Installation
----------------
1. You will need the following modules in order for pm_email_notify
    module to work:
    -privatemsg (http://drupal.org/project/privatemsg)

    If you haven't done so yet - visit the link above and install/enable
    the module before proceeding.

2. Download the pm_mail_notify.zip file from the following location:
    http://www.box.net/shared/5gpjtx0hi6
   Unzip the pm_email_notify.zip file, you will end up with the
    following files:
    -README.txt
    -pm_email_notify.info
    -pm_email_notify.install
    -pm_email_notify.module

3.  Email notifications are enabled for users by default.  If you
    want to disable email notifications by default, open up the
    pm_email_notify.module file with any text editor, and modify
    the following line by replacing 1 with 0:

    define("DEFAULT_EMAIL_NOTIFICATION_SETTING", 1);

4. Create the following folder on your website inside privatemsg directory:
   pm_email_notify/
   (You can find privatemsg/ directory inside /sites/all/modules/ directory, or
    sometimes inside /modules/ directory)

5. Upload the 4 unzipped files into that folder.

6. Log in as admin user into your drupal website, and go to
    Administer->Site Building->Modules page.

7. Scroll down to Mail group, and enable the box next to
    PM Email Notification module.  (NOTE:  The box will be grayed out,
    if you haven't installed and enabled Privatemsg module first)

    This will create a table inside your drupal database
    called pm_email_notify that stores users notification preferences

8. The last step of installation is adding a call from privatemsg module
    to pm_email_notify module.
    a) download the following file from your website:
    /privatemsg/privatemsg.module

    b) find the following piece of code inside the file (around line 637:

    // 2) Save message to recipients.
    // Each recipient gets a record in the pm_index table.
    $query = "INSERT INTO {pm_index} (mid, thread_id, uid, is_new, deleted) VALUES (%d, %d, %d, %d, 0)";
    foreach ($message['recipients'] as $recipient) {
        $mid = $message['mid'];
        $thread_id  = $message['thread_id'];
        db_query($query, $mid, $thread_id, $recipient->uid, 1);
    }

    c) add the two lines at the end of the foreach loop so that you end up with the following:

    // 2) Save message to recipients.
    // Each recipient gets a record in the pm_index table.
    $query = "INSERT INTO {pm_index} (mid, thread_id, uid, is_new, deleted) VALUES (%d, %d, %d, %d, 0)";
    foreach ($message['recipients'] as $recipient) {
        $mid = $message['mid'];
        $thread_id  = $message['thread_id'];
        db_query($query, $mid, $thread_id, $recipient->uid, 1);
        // 2a) Notify each recipient via email that they have been sent a private message
        module_invoke('pm_email_notify', 'privatemsg_notify', $message['author'], $recipient);
    }

    d) Upload modified file back to your drupal website.

9.  At this point PM notifications should be functional.  Each user can adjust
    their PM notification settings at the following location:
    /messages/notify


Further Customization
----------------
To modify the text of notification message, change the 'subject' and 'body'
variables in pm_email_notify_mail function inside pm_email_notify.module.


