--- /dev/null
+# Blosxom Plug-in: feedback
+# Author: Frank Hecker (http://www.hecker.org/)
+#
+# Version 0.23
+
+package feedback;
+
+use warnings;
+
+
+# --- Configurable variables ---
+
+# --- You *must* set the following variables properly for your blog ---
+
+# Where should I keep the feedback hierarchy?
+# (By default it goes in the Blosxom state directory. However you may
+# prefer it to go in the same directory as the Blosxom data directory.
+# If so, delete the following line and uncomment the line following it.)
+$fb_dir = "$blosxom::plugin_state_dir/feedback";
+# $fb_dir = "$blosxom::datadir/../feedback";
+
+
+# --- Set the following variables according to your preferences ---
+
+# Are comments and TrackBacks allowed? Set to zero to disable either or both.
+my $allow_comments = 1;
+my $allow_trackbacks = 1;
+
+# Don't allow comments/TrackBacks if story is older than this (in seconds).
+# (Set to zero to keep story open for comments/TrackBacks forever.)
+my $comment_period = 90 * 86400; # 90 days
+my $trackback_period = 90 * 86400; # 90 days
+
+# Do Akismet checking of comments and/or TrackBacks for spam.
+my $akismet_comments = 0;
+my $akismet_trackbacks = 0;
+
+# WordPress API key for use with Akismet.
+# (Register at <http://wordpress.com/> to get your own API key.)
+my $wordpress_api_key = '';
+
+# Do MT-blacklist checking of comments and/or TrackBacks for spam.
+# NOTE: The MT-Blacklist file is no longer maintained; we suggest using
+# Akismet instead.
+my $blacklist_comments = 0;
+my $blacklist_trackbacks = 0;
+
+# Where can I find the local copy of the MT-Blacklist file?
+my $blacklist_file = "$blosxom::plugin_state_dir/blacklist.txt";
+
+# Send an email message to notify the blog owner of new comments and/or
+# TrackBacks and (optionally) request approval of new comments/TrackBacks.
+my $notify_comments = 0;
+my $notify_trackbacks = 0;
+my $moderate_comments = 1;
+my $moderate_trackbacks = 1;
+
+# Email address and SMTP server used for notifications and moderation requests.
+my $address = 'jdoe@example.com';
+my $smtp_server = 'smtp.example.com';
+
+# Default values for fields not submitted with the comment or TrackBack ping.
+my $default_name = "Someone";
+my $default_blog_name = "An unnamed blog";
+my $default_title = "an article";
+
+# The formatting used for comments, i.e., how they are translated to (X)HTML.
+# Valid choices at present are 'none', 'plaintext' and 'markdown'.
+my $comment_format = 'plaintext';
+
+# Should we accept and display commenter's email addresses? (The default is
+# to support http/https URLs only; this may be the only option in future.)
+my $allow_mailto = 0;
+
+
+# --- You should not normally need to change the following variables ---
+
+# What flavour should I consider an incoming TrackBack ping?
+$trackback_flavour = "trackback";
+
+# What file extension should I use for saved comments and TrackBacks?
+my $fb_extension = "wb";
+
+# What fields are used in the comments form?
+my @comment_fields = qw! name url comment !;
+
+# What fields are used by TrackBacks?
+my @trackback_fields = qw! blog_name url title excerpt !;
+
+# Limit all fields to this length or less (just in case).
+my $max_param_length = 10000;
+
+
+# --- Variables for use in flavour templates (e.g., as $feedback::foo) ---
+
+# Comment and TrackBack fields, for use in the comment, preview, and
+# trackback templates.
+$name = '';
+$name_link = ''; # Combines name and link for email/URL
+$date = '';
+$comment = '';
+$blog_name = '';
+$title = '';
+$title_link = ''; # Combines title and link to article
+$excerpt = '';
+$url = ''; # Also used in $name_link, $title_link
+
+# Field values for previewed comments, used in the commentform template.
+$name_preview = '';
+$comment_preview = '';
+$url_preview = '';
+
+# Message displayed in response to a comment submission (e.g., to display
+# an error message), for use in the story or foot templates. The response is
+# formatted for use in HTML/XHTML content.
+$comment_response = '';
+
+# XML message displayed in response to a TrackBack ping (e.g., to display
+# an error message or indicate success), per the TrackBack Technical
+# Specification <http://www.sixapart.com/pronet/docs/trackback_spec>.
+$trackback_response = '';
+
+# All comments and TrackBacks for a particular story, for use in the story
+# template for an individual story page. Also includes content from the
+# comments_head/comments_foot and trackbacks_head/trackbacks_foot templates.
+$comments = '';
+$trackbacks = '';
+
+# Counts of comments and TrackBacks for a story, for use in the story
+# template (e.g., for index and archive pages).
+$comments_count = 0;
+$trackbacks_count = 0;
+$count = 0; # total of both
+
+# Previewed comment for a particular story, for use in the story
+# template for an individual story page.
+$preview = '';
+
+# Default comment submission form, for use in the foot template (for an
+# individual story page). The plug-in sets this value to null if comments
+# are disabled or in cases where the page is not for an individual story
+# or the story is older than the allowed comment period.
+$commentform = '';
+
+# TrackBack discovery information, for use in the foot template (for
+# an individual story page). The code sets this value to null if TrackBacks
+# are disabled or in cases where the page is not for an individual story
+# or the story is older than the allowed TrackBack period.
+$trackbackinfo = '';
+
+
+# --- External modules required ---
+
+use CGI qw/:standard/;
+use FileHandle;
+use URI;
+use URI::Escape;
+
+
+# --- Global variables (used in interpolation) ---
+
+use vars qw! $fb_dir $trackback_flavour $name $name_link $date $comment
+ $blog_name $title $name_preview $comment_preview $url_preview
+ $comment_response $trackback_response $comments $trackbacks
+ $comments_count $trackbacks_count $count $preview $commentform
+ $trackbackinfo !;
+
+
+# --- Private static variables ---
+
+# Spam blacklist array.
+my @blacklist_entries = ();
+
+# File handle for use in reading/writing the feedback file, etc.
+my $fh = new FileHandle;
+
+# Path and filename for the main feedback file for a story, and item name
+# used in contructing filenames for files containing moderated items.
+my $fb_path = '';
+my $fb_fn = '';
+
+# Whether comments or TrackBacks are closed for a given story.
+my $closed_comments = 0;
+my $closed_trackbacks = 0;
+
+
+# --- Plug-in initialization ---
+
+# Strip potentially confounding final slash from feedback directory path.
+$fb_dir =~ s!/$!!;
+
+# Strip potentially confounding initial period from file extension.
+$fb_extension =~ s!^\.!!;
+
+# Initialize the default templates; use $blosxom::template so we can leverage
+# the Blosxom template subroutine (whether default or replaced by a plug-in).
+my %template = ();
+while (<DATA>) {
+ last if /^(__END__)?$/;
+ # TODO: Fix this to correctly handle empty flavours (i.e., no $txt).
+ my ($ct, $comp, $txt) = /^(\S+)\s(\S+)(?:\s(.*))?$/;
+# my ($ct, $comp, $txt) = /^(\S+)\s(\S+)\s(.*)$/;
+ $txt = '' unless defined($txt);
+ $txt =~ s/\\n/\n/mg;
+ $blosxom::template{$ct}{$comp} = $txt;
+}
+
+# Moderation implies notification.
+$notify_comments = 1 if $moderate_comments;
+$notify_trackbacks = 1 if $moderate_trackbacks;
+
+
+# --- Plug-in subroutines ---
+
+# Create feedback directory if needed.
+sub start {
+ # The $fb_dir variable must be set to activate feedback.
+ unless ($fb_dir) {
+ warn "feedback: " .
+ "The \$fb_dir configurable variable is not set; "
+ . "please set it to enable comments or TrackBacks.\n";
+ return 0;
+ }
+
+ # The value of $fb_dir must be a writeable directory.
+ if (-e $fb_dir && !(-d $fb_dir && -w $fb_dir)) {
+ warn "feedback: The feedback directory '$fb_dir' "
+ . "must be a writeable directory; please rename or remove it "
+ . "and Blosxom will create it properly for you.\n";
+ return 0;
+ }
+
+ # The $fb_dir does not yet exist, so Blosxom will create it.
+ unless (-e $fb_dir) {
+ return 0 unless (mk_feedback_dir($fb_dir));
+ }
+
+ return 1;
+}
+
+
+# Decide whether to close comments and TrackBacks for a story.
+sub date {
+ my ($pkg, $file, $date_ref, $mtime, $dw, $mo, $mo_num, $da, $ti, $yr) = @_;
+
+ # A positive value of $comment_period represents the time in seconds
+ # during which posting comments or TrackBacks is allowed after a
+ # story has been published. (Note that updating a story has the effect
+ # of reopening the feedback period.) A zero or negative value for
+ # $comment_period means that posting feedback is always allowed.
+
+ if ($comment_period <= 0) {
+ $closed_comments = 0;
+ } elsif ($allow_comments && (time - $mtime) > $comment_period) {
+ $closed_comments = 1;
+ } else {
+ $closed_comments = 0;
+ }
+
+ # $trackback_period works the same way as $comment_period.
+
+ if ($trackback_period <= 0) {
+ $closed_trackbacks = 0;
+ } elsif ($allow_trackbacks && (time - $mtime) > $trackback_period) {
+ $closed_trackbacks = 1;
+ } else {
+ $closed_trackbacks = 0;
+ }
+
+ return 1;
+}
+
+
+# Parse posted TrackBacks and comments and take action as appropriate.
+# Retrieve comments and TrackBacks and format according to the templates.
+# Display a comment form and/or TrackBack URL as appropriate.
+
+sub story {
+ my ($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
+ my $submission_type;
+ my $status_msg;
+ my $is_story_page;
+
+ # We have five possible tasks in this subroutine:
+ #
+ # * handle submitted TrackBack pings or comments (or related requests)
+ # * display previously-submitted TrackBacks or comments
+ # * display a comment being previewed
+ # * display a form for entering a comment (or editing a previewed one)
+ # * display information about submitting TrackBacks
+ #
+ # Exactly what we do depends whether we are rendering dynamically or
+ # statically and on the type of request (GET, HEAD, or POST) (when
+ # dynamically rendering), the Blosxom flavour, the parameters associated
+ # with the request, the age of the story, and the way the feedback
+ # plug-in itself is configured.
+
+ # Make $path empty if at top level, preceded by a single slash otherwise.
+ !defined($path) and $path = "";
+ $path =~ s!^/*!!; $path &&= "/$path";
+
+ # Set feedback path and filename for this story.
+ $fb_path = $path;
+ $fb_fn = $filename . '.' . $fb_extension;
+
+ # Determine whether this is an individual story page or not.
+ $is_story_page =
+ $blosxom::path_info =~ m!^(.*/)?(.+)\.(.+)$! ? 1 : 0;
+
+ # For dynamic rendering of an individual story page *only*, check to
+ # see if this is a feedback-related request, take action, and formulate
+ # a response.
+ #
+ # We have five possible cases: TrackBack ping, comment preview, comment
+ # post, moderator approval, and moderator rejection. These are
+ # distinguished based on the type of request (POST vs. GET/HEAD),
+ # the flavour (for TrackBack pings only), and the request parameters.
+
+ $submission_type = $comment_response = $trackback_response = '';
+ if ($blosxom::static_or_dynamic eq 'dynamic' && $is_story_page) {
+ ($submission_type, $status_msg) = process_submission();
+ if ($submission_type eq 'trackback') {
+ $trackback_response = format_tb_response($status_msg);
+ return 1; # All done.
+ } elsif ($submission_type eq 'comment'
+ || $submission_type eq 'preview'
+ || $submission_type eq 'approve'
+ || $submission_type eq 'reject') {
+ $comment_response = format_cmt_response($status_msg);
+ }
+ }
+
+ # Display previously-submitted comments and TrackBacks for this story.
+ # For index and and archive pages we just display counts of the comments
+ # and TrackBacks.
+
+ $comments = $trackbacks = '';
+ $comments_count = $trackbacks_count = 0;
+ if ($is_story_page) {
+ ($comments, $comments_count, $trackbacks, $trackbacks_count) =
+ get_feedback($path);
+ } else {
+ ($comments_count, $trackbacks_count) = count_feedback();
+ }
+ $count = $comments_count + $trackbacks_count;
+
+ # If we are previewing a comment then format the comment for display.
+ $preview = '';
+ if ($submission_type eq 'preview') {
+ $preview = get_preview($path);
+ }
+
+ # Display a form for comment submission, if we are on an individual
+ # story page and comments are (still) allowed. (If we are previewing
+ # a comment then the form will be pre-filled as appropriate.)
+
+ $commentform = '';
+ if ($is_story_page && $allow_comments) {
+ if ($closed_comments) {
+ $commentform =
+ "<p class=\"commentform\">"
+ . "Comments are closed for this story.</p>";
+ } else {
+ # Get the commentform template and interpolate variables in it.
+ $commentform =
+ &$blosxom::template($path,'commentform',$blosxom::flavour)
+ || &$blosxom::template($path,'commentform','general');
+ $commentform = &$blosxom::interpolate($commentform);
+ }
+ }
+
+ # Display information on submitting TrackPack pings (including code for
+ # TrackBack autodiscovery), if we are on an individual story page and
+ # TrackBacks are (still) allowed.
+
+ $trackbackinfo = '';
+ if ($is_story_page && $allow_trackbacks) {
+ if ($closed_trackbacks) {
+ $trackbackinfo =
+ "<p class=\"trackbackinfo\">"
+ . "Trackbacks are closed for this story.</p>";
+ } else {
+ # Get the trackbackinfo template and interpolate variables in it.
+ $trackbackinfo =
+ &$blosxom::template($path,'trackbackinfo',$blosxom::flavour)
+ || &$blosxom::template($path,'trackbackinfo','general');
+ $trackbackinfo = &$blosxom::interpolate($trackbackinfo);
+ }
+ }
+
+ # For interpolate_fancy to work properly when deciding whether to include
+ # certain content or not, the associated variables must be undefined if
+ # there is no actual content to be displayed.
+
+ $comment_response =~ m!^\s*$! and $comment_response = undef;
+ $comments =~ m!^\s*$! and $comments = undef;
+ $trackbacks =~ m!^\s*$! and $trackbacks = undef;
+ $preview =~ m!^\s*$! and $preview = undef;
+ $commentform =~ m!^\s*$! and $commentform = undef;
+ $trackbackinfo =~ m!^\s*$! and $trackbackinfo = undef;
+
+ return 1;
+}
+
+
+# --- Helper subroutines ---
+
+# Process a submitted HTTP request and take whatever action is appropriate.
+# Returns the type of submission: 'trackback', 'comment', 'preview',
+# 'approve', 'reject', or null for a request not related to feedback.
+# Also sets $comment_response and $trackback_response;
+
+sub process_submission {
+ my $submission_type = '';
+ my $status_msg = '';
+
+ if (request_method() eq 'POST') {
+ # We have two possible cases: a TrackBack ping (identified by
+ # the flavour extension) or a submitted comment.
+
+ if ($blosxom::flavour eq $trackback_flavour) {
+ $status_msg = handle_feedback('trackback');
+ $submission_type = 'trackback';
+ } else {
+ # Comment posts may or may not use a particular flavour
+ # extension, so we check for the value of the 'plugin'
+ # hidden field (from the comment form).
+
+ my $plugin_param = sanitize_param(param('plugin'));
+ if ($plugin_param eq 'writeback') {
+ # Comment previews are distinguished from comment posts
+ # by the value of the 'submit' parameter associated with
+ # the 'Post' and 'Preview' form buttons.
+
+ my $submit_param = sanitize_param(param('submit'));
+ $status_msg = '';
+ if ($submit_param eq 'Preview') {
+ $status_msg = handle_feedback('preview');
+ $submission_type = 'preview';
+ } elsif ($submit_param eq 'Post') {
+ $status_msg = handle_feedback('comment');
+ $submission_type = 'comment';
+ } else {
+ $status_msg = "The submit parameter must have the value "
+ . "'Preview' or 'Post'";
+ }
+ }
+ }
+ } elsif (request_method() eq 'GET' || request_method() eq 'HEAD') {
+ my $moderate_param = sanitize_param(param('moderate'));
+ my $feedback_param = sanitize_param(param('feedback'));
+
+ if ($moderate_param) {
+ # We have two possible cases: moderator approval or rejection,
+ # distinguished based on the value of the 'moderate' parameter.
+
+ if (!$feedback_param) {
+ $status_msg =
+ "You must provide a 'feedback' parameter and item.";
+ } elsif ($moderate_param eq 'approve') {
+ $status_msg = approve_feedback($feedback_param);
+ $submission_type = 'approve';
+ } elsif ($moderate_param eq 'reject') {
+ $status_msg = reject_feedback($feedback_param);
+ $submission_type = 'reject';
+ } else {
+ $status_msg =
+ "'moderate' parameter must "
+ . "have the value 'approve' or 'reject'.";
+ }
+ }
+ }
+
+ return $submission_type, $status_msg;
+}
+
+
+# Retrieve comments and TrackBacks for a story and format them according
+# to the appropriate templates for the story (based on the story's path).
+# For comments we use the comment template for each individual comment,
+# along with the optional comments_head and comments_foot templates (before
+# and after the comments proper). For TrackBacks we use the corresponding
+# trackback template for each TrackBack, together with the optional
+# trackbacks_head and trackbacks_foot templates.
+
+sub get_feedback {
+ my $path = shift;
+ my ($comments, $comments_count, $trackbacks, $trackbacks_count);
+
+ $comments = $trackbacks = '';
+ $comments_count = $trackbacks_count = 0;
+
+ # Retrieve the templates for individual comments and TrackBacks.
+ my $comment_template =
+ &$blosxom::template($path, 'comment', $blosxom::flavour)
+ || &$blosxom::template($path, 'comment', 'general');
+
+ my $trackback_template =
+ &$blosxom::template($path, 'trackback', $blosxom::flavour)
+ || &$blosxom::template($path, 'trackback', 'general');
+
+ # Open the feedback file (if it exists) and read any comments or
+ # TrackBacks. Note that we can distinguish comments from TrackBacks
+ # because comments have a 'comment' field and TrackBacks don't.
+
+ my %param = ();
+ if ($fh->open("$fb_dir$fb_path/$fb_fn")) {
+ foreach my $line (<$fh>) {
+ $line =~ /^(.+?): (.*)$/ and $param{$1} = $2;
+ if ( $line =~ /^-----$/ ) {
+ if ($param{'comment'}) {
+ $comment = format_comment($param{'comment'});
+ $date = format_date($param{'date'});
+ ($name, $name_link) =
+ format_name($param{'name'}, $param{'url'});
+
+ my $cmt = $comment_template;
+ $cmt = &$blosxom::interpolate($cmt);
+
+ $comments .= $cmt;
+ $comments_count++;
+ } else {
+
+ $blog_name = format_blog_name($param{'blog_name'});
+ $excerpt = format_excerpt($param{'excerpt'});
+ $date = format_date($param{'date'});
+ ($title, $title_link) =
+ format_title($param{'title'}, $param{'url'});
+
+ my $trackback = $trackback_template;
+ $trackback = &$blosxom::interpolate($trackback);
+
+ $trackbacks .= $trackback;
+ $trackbacks_count++;
+ }
+ %param = ();
+ }
+ }
+ }
+
+ return ($comments, $comments_count, $trackbacks, $trackbacks_count);
+}
+
+
+# Retrieve comments and TrackBacks for a story and (just) count them.
+
+sub count_feedback {
+ my $comments_count = 0;
+ my $trackbacks_count = 0;
+
+ # Open the feedback file (if it exists) and count any comments or
+ # TrackBacks. Note that we can distinguish comments from TrackBacks
+ # because comments have a 'comment' field and TrackBacks don't.
+
+ my %param = ();
+ if ($fh->open("$fb_dir$fb_path/$fb_fn")) {
+ foreach my $line (<$fh>) {
+ $line =~ /^(.+?): (.*)$/ and $param{$1} = $2;
+ if ( $line =~ /^-----$/ ) {
+ if ($param{'comment'}) {
+ $comments_count++;
+ } else {
+ $trackbacks_count++;
+ }
+ %param = ();
+ }
+ }
+ }
+
+ return ($comments_count, $trackbacks_count);
+}
+
+
+# Format a previewed comment according to the appropriate preview template
+# for the story (based on the story's path).
+
+sub get_preview {
+ my $path = shift;
+ my $preview = '';
+
+ # Retrieve the comment template (also used for previewed comments).
+ my $comment_template =
+ &$blosxom::template($path, 'comment', $blosxom::flavour)
+ || &$blosxom::template($path, 'comment', 'general');
+
+ # Format the previewed comment using the submitted values.
+ $comment = format_comment($comment_preview);
+ $date = format_date($date_preview);
+ ($name, $name_link) =
+ format_name($name_preview, $url_preview);
+
+ $preview = &$blosxom::interpolate($comment_template);
+
+ return $preview;
+}
+
+
+# Create top-level directory to hold feedback files, and make it writeable.
+sub mk_feedback_dir {
+ my $mkdir_r = mkdir("$fb_dir", 0755);
+ warn $mkdir_r
+ ? "feedback: $fb_dir created.\n"
+ : "feedback: Could not create $fb_dir.\n";
+ $mkdir_r or return 0;
+
+ my $chmod_r = chmod 0755, $fb_dir;
+ warn $chmod_r
+ ? "feedback: $fb_dir set to 0755 permissions.\n"
+ : "feedback: Could not set permissions on $fb_dir.\n";
+ $chmod_r or return 0;
+
+ warn "feedback: feedback is enabled!\n";
+ return 1;
+}
+
+
+# Create subdirectories of feedback directory as necessary.
+sub mk_feedback_subdir {
+ my $dir = shift;
+ my $p = '';
+
+ return 1 if !defined($dir) or $dir eq '';
+
+ foreach (('', split /\//, $dir)) {
+ $p .= "/$_";
+ $p =~ s!^/!!;
+ return 0
+ unless (-d "$fb_dir/$p" or mkdir "$fb_dir/$p", 0755);
+ }
+
+ return 1;
+}
+
+
+# Process a submitted comment or TrackBack.
+sub handle_feedback {
+ my $feedback_type = shift;
+ my $status_msg = '';
+ my $is_comment;
+ my $is_preview;
+ my $fb_item;
+
+ # Set up to handle either a comment, preview, or TrackBack as requested.
+ if ($feedback_type eq 'comment') {
+ $is_comment = 1;
+ $is_preview = 0;
+ } elsif ($feedback_type eq 'preview') {
+ $is_comment = 1;
+ $is_preview = 1;
+ } else {
+ $is_comment = 0;
+ $is_preview = 0;
+ }
+
+ my $allow = $is_comment ? $allow_comments : $allow_trackbacks;
+ my $closed = $is_comment ? $closed_comments : $closed_trackbacks;
+ my $period = $is_comment ? $comment_period : $trackback_period;
+ my $akismet = $is_comment ? $akismet_comments : $akismet_trackbacks;
+ my $blacklist = $is_comment ? $blacklist_comments : $blacklist_trackbacks;
+ my $notify = $is_comment ? $notify_comments : $notify_trackbacks;
+ my $moderate = $is_comment ? $moderate_comments : $moderate_trackbacks;
+ my @fields = $is_comment ? @comment_fields : @trackback_fields;
+
+ # Reject request if feedback is not (still) allowed.
+ unless ($allow && !$closed) {
+ if ($closed) {
+ $status_msg =
+ "This story is older than " . ($period/86400) . " days. "
+ . ($is_comment ? "Comments" : "TrackBacks")
+ . " have now been closed.";
+ } else {
+ $status_msg =
+ ($is_comment ? "Comments" : "TrackBacks")
+ . " are not enabled for this site.";
+ }
+ return $status_msg;
+ }
+
+ # Filter out the "good" fields from the CGI parameters.
+ my %params = copy_params(\@fields);
+
+ # Comments must have (at least) a comment parameter, and TrackBacks a URL.
+ if ($is_comment) {
+ unless ($params{'comment'}) {
+ $status_msg =
+ "You didn't enter anything in the comment field.";
+ return $status_msg;
+ }
+ } elsif (!$params{'url'}) {
+ $status_msg = "No URL specified for the TrackBack";
+ return 0;
+ }
+
+ # Check feedback to see if it's spam.
+ if (is_spam(\%params, $is_comment, $akismet, $blacklist)) {
+ # If we are previewing a comment then we allow the poster a
+ # chance to revise the comment; otherwise we just reject it.
+
+ if ($is_preview) {
+ $status_msg =
+ "Your comment appears to be spam and will be rejected "
+ . "unless it is revised. ";
+ } else {
+ $status_msg =
+ "Your feedback was rejected because it appears to be spam; "
+ . "please contact the site administrator if you believe that "
+ . "your feedback was rejected in error.";
+ return $status_msg;
+ }
+ }
+
+ # If we are previewing a comment then just save the fields for later
+ # use in the previewed comment and (as prefilled values) in the comment
+ # form. Otherwise attempt to save the new feedback information, either
+ # into the permanent feedback file for this story (if no moderation) or
+ # into a temporary file (for later moderation).
+
+ if ($is_preview) {
+ $status_msg .= save_preview(\%params);
+ } else {
+ ($fb_item, $status_msg) = save_feedback(\%params, $moderate);
+ return $status_msg unless $fb_item;
+
+ # Send a moderation message or notify blog owner of the new feedback.
+ if ($moderate || $notify) {
+ send_notification(\%params, $moderate, $fb_item);
+ }
+ }
+
+ return $status_msg;
+}
+
+
+# Make a "safe" copy of the CGI parameters based on the expected
+# field names associated with either a comment or TrackBack.
+sub copy_params {
+ my $fields_ref = shift;
+ my %params;
+
+ foreach my $key (@$fields_ref) {
+ my $value = substr(param($key), 0, $max_param_length) || "";
+
+ # Eliminate leading and trailing whitespace, use carriage returns
+ # as line delimiters, and collapse multiple blank lines into one.
+
+ $value =~ s/^\s+//;
+ $value =~ s/\s+$//;
+ $value =~ s/\r?\n\r?/\r/mg;
+ $value =~ s/\r\r\r*/\r\r/mg;
+
+ $params{$key} = $value;
+ }
+
+ return %params;
+}
+
+
+# Send notification or moderation email to blog owner.
+sub send_notification {
+ my ($params_ref, $moderate, $fb_item) = @_;
+
+ unless ($address && $smtp_server) {
+ warn "feedback: No address or SMTP server for notifications\n";
+ return 0;
+ }
+
+ my $message = "New feedback for your post \"$blosxom::title\" ("
+ . $blosxom::path_info . "):\n\n";
+
+ if ($$params_ref{'comment'}) {
+ $message .= "Name : " . $$params_ref{'name'} . "\n";
+ $message .= "Email/URL: " . $$params_ref{'url'} . "\n";
+ $message .= "Comment :\n";
+ my $comment = $$params_ref{'comment'};
+ $comment =~ s!\r!\n!g;
+ $message .= $comment . "\n";
+ } else {
+ $message .= "Blog name: " . $$params_ref{'blog_name'} . "\n";
+ $message .= "Article : " . $$params_ref{'title'} . "\n";
+ $message .= "URL : " . $$params_ref{'url'} . "\n";
+ $message .= "Excerpt :\n";
+ my $excerpt = $$params_ref{'excerpt'};
+ $excerpt =~ s!\r!\n!g;
+ $message .= $excerpt . "\n";
+ }
+
+ if ($moderate) {
+ # For TrackBacks use the default flavour for the approve/reject URI.
+ my $moderate_flavour = $blosxom::flavour;
+ $moderate_flavour eq $trackback_flavour
+ and $moderate_flavour = $blosxom::default_flavour;
+
+ $message .= "\n\nTo approve this feedback, please click on the URL\n"
+ . "$blosxom::url$blosxom::path/$blosxom::fn.$moderate_flavour"
+ . "?moderate=approve;feedback=" . uri_escape($fb_item) . "\n";
+
+ $message .= "\nTo reject this feedback, please click on the URL\n"
+ . "$blosxom::url$blosxom::path/$blosxom::fn.$moderate_flavour"
+ . "?moderate=reject;feedback=" . uri_escape($fb_item) . "\n";
+ }
+
+ # Load Net::SMTP module only now that it's needed.
+ require Net::SMTP; Net::SMTP->import;
+
+ my $smtp = Net::SMTP->new($smtp_server);
+ $smtp->mail($address);
+ $smtp->to($address);
+ $smtp->data();
+ $smtp->datasend("To: $address\n");
+ $smtp->datasend("From: $address\n");
+ $smtp->datasend("Subject: [$blosxom::blog_title] Feedback: "
+ . "\"$blosxom::title\"\n");
+ $smtp->datasend("\n\n");
+ $smtp->datasend($message);
+ $smtp->dataend();
+ $smtp->quit;
+
+ return 1;
+}
+
+
+# Format the date used in comments and TrackBacks. If the argument is a
+# number then it is considered to be a date/time in seconds since the
+# (Perl) epoch; otherwise we assume that the date is already formatted.
+# (This may allow the feedback plug-in to use legacy writeback files.)
+
+sub format_date {
+ my $date_value = shift;
+
+ if ($date_value =~ m!^\d+$!) {
+ my ($sec, $min, $hour, $mday, $mon, $year, $wday, $yday, $isdst) =
+ localtime($date_value);
+ $year += 1900;
+
+ # Modify the following to match your preference.
+ return sprintf("%4d-%02d-%02d %02d:%02d",
+ $year, $mon+1, $mday, $hour, $min);
+ } else {
+ return $date_value;
+ }
+}
+
+
+# Format the name used in comments.
+sub format_name {
+ my ($name, $url) = @_;
+
+ # If the user didn't supply a name, try to use something sensible.
+ unless ($name) {
+ if ($url =~ m/^mailto:/) {
+ $name = substr($url, 7);
+ } else {
+ $name = $default_name;
+ }
+ }
+
+ # Link to a URL if one was provided.
+ my $name_link =
+ $url ? "<a href=\"$url\" rel=\"nofollow\">$name</a>" : $name ;
+
+ return $name, $name_link;
+}
+
+
+# Format the comment response message.
+sub format_cmt_response {
+ my $response = shift;
+
+ # Clean up the response.
+ $response =~ s/^\s+//;
+ $response =~ s/\s+$//;
+
+ # Convert the response into a special type of paragraph.
+ # NOTE: A value 'OK' for $response indicates a successful comment.
+ if ($response eq 'OK') {
+ $response = '<p class="comment-response">Thanks for the comment!</p>';
+ } else {
+ $response = '<p class="comment-response">' . $response . '</p>';
+ }
+
+ return $response;
+}
+
+
+# Format the TrackBack response message.
+sub format_tb_response {
+ my $response = shift;
+
+ # Clean up the response.
+ $response =~ s/^\s+//;
+ $response =~ s/\s+$//;
+
+ # Convert the response into an XML message per the TrackBack Technical
+ # Specification <http://www.sixapart.com/pronet/docs/trackback_spec>.
+ # NOTE: A value 'OK' for $response indicates a successful TrackBack;
+ # note that this value is *not* used as part of the TrackBack response.
+
+ if ($response eq 'OK') {
+ $response = "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>"
+ . "<response><error>0</error></response>";
+ } else {
+ $response = "<?xml version=\"1.0\" encoding=\"iso-8859-1\"?>"
+ . "<response><error>1</error>"
+ . "<message>$response</message></response>";
+ }
+
+ return $response;
+}
+
+
+# Format the comment itself.
+sub format_comment {
+ my $comment = shift;
+
+ # TODO: Support other comment formats such as Textile.
+
+ if ($comment_format eq 'none') {
+ # A no-op, assumes formatting will be added in the template.
+ } elsif ($comment_format eq 'plaintext') {
+ # Simply convert the comment into a series of paragraphs.
+ $comment = '<p>' . $comment . '</p>';
+ $comment =~ s!\r\r!</p><p>!mg;
+ } elsif ($comment_format eq 'markdown'
+ && $blosxom::plugins{'Markdown'} > 0) {
+ $comment = &Markdown::Markdown($comment);
+ }
+
+ return $comment;
+}
+
+
+# Format the blog name used in TrackBacks.
+sub format_blog_name {
+ my $blog_name = shift;
+
+ $blog_name or $blog_name = $default_blog_name;
+
+ return $blog_name;
+}
+
+
+# Format the title used in TrackBacks.
+sub format_title {
+ my ($title, $url) = @_;
+ my $title_link;
+
+ # Link to article, quoting the title if one was supplied.
+ if ($title) {
+ $title_link = "\"<a href=\"$url\" rel=\"nofollow\">$title</a>\"";
+ } else {
+ $title = $default_title;
+ $title_link = "<a href=\"$url\" rel=\"nofollow\">$title</a>";
+ }
+
+ return $title, $title_link;
+}
+
+
+# Format the TrackBack excerpt.
+sub format_excerpt {
+ my $excerpt = shift;
+
+ # TODO: Truncate excerpts at some reasonable length.
+
+ # Simply convert the excerpt into a series of paragraphs.
+ if ($excerpt) {
+ $excerpt = '<p>' . $excerpt . '</p>';
+ $excerpt =~ s!\r\r!</p><p>!mg;
+ }
+
+ return $excerpt;
+}
+
+
+# Read in the MT-Blacklist file.
+sub read_blacklist {
+
+ # No need to do anything if we've already read in the blacklist file.
+ return 1 if @blacklist_entries;
+
+ # Try to find the blacklist file and open it.
+ open BLACKLIST, "$blacklist_file"
+ or die "Can't read '$blacklist_file', $!\n";
+
+ my @lines = grep {! /^\s*\#/ } <BLACKLIST>;
+ close BLACKLIST;
+ die "No blacklists?\n" unless @lines;
+
+ foreach my $line (@lines) {
+ $line =~ s/^\s*//;
+ $line =~ s/\s*[^\\]\#.*//;
+ next unless $line;
+ push @blacklist_entries, $line;
+ }
+ die "No entries in blacklist file?\n" unless @blacklist_entries;
+
+ return 1;
+}
+
+
+# Do spam tests on comment or TrackBack; returns 1 if spam, 0 if OK.
+sub is_spam {
+ my ($params_ref, $is_comment, $akismet, $blacklist) = @_;
+
+ # Perform a series of spam tests. If any show positive then reject.
+
+ # Does the host part of the URL reference an IP address?
+ return 1 if uses_ipaddr($$params_ref{'url'});
+
+ # Does the comment or TrackBack match against the Akismet service?
+ return 1 if $akismet && matches_akismet($params_ref, $is_comment);
+
+ # Does the comment or TrackBack match against the MT-Blacklist file
+ # (deprecated)?
+ return 1
+ if $blacklist && matches_blacklist((join "\n", values %$params_ref));
+
+ # TODO: Add other useful spam checks.
+
+ # Got by all the tests, so assume it's not spam.
+ return 0;
+}
+
+
+# Check host part of URL to see if it is an IP address.
+sub uses_ipaddr {
+ my $uri = shift;
+
+ return 0 unless $uri;
+
+ # Construct URI object.
+ my $u = URI->new($uri);
+
+ # Return if this not actually a URI (i.e., it's an email address).
+ return 0 unless defined($u->scheme);
+
+ # Check for an IPv4 or IPv6 address on http/https URLs.
+ if ($u->scheme eq 'http' || $u->scheme eq 'https') {
+ if ($u->authority =~ m!^\[?\d!) {
+ return 1;
+ }
+ }
+
+ return 0;
+}
+
+
+# Check comment or TrackBack against the Akismet online service.
+sub matches_akismet {
+ my ($params_ref, $is_comment) = @_;
+
+ # Load Net:Akismet module only now that it's needed.
+ require Net::Akismet; Net::Akismet->import;
+
+ # Attempt to connect to the Askimet service.
+ my $akismet = Net::Akismet->new(KEY => $wordpress_api_key,
+ URL => $blosxom::url);
+ unless ($akismet) {
+ warn "feedback: Akismet key verification failed\n";
+ return 0;
+ }
+
+ # Set up fields to be verified. Note that we do not use the REFERRER,
+ # PERMALINK, or COMMENT_AUTHOR_EMAIL fields supported by Akismet.
+
+ my %fields = (USER_IP => $ENV{'REMOTE_ADDR'});
+ if ($is_comment) {
+ $fields{COMMENT_TYPE} = 'comment';
+ $fields{COMMENT_CONTENT} = $$params_ref{'comment'};
+ $fields{COMMENT_AUTHOR} = $$params_ref{'name'};
+ $fields{COMMENT_AUTHOR_URL} = $$params_ref{'url'};
+ } else {
+ $fields{COMMENT_TYPE} = 'trackback';
+ $fields{COMMENT_CONTENT} =
+ $$params_ref{'title'} . "\n" . $$params_ref{'excerpt'};
+ $fields{COMMENT_AUTHOR} = $$params_ref{'blog_name'};
+ $fields{COMMENT_AUTHOR_URL} = $$params_ref{'url'};
+ }
+
+ # Is it spam?
+ return 1 if $akismet->check(%fields) eq 'true';
+
+ # Apparently not.
+ return 0;
+}
+
+
+# Check comment or TrackBack against the MT-Blacklist file (deprecated).
+sub matches_blacklist {
+ my $params_string = shift;
+
+ # Read in the blacklist file.
+ read_blacklist();
+
+ # Check each blacklist entry against the comment or TrackBack.
+ foreach my $spam (@blacklist_entries) {
+ chomp($spam);
+ return 1 if $params_string =~ /$spam/;
+ }
+
+ return 0;
+}
+
+
+# Save comment or TrackBack to disk. If moderating, returns the (randomly-
+# generated) id of the item saved for later approval or rejection (plus
+# a status message). If not moderating returns the name of the feedback
+# file in which the item was saved instead of the id. Returns null on errors.
+
+sub save_feedback {
+ my ($params_ref, $moderate) = @_;
+ my $fb_item = '';
+ my $feedback_fn = '';
+ my $status_msg = '';
+
+ # Clear values used to prefill commentform.
+ $name_preview = $url_preview = $comment_preview = '';
+
+ # Create a new directory if needed to contain the feedback file.
+ unless (mk_feedback_subdir($fb_path)) {
+ $status_msg = 'Could not save comment or TrackBack.';
+ return '', $status_msg;
+ }
+
+ # Save into the main feedback file or a temporary file, depending on
+ # whether feedback is being moderated or not.
+ if ($moderate) {
+ $fb_item = rand_alphanum(8);
+ $feedback_fn = $fb_item . '-' . $fb_fn;
+ } else {
+ $feedback_fn = $fb_fn;
+ }
+
+ # Attempt to open the file and append to it.
+ unless ($fh->open(">> $fb_dir$fb_path/$feedback_fn")) {
+ warn "couldn't >> $fb_dir$fb_path/$feedback_fn\n";
+ $status_msg = 'Could not save comment or TrackBack.';
+ return '', $status_msg;
+ }
+
+ # Write each parameter out as a line in the file.
+ foreach my $key (sort keys %$params_ref) {
+ my $value = $$params_ref{$key};
+
+ # Eliminate leading and trailing whitespace, use carriage returns
+ # as line delimiters, and collapse multiple blank lines into one.
+
+ $value =~ s/^\s+//;
+ $value =~ s/\s+$//;
+ $value =~ s/\r?\n\r?/\r/mg;
+ $value =~ s/\r\r\r*/\r\r/mg;
+
+ # Ensure URL and other fields are sanitized.
+ if ($key eq 'url') {
+ $value = sanitize_uri($value);
+ } else {
+ $value = escapeHTML($value);
+ }
+
+ print $fh "$key: $value\n";
+ }
+
+ # Save the date/time (in seconds) and IP address as well.
+ print $fh "date: " . time() ."\n";
+ print $fh "ip: " . $ENV{'REMOTE_ADDR'} . "\n";
+
+ # End the entry and close the file.
+ print $fh "-----\n";
+ $fh->close();
+
+ # Set responses to indicate success.
+ if ($moderate) {
+ $status_msg =
+ "Your feedback has been submitted for a moderator's approval; "
+ . "it may take 24 hours or more to appear on the site.";
+ return $fb_item, $status_msg;
+ } else {
+ $status_msg = 'OK';
+ return $feedback_fn, $status_msg;
+ }
+}
+
+
+# Generate random alphanumeric string of the specified length.
+sub rand_alphanum {
+ my $size = shift;
+ return '' if $size <= 0;
+
+ my @alphanumeric = ('a'..'z', 'A'..'Z', 0..9);
+ return join '', map $alphanumeric[rand @alphanumeric], 0..$size;
+}
+
+
+# Save previewed comment for later viewing (on the same page).
+# Sets $status_msg with an appropriate message.
+sub save_preview {
+ my $params_ref = shift;
+ my $status_msg;
+
+ # Save each parameter for later use in the preview template.
+ foreach my $key (sort keys %$params_ref) {
+ my $value = $$params_ref{$key};
+
+ # Eliminate leading and trailing whitespace, use carriage returns
+ # as line delimiters, and collapse multiple blank lines into one.
+
+ $value =~ s/^\s+//;
+ $value =~ s/\s+$//;
+ $value =~ s/\r?\n\r?/\r/mg;
+ $value =~ s/\r\r\r*/\r\r/mg;
+
+ # Ensure URL and other fields are sanitized.
+ if ($key eq 'url') {
+ $value = sanitize_uri($value);
+ } else {
+ $value = escapeHTML($value);
+ }
+
+ if ($key eq 'name') {
+ $name_preview = $value;
+ } elsif ($key eq 'url') {
+ $url_preview = $value;
+ } elsif ($key eq 'comment') {
+ $comment_preview = $value;
+ }
+ }
+
+ # Save the date/time (in seconds) as well.
+ $date_preview = time();
+
+ # Set response to indicate success.
+ $status_msg .=
+ "Please review your previewed comment below and submit it when "
+ . "you are ready.";
+
+ return $status_msg;
+}
+
+
+# Approve a moderated comment or TrackBack (add it to feedback file).
+sub approve_feedback {
+ my $item = shift;
+ my $item_fn;
+ my $status_msg = '';
+
+ # Construct filename containing item to be approved, checking the
+ # item name against the proper format from save_feedback().
+ if ($item =~ m!^[a-zA-Z0-9]{8}!) {
+ $item_fn = $item . "-" . $fb_fn;
+ } else {
+ $status_msg =
+ "The item name to be approved was not in the proper format.";
+ return $status_msg;
+ }
+
+ # Read lines from file containing the approved comment or TrackBack.
+ unless ($fh->open("$fb_dir$fb_path/$item_fn")) {
+ warn "feedback: couldn't < $fb_dir$fb_path/$item_fn\n";
+ $status_msg =
+ "There was a problem approving the comment or TrackBack.";
+ return $status_msg;
+ }
+
+ my @new_feedback = ();
+ while (<$fh>) {
+ push @new_feedback, $_;
+ }
+ $fh->close();
+
+ # Attempt to open the story's feedback file and append to it.
+ # TODO: Try to make this more resistant to race conditions.
+
+ unless ($fh->open(">> $fb_dir$fb_path/$fb_fn")) {
+ warn "couldn't >> $fb_dir$fb_path/$fb_fn\n";
+ $status_msg =
+ "There was a problem approving the comment or TrackBack.";
+ return $status_msg;
+ }
+
+ foreach my $line (@new_feedback) {
+ print $fh $line;
+ }
+
+ # Close the feedback file, delete the file with the approved item.
+ $fh->close();
+ chdir("$fb_dir$fb_path")
+ or warn "feedback: Couldn't cd to $fb_dir$fb_path\n";
+ unlink($item_fn)
+ or warn "feedback: Couldn't delete $item_fn\n";
+
+ # Set response to indicate successful approval.
+ $status_msg = "Feedback '$item' approved by moderator. ";
+
+ return $status_msg;
+}
+
+
+# Reject a moderated comment or TrackBack (delete the temporary file).
+sub reject_feedback {
+ my $item = shift;
+ my $item_fn;
+ my $status_msg;
+
+ # Construct filename containing item to be rejected, checking the
+ # item name against the proper format from save_feedback().
+ if ($item =~ m!^[a-zA-Z0-9]{8}!) {
+ $item_fn = $item . "-" . $fb_fn;
+ } else {
+ $status_msg =
+ "The item name to be rejected was not in the proper format.";
+ return $status_msg;
+ }
+
+ # TODO: Optionally report comment or TrackBack to Akismet as spam.
+
+ # Delete the file with the rejected item.
+ chdir("$fb_dir$fb_path")
+ or warn "feedback: Couldn't cd to '$fb_dir$fb_path'\n";
+ unlink($item_fn)
+ or warn "feedback: Couldn't delete '$item_fn'\n";
+
+ # Set response to indicate successful rejection.
+ $status_msg = "Feedback '$item' rejected by moderator.";
+
+ return $status_msg;
+}
+
+
+# Sanitize a query parameter to remove unexpected characters.
+sub sanitize_param
+{
+ my $param = shift || '';
+
+ # Allow only alphanumeric, underscore, dash, and period.
+ $param and $param =~ s/[^-.\w]/_/go;
+
+ return $param;
+}
+
+
+# Sanitize a URI.
+sub sanitize_uri {
+ my $uri = shift;
+
+ # Construct URI object.
+ my $u = URI->new($uri);
+
+ # If it's not a URI then assume it's an email address.
+ $u->scheme('mailto') unless defined($u->scheme);
+
+ # We check email addresses (if allowed) separately from web addresses.
+ if ($allow_mailto && $u->scheme eq 'mailto') {
+ # Make sure this is a valid RFC 822 address.
+ if (valid($u->opaque)) {
+ $uri = $u->canonical;
+ } else {
+ $status_msg = "You submitted an invalid email address. ";
+ $uri = '';
+ }
+ } elsif ($u->scheme eq 'http' || $u->scheme eq 'https') {
+ if ($u->authority =~ m!^.*@!) {
+ $status_msg =
+ "Userids and passwords are not permitted in the URL field. ";
+ $uri = '';
+ } elsif ($u->authority =~ m!^\d! || $u->authority =~ m!^\[\d!) {
+ $status_msg =
+ "IP addresses are not permitted in the URL field. ";
+ $uri = '';
+ } else {
+ $uri = $u->canonical;
+ }
+ } else {
+ $status_msg =
+ "You specified an invalid scheme in the URL field; ";
+ if ($allow_mailto) {
+ $status_msg .=
+ "the only allowed schemes are 'http', 'https', and 'mailto'. ";
+ } else {
+ $status_msg .=
+ "the only allowed schemes are 'http' and 'https'. ";
+ }
+ $uri = '';
+ }
+
+ return $uri;
+}
+
+# The following is taken from the Mail::RFC822::Address module, for
+# sites that don't have that module loaded.
+my $rfc822re;
+
+# Preloaded methods go here.
+my $lwsp = "(?:(?:\\r\\n)?[ \\t])";
+
+sub make_rfc822re {
+# Basic lexical tokens are specials, domain_literal, quoted_string, atom, and
+# comment. We must allow for lwsp (or comments) after each of these.
+# This regexp will only work on addresses which have had comments stripped
+# and replaced with lwsp.
+
+ my $specials = '()<>@,;:\\\\".\\[\\]';
+ my $controls = '\\000-\\031';
+
+ my $dtext = "[^\\[\\]\\r\\\\]";
+ my $domain_literal = "\\[(?:$dtext|\\\\.)*\\]$lwsp*";
+
+ my $quoted_string = "\"(?:[^\\\"\\r\\\\]|\\\\.|$lwsp)*\"$lwsp*";
+
+# Use zero-width assertion to spot the limit of an atom. A simple
+# $lwsp* causes the regexp engine to hang occasionally.
+ my $atom = "[^$specials $controls]+(?:$lwsp+|\\Z|(?=[\\[\"$specials]))";
+ my $word = "(?:$atom|$quoted_string)";
+ my $localpart = "$word(?:\\.$lwsp*$word)*";
+
+ my $sub_domain = "(?:$atom|$domain_literal)";
+ my $domain = "$sub_domain(?:\\.$lwsp*$sub_domain)*";
+
+ my $addr_spec = "$localpart\@$lwsp*$domain";
+
+ my $phrase = "$word*";
+ my $route = "(?:\@$domain(?:,\@$lwsp*$domain)*:$lwsp*)";
+ my $route_addr = "\\<$lwsp*$route?$addr_spec\\>$lwsp*";
+ my $mailbox = "(?:$addr_spec|$phrase$route_addr)";
+
+ my $group = "$phrase:$lwsp*(?:$mailbox(?:,\\s*$mailbox)*)?;\\s*";
+ my $address = "(?:$mailbox|$group)";
+
+ return "$lwsp*$address";
+}
+
+sub strip_comments {
+ my $s = shift;
+# Recursively remove comments, and replace with a single space. The simpler
+# regexps in the Email Addressing FAQ are imperfect - they will miss escaped
+# chars in atoms, for example.
+
+ while ($s =~ s/^((?:[^"\\]|\\.)*
+ (?:"(?:[^"\\]|\\.)*"(?:[^"\\]|\\.)*)*)
+ \((?:[^()\\]|\\.)*\)/$1 /osx) {}
+ return $s;
+}
+
+# valid: returns true if the parameter is an RFC822 valid address
+#
+sub valid ($) {
+ my $s = strip_comments(shift);
+
+ if (!$rfc822re) {
+ $rfc822re = make_rfc822re();
+ }
+
+ return $s =~ m/^$rfc822re$/so;
+}
+
+
+1;
+
+
+# Default feedback templates.
+__DATA__
+html comment \n<div class="comment"><p>$feedback::name_link wrote at $feedback::date:</p>\n<blockquote>$feedback::comment</blockquote></div>
+html trackback \n<div class="trackback"><p>$feedback::blog_name mentioned this post in $feedback::title_link<?$feedback::excerpt eq="">.</p></?><?$feedback::excerpt ne="">:</p>\n<blockquote>$feedback::excerpt</blockquote></?></div>
+html commentform \n<form method="POST" action="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::flavour">\n<table><tr><td>Name:</td><td><input name="name" size="35" value="$feedback::name_preview"></td></tr>\n<tr><td>URL (optional):</td><td><input name="url" size="35" value="$feedback::url_preview"></td></tr>\n<tr><td>Comments:</td><td><textarea name="comment" rows="5" cols="60">$feedback::comment_preview</textarea></td></tr>\n<tr><td><input type="hidden" name="plugin" value="writeback"><input type="submit" name="submit" value="Preview"></td><td><input type="submit" name="submit" value="Post"></td></tr>\n</table></form>
+html trackbackinfo <p>URL for TrackBack pings: <code>$blosxom::url$blosxom::path/$blosxom::fn.$feedback::trackback_flavour</code></p>\n<!--\n<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:trackback="http://madskills.com/public/xml/rss/module/trackback/">\n<rdf:Description rdf:about="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::flavour" dc:identifier="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::flavour" dc:title="$blosxom::title" trackback:ping="$blosxom::url$blosxom::path/$blosxom::fn.$feedback::trackback_flavour" />\n</rdf:RDF>\n-->
+general comment \n<div class="comment"><p>$feedback::name_link wrote at $feedback::date:</p>\n<blockquote>$feedback::comment</blockquote></div>
+general trackback \n<div class="trackback"><p>$feedback::blog_name mentioned this post in $feedback::title_link<?$feedback::excerpt eq="">.</p></?><?$feedback::excerpt ne="">:</p>\n<blockquote>$feedback::excerpt</blockquote></?></div>
+general commentform \n<form method="POST" action="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::flavour">\n<table><tr><td>Name:</td><td><input name="name" size="35" value="$feedback::name_preview"></td></tr>\n<tr><td>URL (optional):</td><td><input name="url" size="35" value="$feedback::url_preview"></td></tr>\n<tr><td>Comments:</td><td><textarea name="comment" rows="5" cols="60">$feedback::comment_preview</textarea></td></tr>\n<tr><td><input type="hidden" name="plugin" value="writeback"><input type="submit" name="submit" value="Preview"></td><td><input type="submit" name="submit" value="Post"></td></tr>\n</table></form>
+general trackbackinfo <p>URL for TrackBack pings: <code>$blosxom::url$blosxom::path/$blosxom::fn.$feedback::trackback_flavour</code></p>\n<!--\n<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:trackback="http://madskills.com/public/xml/rss/module/trackback/">\n<rdf:Description rdf:about="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::flavour" dc:identifier="$blosxom::url$blosxom::path/$blosxom::fn.$blosxom::flavour" dc:title="$blosxom::title" trackback:ping="$blosxom::url$blosxom::path/$blosxom::fn.$feedback::trackback_flavour" />\n</rdf:RDF>\n-->
+trackback content_type application/xml
+trackback head
+trackback story $feedback::trackback_response
+trackback date
+trackback foot
+__END__
+
+=head1 NAME
+
+Blosxom Plug-in: feedback
+
+=head1 SYNOPSIS
+
+Provides comments and TrackBacks
+(C<http://www.movabletype.org/trackback/>); also supports comment and
+TrackBack moderation and spam filtering using Akismet and/or
+MT-Blacklist (deprecated). Inspired by the original writeback plug-in
+and the various enhanced versions of it.
+
+Comments and TrackBack pings for a particular story are kept in
+C<$fb_dir/$path/$filename.wb>.
+
+=head1 QUICK START
+
+Drop this feedback plug-in file into your plug-ins directory (whatever
+you set as C<$plugin_dir> in C<blosxom.cgi>), and modify the file to
+set the configurable variable C<$fb_dir>. You must also modify the
+variable C<$wordpress_api_key> if you are using the Akismet spam
+blacklist service, the variable C<$blacklist_file> if you are using
+the MT-Blacklist file (deprecated), and the variables C<$address> and
+C<$smtp_server> if you want feedback notification or moderation. (See
+below for more information on these optional features.)
+
+Note that by default all comments and TrackBacks are allowed, with no
+spam checking, moderation, or notification.
+
+Modify your story template (e.g., C<story.html> in your Blosxom data
+directory) to include the variables C<$feedback::comments> and
+C<$feedback::trackbacks> at the points where you'd like comments and
+trackbacks to be inserted.
+
+Modify your story template or foot template (e.g., C<foot.html> in
+your Blosxom data directory) to include the variables
+C<$feedback::comment_response>, C<$feedback::preview>,
+C<$feedback::commentform> and C<$feedback::trackbackinfo> at the
+points where you'd like to insert the response to a submitted comment,
+the previewed comment (if any), the comment submission form and the
+TrackBack information (including TrackBack auto-discovery code).
+
+=head1 CONFIGURATION
+
+By default C<$fb_dir> is set to put the feedback directory and its
+contents in the plug-in state directory. (For example, if
+C<$plugin_state_dir> is C</foo/blosxom/state> then the feedback
+directory C<$fb_dir> is set to C</foo/blosxom/state/feedback>.)
+However a better approach may be to keep the feedback directory at the
+same level as C<$datadir>. (For example, if C<$datadir> is
+C</foo/blosxom/data> then use C</foo/blosxom/feedback> for the
+feedback directory.) This helps ensure that you don't accidentally
+delete previously-submitted comments and TrackBacks (e.g., if you
+clean out the plug-in state directory).
+
+Once C<$fb_dir> is set, the next time you visit your site the feedback
+plug-in will perform some checks, creating the directory C<$fb_dir>
+and setting appropriate permissions on the directory if it doesn't
+already exist. (Check your web server error log for details of what's
+happening behind the scenes.)
+
+Set the variables C<$allow_comments> and C<$allow_trackbacks> to
+enable or disable comments and/or TrackBacks; by default the plug-in
+allows both comments and TrackBacks to be submitted. The variables
+C<$comment_period> and C<$trackback_period> specify the amount of time
+after a story is published (or updated) during which comments or
+TrackBacks may be submitted (90 days by default); set these variables
+to zero to allow submission of feedback at any time after publication.
+
+Set the variables C<$akismet_comments> and C<$akismet_trackbacks> to
+enable or disable checking of comments and/or TrackBacks against the
+Akismet spam blacklist service (C<http://www.akismet.com>). If Akismet
+checking is enabled then you must also set C<$wordpress_api_key> to
+your personal WordPress API key, which is required to connect to the
+Akismet service. (You can obtain a WordPress API key by registering
+for a free blog at C<http://www.wordpress.com>; as a side effect of
+registering you will get an API key that you can then use on any of
+your blogs, whether they're hosted at wordpress.com or not.)
+
+Set the variables C<$blacklist_comments> and C<$blacklist_trackbacks>
+to enable or disable checking of comments and/or TrackBacks against
+the MT-Blacklist file. If blacklist checking is enabled then you must
+also set C<$blacklist_file> to a valid value. (Note that in the past
+you could get a copy of the MT-Blacklist file from
+C<http://www.jayallen.org/comment_spam/blacklist.txt>; however that
+URL is no longer active and no one is currently maintaining the
+MT-Blacklist file. We are therefore deprecating use of the
+MT-Blacklist file, except for people who already have a copy of the
+file and are currently using it; we suggest using Akismet instead.)
+
+Set the variables C<$notify_comments> and C<$notify_trackbacks> to
+enable or disable sending an email message to you each time a new
+comment and/or TrackBack is submitted. If notification is enabled then
+you must set C<$address> and C<$smtp_server> to valid values.
+Typically you would set C<$address> to your own email address (e.g.,
+'jdoe@example.com') and C<$smtp_server> to the fully-qualified domain
+name of the SMTP server you normally use to send outbound mail from
+your email account (e.g., 'smtp.example.com').
+
+Set the variables C<$moderate_comments> and C<$moderate_trackbacks> to
+enable or disable moderation of comments and/or TrackBacks; moderation
+is done by sending you an email message with the submitted comment or
+TrackBack and links on which you can click to approve or reject the
+comment or TrackBack. If moderation is enabled then you must set
+C<$address> and C<$smtp_server> to valid values; see the discussion of
+notification above for more information.
+
+=head1 FLAVOUR TEMPLATE VARIABLES
+
+Unlike Rael Dornfest's original writeback plug-in, this plug-in does
+not require or assume that you will be using a special Blosxom flavour
+(e.g., the 'writeback' flavour) in order to display comments with
+stories. Instead you can display comments and/or TrackBacks with any
+flavour whatsoever (except the 'trackback' flavour, which is reserved
+for use with TrackBack pings). Also unlike the original writeback
+plug-in, this plug-in separates display of comments from display of
+TrackBacks and allows them to be formatted in different ways.
+
+Insert the variables C<$feedback::comments> and/or
+C<$feedback::trackbacks> into the story template for the flavour or
+flavours for which you wish comments and/or TrackBacks to be displayed
+(e.g., C<story.html>). Note that the plug-in will automatically set
+these variables to undefined values unless the page being displayed is
+for an individual story.
+
+Insert the variables C<$feedback::comments_count> and/or
+C<$feedback::trackbacks_count> into the story templates where you wish
+to display a count of the comments and/or TrackBacks for a particular
+story. Note that these variables are available on all pages, including
+index and archive pages. As an alternative you can use the variable
+C<$feedback::count> to display the combined total number of comments
+and TrackBacks (analogous to the variable C<$writeback::count> in the
+original writeback plug-in).
+
+Insert the variables C<$feedback::commentform> and
+C<$feedback::trackbackinfo> into your story or foot template for the
+flavour or flavours for which you want to enable submission of
+comments and/or TrackBacks (e.g., C<foot.html>);
+C<$feedback::commentform> is an HTML form for comment submission,
+while C<$feedback::trackbackinfo> displays the URL for TrackBack pings
+and also includes RDF code to support auto-discovery of the TrackBack
+ping URL. Note that the plug-in sets C<$feedback::commentform> and
+C<$feedback::trackbackinfo> to be undefined unless the page being
+displayed is for an individual story.
+
+The plug-in also sets C<$feedback::commentform> and/or
+C<$feedback::trackbackinfo> to be undefined if comments and/or
+TrackBacks have been disabled globally (i.e., using C<$allow_comments>
+or C<$allow_trackbacks>). However if comments or TrackBacks are closed
+because the story is older than the time set using C<$comment_period>
+or C<$trackback_period> then the plug-in sets C<$feedback::commentform>
+or C<$feedback::trackbackinfo> to display an appropriate message.
+
+Insert the variable C<$feedback::comment_response> into your story or
+foot template to display a message indicating the results of
+submitting or moderating a comment. Note that
+C<$feedback::comment_response> has an undefined value unless the
+displayed page is in response to a POST request containing a comment
+submission (i.e., using the 'Post' or 'Preview' buttons) or a GET
+request containing a moderator approval or rejection.
+
+Insert the variable C<$feedback::preview> into your story or foot
+template at the point at which you'd like a previewed comment to be
+displayed. Note that C<$feedback::preview> will be undefined except on
+an individual story page displayed in response to a comment submission
+using the 'Preview' button.
+
+=head1 COMMENT AND TRACKBACK TEMPLATES
+
+This plug-in uses a number of flavour templates to format comments and
+TrackBacks; the plug-in contains a full set of default templates for
+use with the 'html' flavour, as well as a full set of 'general'
+templates used as a default for other flavours. You can also supply
+your own comment and TrackBack templates in the same way that you can
+define other Blosxom templates, by putting appropriately-named
+template files into the Blosxom data directory (or one or more of its
+subdirectories, if you want different templates for different
+categories).
+
+The templates used for displaying comments and TrackBacks are
+analogous to the story template used for displaying stories; the
+templates are used for each and every comment or TrackBack displayed
+on a page:
+
+=over
+
+=item
+
+comment template (e.g., C<comment.html>). This template contains the
+content to be displayed for each comment (analogous to the writeback
+template used in the original writeback plug-in). Within this template
+you can use the variables C<$feedback::name> (name of the comment
+submitter), C<$feedback::url> (URL containing the comment submitter's
+email address or web site), C<$feedback::date> (date/time the comment
+was submitted), and C<$feedback::comment> (the comment itself). You
+can also use the variable C<$feedback::name_link>, which combines
+C<feedback::name> and C<$feedback::url> to create an (X)HTML link if
+the commenter supplied a URL, and otherwise is the same as
+C<$feedback::name>. Note that this template is also used for previewed
+comments.
+
+=item
+
+trackback template (e.g., C<trackback.html>). This template contains
+the content to be displayed for each TrackBack (analogous to the
+writeback template used in the original writeback plug-in). Within
+this template you can use the variables C<$feedback::blog_name> (name
+of the blog submitting the TrackBack), C<$feedback::title> (title of
+the blog post making the TrackBack), C<$feedback::url> (URL for the
+blog post making the TrackBack), C<$feedback::date> (date/time the
+TrackBack was submitted), and C<$feedback::excerpt> (an excerpt from
+the blog post making the TrackBack). You can also use the variable
+C<$feedback::title_link>, which combines C<$feedback::title> and
+C<$feedback::url> and is analogous to C<$feedback::name_link>.
+
+=back
+
+The feedback plug-in also uses the following templates:
+
+=over
+
+=item
+
+commentform template (e.g., C<commentform.html>). This template
+provides a form for submitting a comment. The default template
+contains a form containing fields for the submitter's name, email
+address or URL, and the comment itself; submitting the form initiates
+a POST request to the same URL (and Blosxom flavour) used in
+displaying the page on which the form appears. If you define your own
+commentform template note that the plug-in requires the presence of a
+'plugin' hidden form variable with the value set to 'writeback'; this
+tells the plug-in that it should handle the incoming data from the POST
+request rather than leaving it for another plug-in. Also note that in
+order to support both comment posting and previewing the form has two
+buttons, both with name 'submit' and with values 'Post' and 'Preview'
+respectively; if you change these names and values then you must
+change the plug-in's code.
+
+=item
+
+trackbackinfo template (e.g., C<trackbackinfo.html>). This template
+provides information for how to go about submitting a TrackBack. The
+default template provides both a displayed reference to the TrackBack
+ping URL and non-displayed RDF code by which other systems can
+auto-discover the TrackBack ping URL.
+
+=back
+
+=head1 SECURITY
+
+This plug-in has at least the following security-related issues, which
+we attempt to address as described:
+
+=over
+
+=item
+
+The plug-in handles POST and GET requests with included parameters of
+potentially arbitrary length. To help minimize the possibility of
+problems (e.g., buffer overruns) the plug-in truncates all parameters
+to a maximum length (currently 10,000 bytes).
+
+=item
+
+People can submit arbitrary content as part of a submitted comment or
+TrackBack ping, with that content then being displayed as part of the
+page viewed by other users. To help minimize the possibility of
+attacks involving injection of arbitrary page content, the plug-in
+"sanitizes" any submitted HTML/XHTML content by converting the '<'
+character and other problematic characters (including '>' and the
+double quote character) to the corresponding HTML/XHTML character
+entities. The plug-in also sanitizes submitted URLs by URL-encoding
+characters that are not permitted in a URL.
+
+=item
+
+When using moderation, comments or TrackBacks are approved (or
+rejected) by invoking a GET (or HEAD) request using the URL of the
+story to which the comment or TrackBack applies, with the URL having
+some additional parameters to signal whether the comment should be
+approved or rejected. Since the feedback plug-in does not track (much
+less validate) the source of the moderation request, in theory
+spammers could approve their own comments or TrackBacks simply by
+following up their feedback submission with a GET request of the
+proper form. To minimize the possibility of this happening we generate
+a random eight-character alphanumeric key for each submitted comment
+or TrackBack, and require that that key be supplied in the approval or
+rejection request. This provides reasonable protection assuming that a
+spammer is not intercepting and reading your personal email (since the
+key is included in the moderation email message).
+
+=back
+
+=head1 VERSION
+
+0.23
+
+=head1 AUTHOR
+
+This plug-in was created by Frank Hecker, hecker@hecker.org; it was
+based on and inspired by the original writeback plug-in by Rael
+Dornfest together with modifications made by Fletcher T. Penney, Doug
+Alcorn, Kevin Scaldeferri, and others.
+
+=head1 SEE ALSO
+
+More on the feedback plug-in: http://www.hecker.org/blosxom/feedback
+
+Blosxom Home/Docs/Licensing: http://www.blosxom.com/
+
+Blosxom Plug-in Docs: http://www.blosxom.com/plugin.shtml
+
+=head1 BUGS
+
+Address bug reports and comments to the Blosxom mailing list
+[http://www.yahoogroups.com/group/blosxom].
+
+=head1 LICENSE
+
+The feedback plug-in
+Copyright 2003-2006 Frank Hecker, Rael Dornfest, Fletcher T. Penney,
+ Doug Alcorn, Kevin Scaldeferri, and others
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
projects / matthijs / upstream / blosxom-plugins.git / blobdiff