writeback-vRobGarth

# Blosxom Plugin: writeback
# Author(s): Rael Dornfest <rael@oreilly.com> 
# Version: 2003-09-18
# Documentation: See the bottom of this file or type: perldoc writeback

package writeback;

# --- Configurable variables -----

# Where should I keep the writeback hierarchy?
# I suggest: $writeback_dir = "$blosxom::plugin_state_dir/writeback";
#
# NOTE: By setting this variable, you are telling the plug-in to go ahead
# and create a writeback directory for you.
my $writeback_dir = "$blosxom::plugin_state_dir/writeback";

# What flavour should I consider an incoming trackback ping?
# Otherwise trackback pings will be ignored!
#my $trackback_flavour = "trackback";
my $trackback_flavour = "";

# What file extension should I use for writebacks? 
# Make sure this is different from that used for your Blosxom weblog
# entries, usually txt.
my $file_extension = "wb";

# What fields are used in your comments form and by trackbacks?
my @fields = qw! name url title comment excerpt blog_name !;

# What tags are you going to allow in comment?
my @report_tags = qw! a em strong cite code pre p br ul ol li dl dt dd !;
# Tag attributes allowed?
my @allow_attr = qw! href !;
# HTML Elements in tags to ignore
my @ignore_elements = qw! script style !;

# --------------------------------
 
# Comments for a story; use as $writeback::writebacks in flavour templates
$writebacks;

# Count of writebacks for a story; use as $writeback::count in flavour templates
$count;

# Form for posting writebacks; use as $writeback::form in flavour templates
$form;

# The path and filename of the last story on the page (ideally, only 1 story
# in this view) for displaying the trackback URL;
# use as $writeback::trackback_path_and_filename in your foot flavour templates
$trackback_path_and_filename;

# Response to writeback; use as $writeback::writeback_response in 
# flavour templates
$writeback_response;

# Response to a trackback ping; use as $writeback::trackback_response in
# head.trackback flavour template
$trackback_response =<<'TRACKBACK_RESPONSE';
<?xml version="1.0" encoding="iso-8859-1"?>
<response>
<error></error>
<message></message>
</response>
TRACKBACK_RESPONSE

$blosxom::template{'trackback'} = {
  'content_type' => 'text/xml',
  'head'         => '$writeback::trackback_response',
  'date'         => ' ',
  'story'        => ' ',
  'foot'         => ' '
};
 
# --------------------------------

use CGI qw/:standard/;
use FileHandle;
use HTML::Parser;

my $fh = new FileHandle;

# Strip potentially confounding bits from user-configurable variables
$writeback_dir =~ s!/$!!; $file_extension =~ s!^\.!!;

# Save Name and URL/Email via cookie if the cookies plug-in is available
$cookie;

# make it easier to look up attributes
my %allow_attr = map { $_ => 1} @allow_attr;

sub tag {
  my($pos, $text) = @_;
  if (@$pos >= 4) {
    # remove attributes
    my($k_offset, $k_len, $v_offset, $v_len) = @{$pos}[-4 .. -1];
    my $next_attr = $v_offset ? $v_offset + $v_len : $k_offset + $k_len;
    my $edited;
    while (@$pos >= 4) {
      ($k_offset, $k_len, $v_offset, $v_len) = splice @$pos, -4;
      if (!$allow_attr{lc substr($text, $k_offset, $k_len)}) {
        substr($text, $k_offset, $next_attr - $k_offset) = "";
        $edited++;
      }
      $next_attr = $k_offset;
    }
    # if we killed all attributed, kill any extra whitespace too
    $text =~ s/^(<\w+)\s+>$/$1>/ if $edited;
  }
  open (FH, ">>/tmp/out.$$");
  print FH $text, "\n";
  close FH;
  $_[2] .= $text;
}

sub strip_html {
  my $stripped = "";
  HTML::Parser->new(api_version   => 3,
    start_h       => [ sub { \&tag(@_, $stripped) }, "tokenpos, text"],
    process_h     => ["", ""],
    comment_h     => ["", ""],
    declaration_h => ["", ""],
    default_h     => [ sub { $stripped .= shift }, "text"],

    report_tags   => \@report_tags,
    ignore_elements => \@ignore_elements,
  )
  ->parse(shift)
  ->eof;
  return $stripped;
}

