Linux Certif

Toute la documentation sur la certification Linux LPI

WWW::Mechanize::TWiki.3pm

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.