=head1 NAME WWW::TWikiClient - WWW::Mechanize-based client to access a TWiki. =head1 SYNOPSIS # 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 ('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); =head1 ABOUT 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 I<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 L<http://twiki.org/> for more information about TWiki. See the example scripts in eg/ for more complex usage. =head1 METHODS WWW::TWikiClient inherits from L<WWW::Mechanize|WWW::Mechanize>. See there for more methods. =head2 new Constructor. Takes an argument hash: =over 4 =item bin_url The base URL, where the twiki binaries are reached, e.g. "http://twiki.org/cgi-bin/". =item 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. =item current_topic The topic that is used if not given to functions. That makes it easier to set the topic and then call C<read_topic> and C<save_topic> with just content params. =item auth_user Set your TWiki username here. =item auth_passwd Set your TWiki password here. =item override_locks If the topic is locked during C<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. =item 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. =back =head2 pre_init Called before params are taken over. I mostly use it for setting default values in derived clases. =head2 post_init Called after params are taken over. I mostly use it for forcing values (and ignoring params) in derived clases. =head2 get_basic_credentials Overwritten function to provide username and password, that were set via C<auth_user> and C<auth_passwd>. =head2 htmlparse_extract_single_textarea Auxiliary function to extract the nameless textarea in "raw text" view. =head2 _htmlparse_get_text Auxiliary function within L<htmlparse_extract_single_textarea|htmlparse_extract_single_textarea>. =head2 $url = _make_url ($cmd, $topic, $optional_tail); Auxiliary function. Constructs URL from class param C<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 C<current_default_web> is used. =head2 $client->edit_press_cancel; Cancels edit of C<current_topic>. =head2 my $rawcontent = $client->read_topic ($optional_topic_name); Returns the raw topic content. Uses C<current_topic> if no C<$optional_topic_name> given. =head2 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 C<read_topic> and concatenate. Uses C<current_topic> if no C<$optional_topic_name> given. =head2 attach_to_topic ($local_filename, $comment, $create_link_flag, $hide_file, $optional_topic_name); Attaches (uploads) a local file to the topic. Uses C<current_topic> if no C<$optional_topic_name> given. C<$local_filename> should be a full path and filename. C<$comment> is the created text near the image. If C<$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 C<$hide_file> is a true value, "attachments will not be shown in topic view page". (quoted from the TWiki description). =head1 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. =head2 _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. =head2 _skin_regex_topic_locked This regex is for matching "topic locked" page. =head2 _skin_regex_topic_locked_edit_anyway This regex is for finding the "Edit anyway" link in the "topic locked" page. =head1 AUXILIARY METHODS =head2 _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. =head2 _save_topic_handle_locks Checks for lock and overrides ot if C<override_locks> is set. =head1 AUTHOR Steffen Schwigon <email@example.com> =head1 LICENSE Copyright (c) 2006. Steffen Schwigon All rights reserved. You can redistribute and/or modify this bundle under the same terms as Perl itself.