Watcher Module for Drupal 6.x

Feature overview

    * Lets users watch nodes for changes or new comments being posted without
      having to post themselves.+
    * Uses AJAX to toggle watching for a smooth user experience.
    * Allows both anonymous and registered users to watch nodes.
    * Supports email notifications being sent when both or either of the
      above occurs.
    * Template-based notification messages using the Token module - edit the
      templates to your liking!
    * Provides a binder with an overview of the nodes you watch. From the
      binder you can also toggle email notifications for each node you watch.
    * Users may choose to publish the binder so that other users can see what
      they're watching, providing a form of social bookmarking.
    * Uses a queue-based email dispatcher to handle large numbers of notifications.
    * Users can opt to automatically watch nodes they create or comment on.
    * User settings can have default values, set by the site owner, that can be
      customized and overridden by the user.
    * Highly customizable, configurable user interface and themeable.
    * Designed with usability and exceptional user experience as a high priority.

Watcher was developed to fill a gap that has existed for a long time. Even
though there are several subscription and notification modules out there,
none is both easy to use or particularly specialized and allows instant
(or near instant) notifications. Watcher is not a general solution to
notifications but caters to the needs of community sites.

+Added in the Drupal 6 version.


Requirements
------------
To install this version of Watcher you need:

* Drupal 6.x
* Comments module (included in Drupal)
* Node module (included in Drupal)
* Token module (http://drupal.org/project/token)

There's a version for Drupal 5 as well, available from:
http://drupal.org/project/watcher


Installation
------------
To install Watcher, do the following:

  1. Download, install and configure the Token module, follow the
     instructions for that module.

  2. Download the latest stable version of Watcher from its project
     page: http://drupal.org/project/watcher

  3. Unpack the file you downloaded into the modules directory of your site.

  4. Go to Administer » Site building » Modules and enable the module.

  5. Go to Administer » Site configuration » Watcher and select at least
     one content type for the module.

     NOTE: The module will not work and users will not be able to watch
     posts unless you select at least *one* content type.
     Click "Save configuration" to save your changes.


Upgrading from Drupal 5
-----------------------
If you've been using a previous version of Watcher, make sure you go to update.php
and run the update script after uploading the new module files.


Issues
------
In case Watcher does not appear to work for anonymous users even though the
role Anonymous has been granted the necessary permissions, your users table
may be missing the anonymous user.

To fix this, first empty your site's cache. You can do that by going to
Administration » Site Settings » Performance

Secondly, make sure there's a row with uid 0 in your site's users table.
You can confirm that by executing this SQL query:
SELECT * FROM `users` WHERE uid = 0;

The query should return exactly one row. If no row is returned, the row is
missing and must be restored. Execute this query to add the row:
INSERT INTO `users` VALUES (0, '', '', '', 0, 0, 0, '', '', 0, 0, 0, 0, NULL, '', '', '', NULL);

See: http://drupal.org/node/370459


CAPTCHA support and preventing spam
-----------------------------------
Since Watcher now supports anonymous users watching nodes, CAPTCHA support has
been added to help prevent spam submissions. Download CAPTCHA module:
http://www.drupal.org/project/captcha

Watcher is known to work with CAPTCHA 6.x-1.0-rc2 and probably also all subsequent
6.x-1.0 release. Compatibility with 6.x-2.0 and later is not confirmed at this point.

Install CAPTCHA and set up its permissions as needed. Then go to:
admin/user/captcha/captcha/captcha_point

Enter "_watcher_watch_toggle_anonymous_form" (quotation marks omitted) in the
"Form ID" field. Select a challenge type and save the form. CAPTCHA will now display
the challenge you selected when anonymous users want to start watching a node.

To implement a first line of defense against spambots you can use the Bad Behavior
module. It uses heuristics to determine whether the browser is a genuine
human-controlled software application or an automated spambot:
http://drupal.org/project/badbehavior


Configuration
-------------
The module can be configured by going to:
Administer » Site configuration » Watcher

You can customize a wide range of options. Most of this is quite straight-forward
however some things may require an explanation.

Under "Settings for Email Notifications" you can choose what method to use for
sending emails. This will have an impact on how many messages are sent at once.
Watcher stores notifications to be sent in a message queue and every time messages
are sent they're taken off the queue. The method affects when the queue messages are
actually sent, it can either happen when cron and cron.php is being run or when a
user posts a comment.

If there are many messages in the queue, the best setting to use is cron and making
sure cron is run frequently enough that the entire queue is being processed. You can
change the time limit for message sending. The server will send as many messages as
possible during this interval. Any messages left unsent will remain in the queue
until it is processed again.

You may also modify the notification message templates that are used to generate the
notification messages. You can use placeholder tokens to insert the content that
changes, such as recipient name and comment excerpt.

Watcher also allows every user on your site to customize how the module works for them.
Users may enable or disable email notifications and make it so that they automatically
watch every post they make or comment on. Users who have not yet altered these settings
will be affected by the user settings defaults. These default settings apply until a
user goes to his or her settings page for Watcher and clicks "Save".

The page titled Statistics shows some basic statistics about the module which may be of
interest to you as a site owner. If there are unsent messages in the message queue,
these can be viewed here as well.

The Testing page allows you to do testing in case notification messages are not being
delivered. You can create test messages that are sent to your own email address.


Retroactively add existing posts
--------------------------------
If you have a large site and a large quantity of nodes/posts you may want to add the
existing nodes your users have made or commented on to their watched posts lists.

You can do this by running the SQL queries below. The queries below will do the
following:
- add all posts a user has created to his/her watched posts list
- add the nodes belonging to every comment a user has made to his/her watched posts list

CAUTION: Make a database dump to keep as a backup copy before attempting this!
CAUTION: The following has only been tested with MySQL 5!

INSERT IGNORE INTO watcher_nodes (uid, nid, send_email, added) SELECT uid, nid, 1, UNIX_TIMESTAMP() FROM node;
INSERT IGNORE INTO watcher_nodes (uid, nid, send_email, added) SELECT uid, nid, 1, UNIX_TIMESTAMP() FROM comments;


Theming
-------
Watcher is entirely themable. Open watcher.module in your editor to see what
theme functions are available to be overridden. The functions are documented in
detail in the code.

Themable functions of interest:
  * watcher_binder($intro_text, $posts_table_header, $posts_table_body)
  * watcher_binder_email_icon($t, $type, $url, $dest)
  * watcher_binder_stop_watching_icon($url, $dest)
  * watcher_node_toggle_watching_link($uid, $nid, $dest, $user_is_watching)
  * watcher_help_page($content)

Watcher outputs the watcher link at the end of the node's body by default. A future
feature will be to make this configurable, allowing the link to be output in the
node's links section, at the beginning or end of body or in a separate template
variable. Until then, you can use the following method to separate the watcher link
from the node's body.

In node.tpl.php, to display the watcher link:

  <?php if($node->content['watcher']['#value']): ?>
    <div class="node_watcher">
      <?php print $node->content['watcher']['#value']; ?>
    </div>
  <?php endif; ?>

And the node's body:

  <div class="content">
    <div class="content_description"><?php print $node->content['body']['#value']; ?></div>
  </div>

For more info, please see: http://drupal.org/node/11816


Terminology
-----------
I have tried to consistently use the term "post" in the parts of the module that
the end users see as it makes way more sense to non-Drupallers than the word "node".
In the code comments and documentation, I've used the word "node" where I talk
about nodes.

The word "binder", is used interchangeable with the term "watched posts list". They're
exactly the same thing, "binder" is a term Hans Dekker of Wordsy.com suggested and it's
stayed in the module since its first versions.


Author
------
The module was developed by Jakob Persson <http://drupal.org/user/37564> of
NodeOne, Sweden's leading Drupal consulting firm. Our goal is to empower the
user by building usable, powerful and effective web solutions for our clients.
Visit us at http://www.nodeone.se

I am a developer that considers usability and user experience to be some of the
defining properties of successful software applications as well as devices and
appliances. I have a background in cognitive science and HCI and I work with
user experience and usability at NodeOne, building beautiful, usable
web sites and intranet applications for our clients.

The author can be contacted for paid customizations of this module as well as
Drupal consulting, installation, development and customizations.


Sponsors
--------
The development of this module has been sponsored by

  * Wordsy <http://www.wordsy.com>
  * NodeOne <http://www.nodeone.se>


Thanks
------
To Hans Dekker <http://www.hansdekker.com> for the idea as well as suggestions
and feedback.

Some of the icons were either taken directly from the Tango Icon Library or were
derived from Tango icons.
http://tango.freedesktop.org/
