View on
MetaCPAN
search.cpan.org is shutting down
For details read Perl NOC. After June 25th this page will redirect to MetaCPAN.org
Steffen Schwigon > WWW-TWikiClient > WWW::TWikiClient

Download:
twikiclient/WWW-TWikiClient-0.11.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.11   Source  

NAME ^

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

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);

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 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 http://twiki.org/ for more information about TWiki.

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

METHODS ^

WWW::TWikiClient inherits from 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.

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

attach_to_topic ($local_filename, $comment, $create_link_flag, $hide_file, $optional_topic_name);

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

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) 2006. Steffen Schwigon
  All rights reserved. You can redistribute and/or modify
  this bundle under the same terms as Perl itself.
syntax highlighting: