Installation, usage and API

Installation

Required modules

Flags

• Using the flag administration page (admin/structure/flags) set the flags for subscribing to comments, content and (optionally) organic groups.
• Tested with version 3.0, but it **should** works also with Flag 2.x.

Suggested modules

Queue mail

• This module puts emails on a queue instead of firing them all at once
• To make it works with Flag_notify, just add the flag_notify send emails function in the queue configuration page (add "flag_notify_*" in the "Mail IDs to queue" form under admin/config/system/queue_mail page).

Organic groups

• If available, it allows notification (comment, content, new users) at group level.

Views + View bulk operation

• View and VBO allows you to provide users with a nice views of the group/content/comment they subscribed so that users can manage their subscriptions.
• The view itself is not provided by the flag_notify module, but it is easy to be implemented

Installation steps

1. Download and enable the Organic Group module before Flag Notify if you want to use group notification
2. Download and enable the Flag module like usual
3. Download and enable this module like usual
4. Using the Flag administration page, create one flags for subscription to comment (flag type: comments), one flag for subscription to content (flag type: nodes) and one flag for group notification (flag type: nodes). You can set the flags as of your preferences, e.g. choosing which content types should be available for subscription. Any of these three levels is optional. For example:
   
5. Configure Flag Notify under admin/config/system/flag_notify, notably picking up the Flags you created in the previous step and choosing some elements of the notification message, like the salutation and the footer:
   
6. On admin/config/people/accounts/fields/flag_notify_field_defaults set the site-defaults (for all the new users of the site) of the user-defaults for notification subscription, e.g. if an user should get auto-subscribed to the comments he/she write. The users can then still subscribe/unsubscribe to individual items.
7. Optionally, create a view (suggested using View Bulk Operation) to allow users to manage their subscriptions and set its path in the Flag Notify configuration page, so that a link to it will be shown on each notification. For example:
   

Troubles

If you install the og module AFTER having installed this module, and you want to use this module for notification of group activity, you have to manually edit the field "field_notification_defaults" in the configuration of user profiles to include a default option for group activity notifications and give it the 'group' key, so that in "allowed values" you will have:
group|Activity in the groups you join
content|New comments and modifications on content you create
comment|Replies to your comments
These defaults affect only new users, so if you install this module on a
established site, you have to manually give existing users the default options you require (you can do that quickly using VBO).

Usage

When an user post a comment, edits a content or enrols in a group, the system will catch the event and sent the corresponding notification message to all the involved users.
If you need for any reason to perform an operation that risks to send lot of unwonted notifications (e.g. making an automatic update of the nodes), you can temporary pause the notifications in admin/config/system/flag_notify. When the notification system is paused events to not generate emails at all (e.g. emails are not even queued for later delivery).

API

This module provides a powerful api to allow users interact with it creating their own module and implementing the hooks defined in the file flag_notify.api.php contained in the module (that we refer to for a detailed description of the hooks and their parameters).

Two main user-cases are possible.
The first one is that you want to implement your own logic in order to better decide on which notifications should be sent.
Since Flag Notify 7.x-1.0, you can "intercept" the notification chain and change the event data or "break" it using the hooks.
For example, if you have a chat_room node type where comments are chat posts and you don't want to bother all group users with notification of each chat message you could create a module and write:

/**
 * Implement hook_flag_notify_event_alter()
 *
 */
function MYMODULE_flag_notify_event_alter(&$break, &$event, &$groups, &$node, &$comment, &$user) {
 if($node->type == 'chat_room' && $event == 'new_comment'){
   $break=TRUE;
 }
} 

The other user case is when you want to personalise the notification message.
Again, you can use an hook for that (hook_flag_notify_message_alter())
Using your own module instead of a token-based system allows for a very broad possibilities of personalisation of the email. If you use the t() function you will also be able to send the message in the preferred language of the target user.

To help you with the personalisation of the message you can use this example module (zip - tgz).
Download, unzip it and place it together with the other modules (e.g. in /sites/default/modules). You can then change the content of the flag_notify_message_alter_flag_notify_message_alter() function and enable the module to get the notification messages exactly as you want them !