# Blosxom Plugin: writeback

# Blosxom Plugin: writeback
# Author(s): Rael Dornfest <[email protected]>
# 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::datadir/writeback";

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

# 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 !;

# --------------------------------

# 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;

# 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;

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;

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) ) {

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") ) {
foreach ( @fields ) {
my $p = param($_);
$p =~ s/<.*?>//mg; # a gross way to prevent tomfoolery, to be redone
$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 your comment.";

# 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.";
}
}

1;
}

sub story {
my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;

$path =~ s!^/*!!; $path &&= "/$path";

($writebacks, $count) = ('', 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'};
}

if ( $fh->open("$writeback_dir$path/$filename.$file_extension") ) {
foreach my $line (<$fh>) {
$line =~ /^(.+?):\s*(.*)$/ and $param{$1} = $2;
if ( $line =~ /^-----$/ ) {

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

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

}

$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 <[email protected]>, 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.