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 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 => '' } );

  # 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", 1 );
  $mech->field( text => 'New topic text' );
  $mech->click_button( value => 'Save' );

  # append to a topic
  $mech->edit( "$topic", 1 );
  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().

DEPENDENCIES

  CPAN:WWW::Mechanize
  CPAN:HTML::TableExtract

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

AUTHOR

Will Norris, <wbniv@cpan.org>

COPYRIGHT AND LICENSE

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.

CPAN RT