The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
WWW-Mechanize-TWiki-0.12
++
/ WWW::Mechanize::TWiki

NAME

WWW::Mechanize::TWiki - WWW::Mechanize subclass to navigate TWiki wikis

SYNOPSIS

This document describes a subclass of WWW::Mechanize. Knowledge of WWW::Mechanize usage is assumed.

  use File::Basename;
  use WWW::Mechanize::TWiki;

  my $mech = WWW::Mechanize::TWiki->new( agent => File::Basename::basename( $0 ), autocheck => 1 ) or die $!;
  $mech->cgibin( 'http://ntwiki.ethermage.net/~develop/cgi-bin', { scriptSuffix => '' } );

  # (optional) establish credentials --- do this *after* setting cgibin
# $mech->credentials( undef, undef, USERNAME => PASSWORD );

  # get a list of topics in the _default web (typically somewhere around 11 topics)
  my @topics = $mech->getPageList( '_default' );

  # create a new page (no modifications, just use the template)
  my $topic = 'Tinderbox.TestsReportSvn' .$svnRev;
  $mech->edit( $topic, { 
      topicparent => 'WebHome', 
      templatetopic => 'TestReportTemplate',
      formtemplate => 'TestReportForm',
  } );
  $mech->click_button( value => 'Save' );

  # attach a file to the newly-created topic
  $mech->follow_link( text => 'Attach' );
  $mech->submit_form( fields => {
      filepath => 'report.txt',
      filecomment => `date`,
      hidefile => undef,
  } );

  # change a topic
  $mech->edit( $topic );
  $mech->field( text => 'New topic text' );
  $mech->click_button( value => 'Save' );

  # append to a topic
  $mech->edit( $topic );
  my $text = $mech->field( 'text' );
  $text .= "   * Adding to the text! `date`";
  $mech->field( text => $text );
  $mech->click_button( value => 'Save' );

DESCRIPTION

WWW::Mechanize::TWiki provides a programatic interface to TWiki's REST interface. It does this by mapping perl functions and data structures onto a TWiki URI.

For example, WWW::Mechanize::TWiki will turn this method call

  $mech->edit( 'Tinderbox.TestsReportSvn', { 
      topicparent => 'WebHome', 
      templatetopic => 'TestReportTemplate',
      formtemplate => 'TestReportForm',
  } );

into the following URI: (encoding as needed)

  http://twiki.org/cgi-bin/twiki/edit/Tinderbox.TestReport?topicparent=WebHome;templatetopic=TestReportTemplate;formtemplate=TestReportForm

