=head1 NAME

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             ('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.


=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"

=head2 _htmlparse_get_text

Auxiliary function within

=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>

=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

If C<$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.

=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"


=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 <schwigon@cpan.org>

=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.