===== Event Notification Handler =====

<<[[Ticket:56]]<<

Believe it or not, I wrote this code before I found out about PageWatches but I think my approach is a little different.

Basically, I wanted something that would email people in my office whenever somebody posted a comment on a page of interest. I thought I would make it a little more robust however. This should be a framework that will allow wikka to automatically react to a variety of page events (i.e. commenting a page, editing a page etc) and trigger some response (i.e. emailing a user, sending an http request to a server etc.)

This isn't finished, yet it is currently running in my office, so I know it works.

Steps:
1) Create new event watching table.
1) Create a handler to register an event for a page to watch.
1) Create a response function (i.e. email notification).
1) Add code to look for and process a page event. Then call a response function.
1) Make handler easily accessible for users.

===== 1.) Create Table =====

%%(sql)
CREATE TABLE `wikka_watches` (
`page_tag` VARCHAR(75) NOT NULL,
`watcher` VARCHAR(75) NOT NULL,
`comment` ENUM('Y','N') DEFAULT 'N' NOT NULL,
`edit` ENUM('Y','N') DEFAULT 'N' NOT NULL
)
TYPE = myisam;

ALTER TABLE `wikka_watches` ADD UNIQUE (`page_tag`,`watcher`)

ALTER TABLE `wikka_watches` ADD INDEX (`page_tag`)

ALTER TABLE `wikka_watches` ADD INDEX (`watcher`)
%%

This will create a table that will store a page_tag and watcher pair. The watcher isn't restricted to being a username. It could be the name of a wikipingserver or something like that. Each column after that corresponds to a particular page event with a simple indication of whether or not that event is being watched for.

===== 2.) Create 'addwatch' handler =====

Create a file called addwatch.php in your handlers directory. Add this code:

%%(php)
<?php

/**
* Creates a watch on this page for a watcher.
*
* Usage: append /addwatch to the URL of the page
*
* This handler registers a watch in the database on this page
* for a watcher. Watches can be used to generate events when
* certain things are done to a page. (i.e. email a user when a page
* is commented on.)
*
* @package Handlers
* @subpackage
* @name addwatch
*
* @author {@link http://wikka.jsnx.com/RyeBread RyeBread} - original idea and code - Dec.06.2005
* @copyright Copyright © 2005, Ryan Jarvis
* @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
* @version 0.1
* @since Wikka 1.1.6.X
*
* @todo
* 1. Allow handler to take in params specifying what kind of watch should be made
* 2. Enable setting of watcher that isn't a user (i.e. a wikiping server).
*/

do {

if (!$this->page) {
$this->SetRedirectMessage("Found no page for this handler.");
break;
}

if (!$this->GetUser()) {
$this->SetRedirectMessage("You must be registered to add a watch.");
break;
}

//TODO: get type of watch from a param
//passed into the handler.
//
//get type of watch
$type = "comment";

//check if watch type is valid
$validity = $this->Query("SHOW COLUMNS FROM " . $this->config["table_prefix"] . "watches LIKE '" . $type . "'");
if (mysql_num_rows($validity) == 0) {
$this->SetRedirectMessage("Watch type is invalid.");
break;
}

//get page name
$tag = $this->GetPageTag();

//TODO: optionally specify the id of the
//watcher instead of assuming user name.
//
//get watcher
$watcher = $this->GetUserName();

//register watch in database
$existing = $this->Query(
"SELECT * FROM " . $this->config["table_prefix"] . "watches " .
"WHERE page_tag = '" . mysql_real_escape_string($tag) . "'" .
"AND watcher = '" . mysql_real_escape_string($watcher) . "'");

if (mysql_num_rows($existing) == 0 ) {
$this->Query(
"INSERT INTO " . $this->config["table_prefix"] . "watches SET ".
"page_tag = '" . mysql_real_escape_string($tag) . "', " .
"watcher = '" . mysql_real_escape_string($watcher) . "', " .
$type . " = 'Y'");

$this->SetRedirectMessage("You are now watching this page for " . $type . "s.");
break;
}

if (mysql_result($existing, 0, $type) == 'Y') {
$this->SetRedirectMessage("You are already watching this page for " . $type . "s.");
} else {
$this->Query(
"UPDATE " . $this->config["table_prefix"] . "watches SET ".
"page_tag = '" . mysql_real_escape_string($tag) . "', " .
"watcher = '" . mysql_real_escape_string($watcher) . "', " .
$type . " = 'Y'");
$this->SetRedirectMessage("You are now watching this page for " . $type . "s.");
}

mysql_free_result($existing);

} while (0);

$this->Redirect($this->Href());

?>
%%

As it stands right now, when a registered user invokes this handler on a page, the wikka_watches table will be updated to indicate that this user wants to be notified whenever this page is commented on.

===== 3.) Create 'notify' base function =====

In wikka.php, I added this function at line 972 before MAINTENANCE

%%(php)
//COMMUNICATION
function Notify($to = "", $subject = "", $body = "", $altbody = "")
{
<insert your specific mailing code here>
}
%%

Obviously, how you send mail is dependent on your server setup. I don't use the default mail() function. Instead, I have phpmailer setup, and I use it on an SMTP configuration. If somebody wants to see what I wrote for this function that uses phpmailer, let me know.

Also, it should probably be called '""NotifyOnEmail""' as there might be additional notify functions created that belong to this family.

===== 4.) Invoke Event Processing somewhere =====

Keeping in mind that I want people to be notified of comments made on pages, I decided to invoke the event processing in the 'addcomment.php' action.

Firstly, I have no idea if this is the best place for it to go (as opposed to being added directly in the ""SaveComment()"" function). Secondly, there needs to be a generic event-processing-wrapper of some kind that takes a callback function (such as notify) as a parameter. I'm working on that.

Add the following to 'addcomment.php', line 18, right after STORE NEW COMMENT

%%(php)
//trigger watches
$watches_table = $this->config["table_prefix"] . "watches";
$users_table = $this->config["table_prefix"] . "users";
$watch_query = "SELECT " . $users_table . ".email " .
"FROM " . $watches_table . "," . $users_table . " " .
"WHERE " . $watches_table . ".page_tag = '" . $this->tag . "' " .
"AND " . $watches_table . ".watcher = " . $users_table . ".name";
$watches = $this->LoadAll($watch_query);
foreach ($watches as $email) {
if ($email["email"] == '') {
continue;
}

$this->Notify($email["email"], $this->tag . " commented by " . $this->GetUserName(), $body);

}
%%

===== 5.) Make handler visible =====

Obviously, I want to make it easy for my users to add watches, so I just hacked the following. It adds a link to the footer.

Add the following to footer.php, line 5 after the 'Edit Page'

%%(php)
echo $this->GetUser() ? "<a href=\"".$this->href("addwatch")."\" title=\"Click to watch this page\">Watch page</a> ::\n" : "";
%%

Now I don't really want to hack footer directly, plus, I want to be able to support adding watches of different types, so I need to eventually construct a separate menu altogether.

~& How about a ""{{watch}}"" action instead? --NilsLindenberg

===== Conclusion =====

Whenever a user in my wiki comes across a particular page of interest, he or she can click on the "Watch page" link at the bottom, and it will record the request to be notified. Thereafter, whenever somebody leaves a comment on that page, the user will receive an email containing the comment in the body of the message.

===== TODO: =====

- Create an "removewatch" handler.
- Create a form in the user settings page that will allow people to manage their watches and add/remove/edit at will.

Comments/feedback highly desired. Thank you.
:)

----
CategoryUserContributions