/ 
Acme-PM-Dresden-0.09
/ Acme::PM::Dresden::TWikiClient

NAME

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

SYNOPSIS

# use
use Acme::PM::Dresden::TWikiClient; 
my $client = new Acme::PM::Dresden::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             ('http://twiki.org/cgi-bin/');
$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);

ABOUT

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

It's just within the Acme namespace because it developed within Acme::PM::Dresden::*. It is by all means meant to be a useful module.

It was developed during the same time when WWW:Mechanize::TWiki version 0.06 was uploaded, so I didn't have a look at the new features there yet and don't want to throw away my class.

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 (e.g., at http://twiki.org) 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

See http://twiki.org/ for more information about TWiki.

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

METHODS

Acme::PM::Dresden::TWikiClient inherits from WWW:Mechanize|WWW::Mechanize. See there for more methods.

new

Constructor. Takes an argument hash:

bin_url

The base URL, where the twiki binaries are reached, e.g. "http://twiki.org/cgi-bin/".

current_default_web

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.

current_topic

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.

auth_user

Set your TWiki username here.

auth_passwd

Set your TWiki password here.

override_locks

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.

verbose

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.

pre_init

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

post_init

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

get_basic_credentials

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

htmlparse_extract_single_textarea

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

_htmplparse_get_text

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.

$client->edit_press_cancel;

Cancels edit of current_topic.

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

Returns the raw topic content. Uses $opt 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 $opt current_topic if no $optional_topic_name given.

Attaches (uploads) a local file to the topic. Uses $opt 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).

SKIN OVERRIDABLE METHODS

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.

_skin_regex_authentication_failed

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.

_skin_regex_topic_locked

This regex is for matching "topic locked" page.

_skin_regex_topic_locked_edit_anyway

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

AUXILIARY METHODS

_save_topic_Save

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.

_save_topic_handle_locks

Checks for lock and overrides ot if override_locks is set.

AUTHOR

Steffen Schwigon <schwigon@cpan.org>

LICENSE

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