WWW::TWikiClient - WWW::Mechanize-based client to access a TWiki.


 # use
 use WWW::TWikiClient; 
 my $client = new WWW::TWikiClient;

 # authentication
 $client->auth_user           ("TWikiUserName");
 $client->auth_passwd         ("secretpasswd");

 # handling locks
 $client->override_locks      (0);  # default 0,
                                    # set to 1 if locked topics
                                    # should be "edited anyway"

 # base config
 $client->bin_url             ('');
 $client->current_default_web ('Sandbox'); # used if not contained in topic
 $client->current_topic       ('SandBox32');

 # read and save appended text
 my $topic_content = $client->read_topic;
 $client->save_topic ($topic_content . "\n\n*TWikiClient was here.*\n\n");

 # attach a file
 $client->current_topic ('SandBox32');
 $client->attach_to_topic ("/home/ss5/tmp/image.jpg", "nice photo", 1, 1);


This class is derived from WWW::Mechanize for easy remote controlling a TWiki based website. It was originally developed to migrate from a VQWiki to TWiki.

After it lived some time under the Acme::PM::Dresden namespace I made it an extra distribution because it seems to be useful for others.

It was originally developed during the same time when WWW:Mechanize::TWiki appeared. I watched that other module for some time but my WWW::TWikiClient follows a more explicit implementation approach that worked better for me.

There are many TWikis with many different skins out there. TWikiClient tries to work quite generically. I mostly developed it with TWikis version 01Sep2004 (Cairo release) using the PatternSkin but I also did some tests against some other skins and twiki versions:

   * Beijing release (01Feb2003)
      * default skin (with only preview button in topic edit)
   * Cairo release (01Sep2004)
      * default skin (with several buttons in topic edit)
      * BlueSkin (the old version, probably 0.4)
      * PatternSkin
   * Dakar release 4.0.2
      * Reported to run, not tested by myself

See for more information about TWiki.

See the example scripts in eg/ for more complex usage.


WWW::TWikiClient inherits from WWW::Mechanize. See there for more methods.


Constructor. Takes an argument hash:


The base URL, where the twiki binaries are reached, e.g. "".


The web that is used if topics are given without web prefix. Compare "Main.WebHome" vs. "WebHome"; set current_default_web("Main") for the latter case.


The topic that is used if not given to functions. That makes it easier to set the topic and then call read_topic and save_topic with just content params.


Set your TWiki username here.


Set your TWiki password here.


If the topic is locked during save_topic, this option decides whether the TWiki link "Edit anyway" is used and the lock is ignored.

Please note, that a lock means, that another user edits the topic just in this moment and his later save will throw away your changes.


If set to a true value, then some messages or warnings are printed to STDERR, e.g., if a topic is locked. Default is 0.


Called before params are taken over. I mostly use it for setting default values in derived clases.


Called after params are taken over. I mostly use it for forcing values (and ignoring params) in derived clases.


Overwritten function to provide username and password, that were set via auth_user and auth_passwd.


Auxiliary function to extract the nameless textarea in "raw text" view.


Auxiliary function within htmlparse_extract_single_textarea.

$url = _make_url ($cmd, $topic, $optional_tail);

Auxiliary function. Constructs URL from class param bin_url, $cmd (view, edit, ...) and topic name. If topic name doesn't contain a web prefix (eg., the "Main." in "Main.WebHome"), then the class param current_default_web is used.


Cancels edit of current_topic.

my $rawcontent = $client->read_topic ($optional_topic_name);

Returns the raw topic content. Uses current_topic if no $optional_topic_name given.

my $success = save_topic ($rawcontent, $optional_topic_name);

Writes the string $rawcontent into the topic. Old content is overwritten, so if you just want to append, use read_topic and concatenate. Uses current_topic if no $optional_topic_name given.

Attaches (uploads) a local file to the topic. Uses current_topic if no $optional_topic_name given.

$local_filename should be a full path and filename.

$comment is the created text near the image.

If $create_link_flag is a true value, "images will be displayed, for other attachments a link will be created". (quoted from the TWiki description).

If $hide_file is a true value, "attachments will not be shown in topic view page". (quoted from the TWiki description).


Some behaviour might be skin dependent. The potential skin specific behaviour is sourced out into methods so that they are overridable in a class for a particular skin.


I sourced out some regexes that might be skin dependend. If you have another skin, you should only need to subclass and overwrite the _skin_*() methods.

This regex is for matching "authentication failed" page.


This regex is for matching "topic locked" page.


This regex is for finding the "Edit anyway" link in the "topic locked" page.



Does the real "Save" from the topic edit page. It simply submits the form and look whether the next page looks like a preview page, in which case it simply submits again.


Checks for lock and overrides ot if override_locks is set.


Steffen Schwigon <>


  Copyright (c) 2006. Steffen Schwigon
  All rights reserved. You can redistribute and/or modify
  this bundle under the same terms as Perl itself.