In conjunction with a similar feature for Manila, we're working on a
feature for notifying Radio users via email when new comments are
posted to their sites.

We'd like to give developers an opportunity to comment on the
implementation before releasing the feature.

This message is cross-posted to manila-dev because Manila hosts the
comments for Radio users, and some of the implementation of this
feature will be in Manila.


*** Preferences in Radio

There's only one new preference for this feature -- a checkbox for
whether to send comment notification via email. On the Prefs -> Weblog
-> Comments page:

[x] Check this box to receive notification via email when new comments
are posted.

The default is checked. The value of the pref is stored at
weblogData.prefs.flCommentNotificationEnabled.

Comments are sent to the email address specified on the Prefs -> Basic
Preferences -> User Identity page, which is stored at
weblogData.prefs.authorMailAddress.


*** Connecting to the comments site

Any Manila site can host comments for a Radio weblog, and Manila
currently has no direct way of knowing where to send the emails, or
whether to send them at all. Radio needs a way to send this information
to the Manila site that hosts its comments.

The most flexible way to do this is for Radio to make an XML-RPC call
to the Manila site, but first Radio needs enough information about the
site to make the RPC call. Radio does this by making a request to the
comments page, whose URL is the one bit of data that Radio has about
the comments site. The request has an argument in the URL c=getRpcInfo,
which means "send me your XML-RPC information". Here's an example
request:

GET /comments?c=getRpcInfo HTTP/1.0
Host: radiocomments.userland.com

The body of the response is XML. It contains information needed to call
the Manila site using XML-RPC. Here's an example response:

HTTP/1.1 200 OK
Connection: close
Content-Length: 139
Content-Type: text/xml

<rpcInfo>
<server>radiocomments.userland.com</server>
<port>80</port>
<path>/RPC2</path>
<methodName>manila.radioHosting.setPrefs</methodName>
<siteName>radioComments</siteName>
</rpcInfo>

This request is made by radio.thread.agents.pingCloud, and the data is
stored in a table at weblogData.prefs.commentServer. (The request is
made only once.)

Once Radio has the XML-RPC information, it makes the following XML-RPC
call to the Manila site, also from radio.thread.agents.pingCloud, to
set preferences for comment notification:

manila.radioHosting.setPrefs (siteName, usernum, data) -- returns true

siteName is the canonical name of the Manila site that hosts comments
for the Radio weblog, as returned in XML in the above request.

usernum is the Radio user's usernum, which corresponds to the "u"
argument in the comment pop-up window URLs.

data is a struct which contains the following sub-elements:

flNotifyNewComments -- a boolean, true if the user wants comment
notification via email (corresponding to the new preference described
above)

sendNotificationTo -- a string, the email address notification will be
sent to

We're using a struct for the data parameter in case more information
needs to be sent to Manila using the setPrefs call in the future.


*** Manila implementation

Manila stores metadata about comments in the radioHosting sub-table of
the site's #newsSite table.

A new sub-table of the radioHosting table named userPrefs will store
preferences for the Radio users whose comments the Manila site is
hosting. This sub-table is populated by calls from Radio to
manila.radioHosting.setPrefs, and contains two sub-items,
flNotifyNewComments and sendNotificationTo.

When a new comment is posted to a Radio site, Manila checks to see if
the corresponding usernum has preferences defined in the
["#newsSite"].radioHosting.userPrefs sub-table. If defined, and if the
value of flNotifyNewComments is true, then Manila will send email
notification of the new comment to the email address defined by
sendNotificationTo.


*** Comments and Questions

If you have comments or questions, please post them as a response to
this message.

Thanks,
-Jake