sub start {

  # $writeback_dir must be set to activate writebacks
  unless ( $writeback_dir ) { 
    warn "blosxom : writeback plugin > The \$writeback_dir configurable variable is not set; please set it to enable writebacks. Writebacks are disabled!\n";
    return 0;
  }

  # the $writeback_dir exists, but is not a directory
  if ( -e $writeback_dir and ( !-d $writeback_dir or !-w $writeback_dir ) ) { 
    warn "blosxom : writeback plugin > The \$writeback_dir, $writeback_dir, must be a writeable directory; please move or remove it and Blosxom will create it properly for you.  Writebacks are disabled!\n";
    return 0;
  }
  
  # the $writeback_dir does not yet exist, so Blosxom will create it
  if ( !-e  $writeback_dir )  {

    my $mkdir_r = mkdir("$writeback_dir", 0755);

    warn $mkdir_r 
      ? "blosxom : writeback plugin > \$writeback_dir, $writeback_dir, created.\n"
      : "blosxom : writeback plugin > There was a problem creating your \$writeback_dir, $writeback_dir. Writebacks are disabled!\n";

    $mkdir_r or return 0;

    my $chmod_r = chmod 0755, $writeback_dir;

    warn $chmod_r 
      ? "blosxom : writeback plugin > \$writeback_dir, $writeback_dir, set to 0755 permissions.\n"
      : "blosxom : writeback plugin > There was a problem setting permissions on \$writeback_dir, $writeback_dir. Writebacks are disabled!\n";

    $chmod_r or return 0;

    warn "blosxom : writeback plugin > writebacks are enabled!\n";
  }

  $path_info = path_info();
  my($path,$fn) = $path_info =~ m!^(?:(.*)/)?(.*)\.$blosxom::flavour!;
  $path =~ m!^/! or $path = "/$path";
  $path = "/$path";

  # Only spring into action if POSTing to the writeback plug-in
  if ( request_method() eq 'POST' and (param('plugin') eq 'writeback' or $blosxom::flavour eq $trackback_flavour) ) {
    # Only post if there is a comment
    if (! param('comment')) {
      $writeback_response = "Sorry the comment field cannot be left blank.";
    } else {

      foreach ( ('', split /\//, $path) ) {
        $p .= "/$_";
        $p =~ s!^/!!;
        -d "$writeback_dir/$p" or mkdir "$writeback_dir/$p", 0755;
      }

      if ( $fh->open(">> $writeback_dir$path/$fn.$file_extension") ) {
        # Make a date field as well
        print $fh "date: ", scalar(localtime), "\n";
        foreach ( @fields ) {
          my $p = param($_);

          # do some variable replacements
          $p = 'Anonymous' if ($_ =~ "name" and (! param($_)) );
          $p = 'no Subject' if ($_ =~ "title" and (! param($_)) );
          $p = 'http://en.wikipedia.org/wiki/Anonymous_coward' if ($_ =~ "url" and (! param($_)) );
          $p = 'http://en.wikipedia.org/wiki/Anonymous_coward' if ($_ =~ "url" and param($_) eq 'mailto:');
          # strip out tags which aren't allowed
          my $p = &strip_html($p);
          $p =~ s/\r?\n\r?/\r/mg;
          print $fh "$_: $p\n";
        }
        print $fh "-----\n";
        $fh->close();

        $trackback_response =~ s!<error></error>!<error>0</error>!m;
        $trackback_response =~ s!<message></message>\n!!s;
        $writeback_response = "Thanks for the writeback.";

        # Make a note to save Name and URL/Email if save_preferences checked
        param('save_preferences') and $cookie++;
        # Pre-set Name and URL/Email based on submitted values
        $pref_name = param('name') || '';
        $pref_url = param('url') || '';

      } else {
        warn "couldn't >> $writeback_dir$path/$fn.$file_extension\n";

        $trackback_response =~ s!<error></error>!<error>1</error>!m;
        $trackback_response =~ s!<message>trackback error</message>!!m;
        $writeback_response = "There was a problem posting your writeback.";
      }
    }
  }
  # I don't like this it is messy - but it works.
  # If the span is included in the template it whacks out my design
  if ($writeback_response) {
    $writeback_response = '<p align="center" class="writebackResponse">' . $writeback_response . '</p>';
  }
  1;
}

sub story {
  my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
    
  $path =~ s!^/*!!; $path &&= "/$path";

  ($writebacks, $count, $form)  = ('', 0, '');
  my %param = ();

  # Prepopulate Name and URL/Email with cookie-baked preferences, if any
  if ( $blosxom::plugins{cookies} > 0 and my $cookie = &cookies::get('writeback') ) {
    $pref_name ||= $cookie->{'name'};
    $pref_url ||= $cookie->{'url'};
  }
  $pref_url = "mailto:" if (!$pref_url);

  if ( $fh->open("$writeback_dir$path/$filename.$file_extension") ) {
    foreach my $line (<$fh>) {
      $line =~ /^(.+?):\s*(.*)$/ and $param{$1} = $2;
      if ( $line =~ /^-----$/ ) {
        # Only show comments if story is on it's own page
        if ( $blosxom::path_info =~ m:\.: ) {

          my $writeback = &$blosxom::template($path,'writeback',$blosxom::flavour) || '<p><b>Name/Blog:</b> $writeback::name$writeback::blog_name<br /><b>URL:</b> $writeback::url<br /><b>Title:</b> $writeback::title<br /><b>Comment/Excerpt:</b> $writeback::comment$writeback::excerpt</p>';

          $writeback =~ s/\$writeback::(\w+)/$param{$1}/ge;
          $writebacks .= $writeback;
        }
        $count++;
      }
    }

  }

  # only show form is story is on own page
  if ( $blosxom::path_info =~ m:\.: ) {
    $form = &$blosxom::template($path,'writeback_form',$blosxom::flavour);
    if (! $form) { $form = <<'END';
<form method="POST" action="$url/$path_info">

<table border="0" cellspacing="3" cellpadding="0">
<tr><td>&nbsp;</td></tr>
<tr><td>Name:</td><td><input name="name" size="35" value="$writeback::pref_name" /></td></tr>
<tr><td>URL/Email:</td><td><input name="url" size="35" value="$writeback::pref_url" /> [http://... or mailto:you@wherever] (optional)</td></tr>
<tr><td>Title:</td><td><input name="title" size="35" /> (optional)</td></tr>
<tr><td>Comments:</td><td><textarea name="comment" rows="5" cols="60"></textarea></td></tr>
<tr><td colspan="2">
<input type="checkbox" name="save_preferences" value="1" checked /> Save my Name and URL/Email for next time
</td></tr>
<tr><td colspan="2">
<input type="hidden" name="plugin" value="writeback" />
<input type="submit" value="Post" />
</td></tr>
</table>

</form>
END
    }
    $form =~ s/\$writeback::(\w+)/${$1}/ge;
    $form =~ s/\$(\w+::\w+)/${$1}/ge;
    $form =~ s/\$(\w+)/\$blosxom::$1/g;
    $form =~ s/\$(\w+::\w+)/${$1}/ge;
  }

;

  $trackback_path_and_filename = "$path/$filename";

  1;
}

sub foot {
  $blosxom::plugins{cookies} > 0 and $cookie and &cookies::add(
    cookie(
          -name=>'writeback', 
          -value=>{ 'name' => param('name'), 'url' => param('url') }, 
          -path=>$cookies::path,
          -domain=>$cookies::domain,
          -expires=>$cookies::expires
    )
  );
}

1;


__END__

=head1 NAME

Blosxom Plug-in: writeback

=head1 SYNOPSIS

Provides WriteBacks, a combination of comments and TrackBacks 
[http://www.movabletype.org/trackback/].

All comments and TrackBack pings for a particular story are kept in
$writeback_dir/$path/$filename.cmt.

=head2 QUICK START

Drop this writeback plug-in file into your plug-ins directory 
(whatever you set as $plugin_dir in blosxom.cgi).

Writeback, being a well-behaved plug-in, won't do anything until you set 
$writeback_dir.

While you can use the same directory as your blosxom $datadir (WriteBacks
are saved as path/weblog_entry_name.wb), it's probably better to keep
them separate.

Once set, the next time you visit your site, the writeback plug-in will
perform some checks, creating the $writeback_dir and setting appropriate
permissions if it doesn't already exist.  (Check your error_log for details
of what's happening behind the scenes.)

Move the contents of the flavours folder included in this distribution 
into your Blosxom data directory (whatever you set as $datadir in blosxom.cgi).
Don't move the folder itself, only the files it contains!  If you don't
have the the sample flavours handy, you can download them from:

http://www.raelity.org/apps/blosxom/downloads/plugins/writeback.zip

Point your browser at one of your Blosxom entries, specifying the writeback 
flavour (e.g. http://localhost/cgi-bin/blosxom.cgi/path/to/a/post.writeback)

Enjoy!

=back

=head2 FLAVOUR TEMPLATE VARIABLES

Wherever you wish all the WriteBacks for a particular story to appear
in your flavour templates, use $writeback::writebacks.

A count of WriteBacks for each story may be embedded in your flavour
templates with $writeback::count.

If you'd like, you can embed a "Thanks for the writeback." or 
"There was a problem posting your writeback." message after posting with
$writeback::writeback_response.

=head2 SAMPLE FLAVOUR TEMPLATES

I've made sample flavour templates available to you to help with any
learning curve this plug-in might require.

Take a gander at the source HTML/XML for:

=item * story.writeback, a basic example of a single-entry story
flavour with WriteBacks embedded.  You should not use this as your
default flavour since every story on the home page would have WriteBacks
right there with the story itself.

=item * foot.writeback provides a simple comment form for posting to the
WriteBack plug-in.  NOTE: The writeback plug-in requires the presence
of a "plugin" form variable with the value set to "writeback"; this tells
the plug-in that it should handle the incoming POSTing data rather than
leaving it for another plug-in.

=item * writeback.writeback is a sample flavour file for WriteBacks themselves. 
Think of a WriteBacks flavour file as a story flavour file for individual 
WriteBacks.

=back

=head2 FLAVOURING WRITEBACKS

While the default does a pretty good job, you can flavour your WriteBacks
in the writeback flavour file (e.g. writeback.writeback) using the following 
variables:

=item * $writeback::name$writeback::blog_name - Name entered in comment form or weblog name used in TrackBack ping.

=item * $writeback::url - URL entered in comment form or that of writing citing your weblog entry via TrackBack ping.

=item * $writeback::title - Title entered into comment form or that of writing citing your weblog entry via TrackBack ping.

=item * $writeback::comment$writeback::excerpt - Comment entered into comment aorm or excerpt of writing citing your weblog entry via TrackBack ping.

=item * $writeback::pref_name and $writeback::pref_url are prepopulated with the values of the form you just submitted or preferences stored in a 'writeback' cookie, if you've the cookie plug-in installed an enabled.

=back

=head2 INVITING AND SUPPORTING TRACKBACKS

You should provide the TrackBack ping URL for each story so that those
wanting to TrackBack ping you manually know where to ping.  
$writeback::trackback_path_and_filename, together with $url and 
a TrackBack flavour will provide them all they need.

e.g. $url$writeback::trackback_path_and_filename.trackback

The writeback plugin provides an XML response to TrackBack pings in the form
of a baked-in trackback flavour.  If you alter the value of $trackback_flavour
(why would you?), you'll have to create a set of flavour templates by hand; all 
should be blank save the content_type (text/xml) and head ($writeback::trackback_response).

=head1 INSTALLATION

Drop writeback into your plug-ins directory ($blosxom::plugin_dir).

=head1 CONFIGURATION

=head2 (REQUIRED) SPECIFYING A WRITEBACK DIRECTORY

Writeback, being a well-behaved plug-in, won't do anything until you set 
$writeback_dir, create the directory, and make it write-able by Blosxom.

Create a directory to save WriteBacks to (e.g. $plugin_state_dir/writeback),
and set $writeback_dir to the path to that directory.

While you can use the same directory as your blosxom $datadir (WriteBacks
are saved as path/weblog_entry_name.wb), it's probably better to keep
them separate.

The writeback plug-in will create the appropriate paths to mimick your
$datadir hierarchy on-the-fly.  So, for a weblog entry in 
$datadir/some/path/or/other/entry.txt, WriteBacks will be kept in
$writeback_dir/some/path/or/other/entry.wb.

=head2 (OPTIONAL) ALTERING THE TRACKBACK FLAVOUR

The $trackback_flavour sets the flavour the plug-in associates with incoming TrackBack pings.  Unless this corresponds to the flavour associated with your trackback URL, the writeback plug-in will ignore incoming pings.

=head2 (OPTIONAL) SPECIFYING AN EXTENSION FOR WRITEBACK FILES

The default extension for WriteBacks is wb.  You can change this if
you wish by altering the $file_extension value.

=head2 (OPTIONAL) SPECIFYING WHAT FIELDS YOU EXPECT IN YOUR COMMENTS FORM

The defaults are probably ok here, but you can specify that the writeback
plug-in should look for more fields in your comments form by adding to this
list.  You should keep at least the defaults in place so as not to break
anything.

my @fields = qw! name url title comment excerpt blog_name !;

=head1 VERSION

2003-09-18

=head1 AUTHOR

Rael Dornfest  <rael@oreilly.com>, http://www.raelity.org/

=head1 SEE ALSO

Blosxom Home/Docs/Licensing: http://www.raelity.org/apps/blosxom/

Blosxom Plugin Docs: http://www.raelity.org/apps/blosxom/plugin.shtml

=head1 BUGS

Address bug reports and comments to the Blosxom mailing list 
[http://www.yahoogroups.com/group/blosxom].

=head1 LICENSE

Blosxom and this Blosxom Plug-in
Copyright 2003, Rael Dornfest 

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.