Installation And Documentation
Table Of Contents
Introduction
Preconfigured Default Comment Listing Template
Customizing Your Own Templates To Use EZ Subscribe To Comments
Upgrading From ScriptyGoddess
Description Of EZ Subscribe To Comments Functions By User Interface Page
Technical Notes
System Requirements
Disclaimer
Copyright


EZ Subscribe To Comments is a cgi script designed for use with MovableType. By now, you have placed it in your root MovableType cgi directory, set permissions to 755, and pointed a URL to the script. This section will outline instructions for putting this script to use in your blogs.


Briefly (more details may be found in the technical notes), this script intercepts comment postings by readers of your blog, allows for various tests to validate the comment, records requests to subscribe to posts (that is, requests to be notified when new comments are posted), and then sends out a notification by email to valid subscribers any time a comment is posted to that particular entry. What makes this script unusual is that it does all this with NO hacking of your MovableType installation or any of your plugins. This was a large job to code, and may absorb further improvements on the visuals, but the functionality is here and waiting for you.

You will need to add some fields to your MT Comments Template so that readers can elect to subscribe to the entry's comments either with or without posting themselves. This is easy to do. You simply add a few fields (and some hidden ones to carry forward some necessary information). If you have installed the old ScriptyGoddess Subscribe To Comments script that runs in PHP, then you only have to change the two URL's in the templates, and you're done.

First, the easiest method for starting from scratch, and then a more detailed explanation. If you are using default MT Comments Templates, then here is one that has the necessary changes already made, and you may just copy and paste the whole thing.

Comment Listing Template


How to customize your own templates for this script:

If you have already customized your Comment Templates for your own purposes (and thus do not wish to copy and paste the default template above), then you can follow these easy instructions to add this script's functions to your templates. First, open the MT Comment Listing Template, and search for the following string:

   form method="post" action=

That search will bring you to these lines:

<form method="post" action="<$MTCGIPath$><$MTCommentScript$>" name="comments_form" onsubmit="if (this.bakecookie[0].checked) rememberMe(this)">
<input type="hidden" name="entry_id" value="<$MTEntryID$>" />


Note that this is a <form> tag and that the "action" URL consists of two tags, one for your MTCGI Path and another for the MT Comments Script. You wish to replace the Comments Script tag with the EZ Subscribe To Comments script name. Here are the same lines, properly configured, with the change marked in blue.

<form method="post" action="<$MTCGIPath$>sub-to-com.cgi" name="comments_form" onsubmit="if (this.bakecookie[0].checked) rememberMe(this)">
<input type="hidden" name="entry_id" value="<$MTEntryID$>" />


That was painless, eh? Next, we want to add our radio buttons to allow users to subscribe. We want to put these at the end of the form, so we search for the close form tag:

</form>

This reveals the end of the form, and we are looking at the close form tag and the several lines above it:

<input type="button" onclick="window.close()" value=" Cancel " />
<input type="submit" name="preview" value=" Preview " />
<input style="font-weight: bold;" type="submit" name="post" value=" Post " /><br /><br />

</form>


We are going to be sqeezing three hidden fields, two radio buttons (subscribe and unsubscribe), and a line of text into the space between the three lines you found and the </form> tag you also found. Here are the same lines, with the appropriate additions marked in blue:

<input type="button" onclick="window.close()" value="&nbsp;Cancel&nbsp;" />
<input type="submit" name="preview" value="&nbsp;Preview&nbsp;" />
<input style="font-weight: bold;" type="submit" name="post" value="&nbsp;Post&nbsp;" /><br /><br />

<input type="hidden" name="blogname" value="<$MTBlogName$>"/>
<input type="hidden" name="title" value="<$MTEntryTitle encode_html="1"$>"/>
<input type="hidden" name="link" value="<$MTEntryLink> "/>
<input type="radio" name="subscription" value="subscribe" /> Subscribe <br/>
<input type="radio" name="subscription" value="unsubscribe" /> Unsubscribe <br/>
(email field must be filled in)

</form>


Alright, that takes care of the standard Comment Form in the HTML. Now, we are going to create a second form in the same template. This is so that a reader may subscribe to an entry's comments without actually posting one. That requires a second, non-posting form in the template. Easy. We are going to stick the HTML for that form right after the </MTEntryIfCommentsOpen> tag which closes that container. So, search for that string:

</MTEntryIfCommentsOpen>

And the following lines towards the end of the Comment Listing Template will be revealed:

</script>
</div>
</MTEntryIfCommentsOpen>
</div>
</body>
</html>


We are going to squeeze our fields after the </MTEntryIfCommentsOpen> tag and before the </div> as shown below, highlighted in blue:

</script>
</div>
</MTEntryIfCommentsOpen>
<br/>
<form action="<$MTCGIPath$>sub-to-com.cgi" method="post" name="addsubscriber">
Enter email address to subscribe/unsubscribe to comments on this post without having to post a comment:<br />
<input type="radio" name="subscription" value="subscribe"> Subscribe<br>
<input type="radio" name="subscription" value="unsubscribe"> Unsubscribe<br> (email field must be filled in)
<input type="hidden" name="entry_id" value="<$MTEntryID$>" />
<input type="hidden" name="link" value="<$MTEntryLink$>" />
<input type="hidden" name="title" value="<$MTEntryTitle encode_html="1"$>"/>
Email: <input name="email" size="40" />
<input type="submit" value="submit" name="submit">
</form>

</div>
</body>
</html>


Note that the form "action" is the same as the other form, and points to our new script. That's it folks! Well, almost it. You can make the changes to the first form in the Comment Preview Template as well, if you like. That allows for the radio buttons there too. Obviously, you do not need the Subscribe Without Posting form, since you kinda gotta be posting something to preview it, by my reckoning anyway. You could also doctor up the Comment Error Template, but subscribers should not see this template because the script intercepts those errors, except where readers are blacklisted (see Jay Allen's MT-Blacklist plugin) in which case, they cannot subscribe anyway. So, rebuild, and you are on your way.

Upgrading from ScriptyGoddess:


This is the easiest thing in the world, and allows you to play with this script, and then revert back to ScriptyGoddess, or to switch to Chad Everett's Notifier script without much fuss. All you do is to search for these two lines (they will be in different parts of the template, but are together here for brevity:

<form method="post" action="<? echo $httpPathToFiles; ?>/emailtolist.php" name="comments_form" onsubmit="if (this.bakecookie[0].checked) rememberMe(this)">


<form action="<? echo $httpPathToFiles; ?>/addsubscriber.php" method="post" name="addsubscriber">


You then replace the form "action" URL's highlighted in red, with one's that point to our new script, as follows, with changes highlighted in blue:

<form method="post" action="<$MTCGIPath$>sub-to-com.cgi" name="comments_form" onsubmit="if (this.bakecookie[0].checked) rememberMe(this)">

<form action="<$MTCGIPath$>sub-to-com.cgi" method="post" name="addsubscriber">


Easy enough. Now you can rebuild, and then fire up this script by clicking on the URL that got you here in the first place. Go to the Import From Scripty Goddess Page, import your subscriptions, and give it a whirl. If you don't like it, change the URL's back, go to the Purge Data Page, Purge, and delete the script. That's it. EZ, as the name suggests.


The following sequence describes each page of this user interface, in case they are not self-explanatory:


Script: As you probably already know, this user interface cannot be accessed without signing in. Your MT username and password are used, and you have access through this script to whichever blogs you ordinarily have access to, i.e., the permissions are the same. If you have your MT cookie, you will not need to sign in to use this script.

Subscriptions: This page allows you to manage your subscriptions. You are presented with a pulldown menu of available blogs, sorted so that your most recent posts are on top. You select one, click Choose, and you are presented with another pulldown menu of all entries for that blog. If there are too many to manage, you may click the Filter button which will only list entries with existing subscriptions. The number of subscriptions or opt-outs is in parenthesis in the menu. You may also choose an entry by Entry ID using the box for that on the form.

When you choose an entry, you are presented with a list of subscriptions and opt-outs (if a reader asks never to be notified about comments to a given entry). You may delete any on these using a checkbox and button, or add any email addresses to either subcriptions or opt-outs. You may add addresses by pasting them all in at once as long as each is on its own line. Invalid addresses and duplicates will not be added. If you add an address to the subscription field, but it also exists in the opt-out field, it will still be added, but the opt-out field prevents any email from that entry being sent to that address. It is easy to manage deleteing these if you like.

Sitewide Opt-Outs: This page presents the blog choice menu, and then areas to add and delete sitewide opt-out addresses in the same manner as in the Subscriptions area. Having an address in this area means that the reader will never receive comments notification from your site, no matter where else they are subscribed. They are able to select this option from their own Reader Management Page, or they can request that you put their name in. They cannot undo it, and must contact you to be removed from the sitewide opt-out (which you can do from this page).

Customize Interface: This page gives you some control over the appearance of 1) the notification email, 2) your user interface, 3) the reader's interface, 4) the "processing" window, and 5) the "previewing" window. The first section of this page presents a breakdown of the notification email structure with fields that can be changed. Changes are stored in your databse, and persist unless/until you click Restore Default. All emails come from "yoursite.com" but you can change the sender. The default is "[email protected]" The Subject: field always has [<blogname>] at the beginning, and <entry name> at the end but you can customize the middle part. The default is "New Comment Posted to " which renders "[<blogname>] New Comment Posted to <entry name>" as the Subject. You could change this to "More thoughts have been posted on " or whatever else. There are then checkboxes on whether to include the Author name in the email, the Permalink to the entry, and the actual Comment Text. The default is all three included. Then there is a space for an individual note after the comment text, and finally a checkbox to include a link to the reader's management page (see notes about that page). With that link included, the readers can manage their own subscriptions at your page. These links are coded so that only the person receiving the email may access that area.