(or http://twiki.org/cgi-bin/twiki/edit.cgi/Tinderbox.TestReport..., or http://twiki.org/cgi-bin/twiki/edit.pl/Tinderbox.TestReport..., etc. depending on the scriptSuffix option passed to cgibin())

This is the added functionality on top of CPAN:WWW::Mechanize. CPAN:WWW::Mechanize functions can still be called, naturally.

Setup / Configuration

cgibin( cgi-uri, { scriptSuffix } );

Gets or sets the URI cgi-bin directory of the TWiki scripts

        $mech->cgibin( 'http://twiki.org/cgi-bin/twiki/' );
        print $mech->cgibin();
>http://twiki.org/cgi-bin/twiki/

        $mech->cgibin( 'http://tinderbox.wbniv.wikihosting.com/cgi-bin/twiki/', { scriptSuffix => '.cgi' } );
        print $mech->cgibin();
>http://tinderbox.wbniv.wikihosting.com/cgi-bin/twiki/

pub( pub-uri );

Gets or sets the URI of the TWiki pub directory

        setting pub is optional, although generally recommended.  it is required for downloading or managing 
        attachments.

Web Methods

getPageList( webName );

Returns an array of (fully-qualified) topic names for the specified webName

        my @topics = $mech->getPageList( '_default' );
        print "@topics\n";
>WebChanges WebHome WebIndex WebLeftBar WebNotify WebPreferences WebRss WebSearch WebSearchAdvanced WebStatistics WebTopicList

        my @topics = $mech->getPageList( '_empty' );
        print "@topics\n";
>

Topic Methods

getAttachmentsList( topicName );

Returns an array of attachments of a fully-qualified topicName (includes wiki web name). Each array element is a hash reference which is keyed by the column names.

        my @attachments = getAttachmentsList( 'TWiki.WabiSabi' );
        print Data::Dumper::Dumper( \@attachments );
>$VAR1 = [
>       { 'filename' => 'report.txt', comment => '', hidden => '' },
>       { 'filename' => 'report2.txt', comment => '', hidden => 'h' },
>];

Automatic Methods and Parameters

Invoking method that isn't listed above will construct a URI based on the method's name and its parameters (in a hash reference) and forwards it using WWW::Mechanize::get().

EXPORT

None by default.

Examples

upgrade_topics.pl

This script

use WWW::Mechanize::TWiki; use Getopt::Long;

my $Config;

my $result = GetOptions( $Config, # 'cgibin=s', 'scriptsuffix=s', 'web=s', 'user=s', 'password=s', # miscellaneous/generic options 'verbose|v', );

my $mech = WWW::Mechanize::TWiki->new() or die $!; $mech->cgibin( $Config->{cgibin}, { scriptSuffix => $Config->{scriptsuffix} } ); $mech->credentials( undef, undef, $Config->{user} => $Config->{password} ) if $Config->{user};

my @topics = @ARGV ? map { "$Config->{web}/$_" } @ARGV : $mech->getPageList( $Config->{web} );

my @errors; foreach my $topic ( @topics ) { print "Processing $topic\n" if $Config->{verbose};

    $mech->edit( $topic );
    $mech->field( forcenewrevision => 'on' );
    $mech->click_button( value => 'Save' );
    push @errors, $topic if ( $mech->status() != 200 );
}
print scalar @topics, " topics\n" if $Config->{verbose};
if ( @errors )
{
    print STDERR "Errors processing the following topics:\n";
    foreach my $topic ( @errors )
    {
        print STDERR "\t$topic\n";
    }
}

bugbase_create_plugins_gateways.pl

This script snippet is used to create a gateway topic for bugs for each TWikiExtension on twiki.org: _Note_ that develop.twiki.org uses TemplateLogin, and how it has to login differently than a site using credentials.

use WWW::Mechanize::TWiki 0.11;

my $plugin_topics = qr/.+(Plugin|Contrib|AddOn)$/;

################################################################################

my $mechBugsBase = WWW::Mechanize::TWiki->new( autocheck => 1 ) or die $!; $mechBugsBase->cgibin( 'http://develop.twiki.org/~develop/cgi-bin' );

my $mechTWikiDotOrg = WWW::Mechanize::TWiki->new() or die $!; $mechTWikiDotOrg->cgibin( 'http://twiki.org/cgi-bin' );

# login to develop.twiki.org $mechBugsBase->login( 'Bugs.WebHome' ); $mechBugsBase->field( username => USERNAME ); $mechBugsBase->field( password => PASSWORD ); $mechBugsBase->submit(); # get list of extension gateway pages my @bugsTopics = $mechBugsBase->getPageList( 'Bugs', { search => $plugin_topics } );

# create new gateway page for each twiki.org extension foreach my $topic ( $mechTWikiDotOrg->getPageList( 'Plugins', { search => $plugin_topics } ) ) { my ( $extension ) = $topic =~ /^Plugins\.(.+)$/; # get base topic name next if grep { /^Bugs\.${extension}$/ } @bugsTopics; # don't change any already there

print "Creating $extension\n"; $mechBugsBase->edit( "Bugs.$extension", { templatetopic => 'ExtensionTemplate', topicparent => 'Extension', } ); $mechBugsBase->click_button( value => 'Save' ); sleep rand 3; # be nice to the poor server }

DEPENDENCIES

  CPAN:WWW::Mechanize
  CPAN:HTML::TableExtract
  CPAN:MIME::Base64 (for authentication)

SEE ALSO

WWW::Mechanize, http://twiki.org

TODO

  cgibin and pub parameters should be able to be specified in the constructor

  document use with CPAN:LWP::UserAgent::TWiki::TWikiGuest
    (and understand how to make other agents for use with LDAP, etc.)

  getAttachmentList is very specific, but it is built upon a general algorithm
    to convert a table into a perl array of hash references; make a method
    publically available

  look into ways for a TWiki installation to "publish" its interface

  TemplateLogin domains require different client code to login; look into making this happen transparently

AUTHOR

Will Norris, <wbniv@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2004,2006 by Will Norris

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.