# Blosxom Plugin: writeback # Author(s): Rael Dornfest # 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 = ""; # 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'; 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!!0!m; $trackback_response =~ s!\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!!1!m; $trackback_response =~ s!trackback error!!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 , http://www.raelity.org/ This plugin is now maintained by the Blosxom Sourceforge Team, . =head1 SEE ALSO Blosxom Home/Docs/Licensing: http://blosxom.sourceforge.net/ Blosxom Plugin Docs: http://blosxom.sourceforge.net/documentation/users/plugins.html =head1 BUGS None known; please send bug reports and feedback to the Blosxom development mailing list . =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.