The next two areas contain CSS for the these user pages and for the reader page respectively. The default is a portion of the default MT stylesheet named "Georgia Blue". The stylesheet for the reader page is set to one column while the user's is set to two for this interface. You may change either stylesheet in any way you wish, to fit with your blog, but the reader interface may be the more important one, since only you will see the user interface (so maybe that's the most important, depends ...). The next two text areas contain the simple statements "Processing your comment ..." and "Previewing your comment ..." These are the windows your user sees after clicking either the Post or Preview buttons in your comments form. They appear for a few seconds each. You may put any text you wish in there, including HTML. You might just surround those phrases with some tags to make them bold or else completely customize them with annoying ads and messages. It's up to you.

Import ScriptyGoddess Subscriptions: This page does what it says. You must find the path to your ScriptyGoddess subscriptions directory (you can use your ftp client for this if necessary - or the command line - of course, or cpanel, or whatever). You first enter this path (a model default path is included, to give you the right idea). You then click "List Subscriptions" and if the path is right, all your ScriptyGoddess Subscriptions are listed! Then you click Import, and all non-duplicate, valid addresses are imported into the correct entries. You can go to the Subscriptions page then to see for yourself. The originals are, of course, left untouched, and it is an easy matter to return to using those, if so desired.

Purge All Data: Another page that does what it says. EZ Subscribe To Comments uses the MT Plugindata space in your database to store your subscriptions and configuration information. This will not conflict with any other processes and takes up minimal space, but in the interests of purity, you will want to purge the data if you decide to ditch this script. Click the button, confirm with the dialog box, and poof! Then you can remove the script or else start with a clean slate. Your old ScriptyGoddess subscriptions will, of course, remain in their original location. Of note, any time an entry's subscriptions have been deleted down to zero, that entry's data is removed from the database anyway. But this option unloads all of it.

Installation and Documentation: You're reading it.

Welcome: The opening page, with welcoming information.

Reader Interface Page: This page does not have a button associated with it. It is generated on the fly when reader's click on the link in their notification emails that brings them to their page. Each email address has a code associated with it at each entry. That code is required (it is part of the link) in order to access their page. Once they click on the link they are brought to their page and all of their subscriptions are listed. They may unsubscribe to any entries they are subscribed to, "permanently" opt-out of any they are subscribed to, or "permanently" opt-out of the whole. Permanent means you have to change it if you wish. The best way to work on the appearance of this page is to subscribe to one of your own entries and then click on the link that you get in the notification eamil, and bookmark that page. That way, you can visit repeatedly, while you experiment with the CSS. Note: If you delete that subscription, that bookmark will no longer be valid.


Technical Notes:


This script is written in Perl, and for real Perl coders, I apologize for the redundant, inefficient, and uncommented coding that you will encounter if you peer into the scripting. It was written from the top down as a single CGI script in order to make installation easy. It was written in the ten minutes's here and there between real-life meetings, and it shows. If there is particular interest in this script, I will clean it up as we go along. It uses the MT Perl API in most instances, and should be secure and well functioning.

What it does is to change the Comment form to post to the script first. Then the script opens a new "Processing" page that has hidden fields holding all the necessary information. What ScriptyGoddess did was to suck the subscription information out of that page, and then have it pass the process on to the original comments posting script. The trouble was, you could subscribe before the comment script decided whether it was going to accept your comment. With the advent of MT-Blacklist, this meant that evildoers could subscribe others to comments en masse if they wished, and there was no filtering. The challenge, then, was to write a script that handled subscriptions after MT-Blacklist and other filters. Chad Everett did this by hacking the MT code to hook in his cgi script. This is an extremely clean method, and is a nice way to go. You also have to hack MT-Blacklists overrides of the MT functions, in order to install Notifier.

I personally hate hacking my software code (well, except for MacOSX - I can't resist), and I promised myself I would write a subscription script to do function with NO hacking. That way, upgrades of MT or MT-Blacklist are unlikely to affect this script. So far, I have succeeded in this. The script allows all comments to be accepted or rejected by IP Banning, MT-Blacklist, and any other mechanisms in place before processing subscriptions. If the comment is rejected, so is the subscription. If you wish to subscribe without posting (a valuable feature, especially if some entries are dedicated to plugins or scripts you have written, where readers want to keep up with changes and problems), then, obviously, there is no comment processing. This method does run through MT's IP Banning however, and this confers protection against anyone wishing to subscribe people to comments out of sheer malice. The worse case is comment spam, and MT-Blacklist has us covered there.

System Requirements:


MovableType 2.6 or greater (uses Plugindata), and the Perl module Storable (used by Plugindata). If you are using MT-Blacklist, you are all set with these already.

Disclaimer:


This software is provided as is, with no guarantees, though a good faith effort has been made to ensure security and data integrity, etc. etc. Use at your own risk, which should be minimal.

Copyright:


This script is written by Oscar F Hills as a further exercise in High Intensity Time Wasting. The script is free of charge and restrictions, but I would appreciate a link, a trackback (http://www.ofhills.com/cgi-bin/mtcgi/mt-tb.cgi/84 ) or some other acknowledgement if you use it. Please feel free to email me with questions or suggestions.