Constructor

 my $w = new WWW::Scripter %args

The constructor accepts named arguments. There are only two that WWW::Scripter itself deals with directly. The rest are passed on to the superclass. See WWW::Mechanize and LWP::UserAgent for details on what other arguments the constructor accepts.

The two arguments are:

max_docs

The maximum number of document objects to keep in history (along with their corresponding request and response objects). If this is omitted, Mech's "stack_depth" + 1 will be used. This is off by one because "stack_depth" is the number of pages you can go back to, so it is one less than the number of recorded pages. "max_docs" considers 0 to be equivalent to infinity.

max_history

If the number of items in history exceeds "max_docs", WWW::Scripter will still keep the request objects (so you can go back more than "max_docs" times and previously visited pages will reload). "max_history" restricts the total number of items in history (whether full document objects or just requests). 0 is equivalent to infinity.

The Window Interface

location

Returns the location object (see WWW::Scripter::Location). If you pass an argument, it sets the "href" attribute of the location object.

alert

confirm

prompt

Each of these calls the function assigned by one of the "set_*" methods below under "Window-Related Methods".

navigator

Returns the navigator object. See WWW::Scripter::Navigator.

screen

Returns the screen object. It currently has no features.

setTimeout ( $code_string, $ms );

setTimeout ( $coderef, $ms, @args );

This schedules the code to run after $ms milliseconds have elapsed, returning a number uniquely identifying the time-out. If the first argument is a coderef or an object with "&{}" overloading, it will be called as such. Otherwise, it is parsed as a string of JavaScript code. (If the JavaScript plugin is not loaded, it will be ignored.)

setInterval ( $code_string, $ms );

setInterval ( $coderef, $ms, @args );

This method is just like "setTimeout", except that, when the code runs, it schedules it to run again after $ms milliseconds.

clearTimeout ( $timeout_id )

The cancels the time-out corresponding to the $timeout_id. This only works for those registered with "setTimeout".

clearInterval ( $timer_id )

The cancels the timer corresponding to the $timer_id. This only works for those registered with "setInterval".

open ( $url, $target, $features, $replace )

If $target is not specified or if there is no window or frame named $target, this methods opens the $url in a new window in multiple-window mode, or at the top-level window in single-window mode.

If there is a window or frame named $target, then the $url is opened in that window. If $replace is true, it replaces the current page.

A relative $url is resolved according to the base URL of the current window (the one that "open" is called on), not the $target.

The $features argument is ignored.

close

In multiple-window mode, this detaches this window from its window group. In single-window mode (when there is no window group) it goes back to the previous entry in history (so that it is the opposite of "open").

focus

In multiple-window mode, this brings this window to the front. In single-window mode (when there is no window group) it does nothing.

blur

In multiple-window mode, this sends this window back one, if it is the frontmost window. In single-window mode (when there is no window group) it does nothing.

history

Returns the history object. See WWW::Scripter::History.

window

self

These two return the window object itself.

frames

Although the W3C DOM specifies that this return $w (the window itself), for efficiency's sake this returns a separate object which one can use as a hash or array reference to access its sub-frames. (The window object itself cannot be used that way.) The frames object (class WWW::Scripter::Frames) also has a "window" method that returns $w.

In list context a list of frames is returned.

length

Returns the number of frames. "$w->length" is equivalent to "scalar @{$w->frames}".

top

Returns the 'top' window, which is the window itself if there are no frames.

parent

Returns the parent frame, if there is one, or the window object itself otherwise.

name

This returns the window's name, if applicable. For a frame, this comes from the frame element to which the window belongs. For a top-level window created by "open", this is the name that was passed as the second argument.

scroll

scrollTo

scrollBy

These exist in case scripts try to call them. They don't do anything.

Window-Related Methods

set_alert_function

set_confirm_function

set_prompt_function

Use these to set the functions called by the above methods. There are no default "confirm" and "prompt" functions. The default "alert" prints to the currently selected file handle, with a line break tacked on the end.

check_timers

This evaluates the code associated with each timeout registered with the "setTimeout" method, if the appropriate interval has elapsed.

count_timers

This returns the number of timers currently registered.

wait_for_timers ( %args )

This method waits for any registered timers to finish (calling "check_timers" repeatedly in a loop). Its %args are as follows:

  max_wait    Number indicating for how many seconds the loop
              should run before giving up and returning.
  min_timers  Only run until this many timers are left, not until
              they have all finished.
  interval    Number of seconds to wait before each iteration of
              the loop.  The default is .1.
    

Some websites have timers running constantly, that are never cleared. For these, you will usually need to set a value for "min_timers" (or "max_wait") to avoid an infinite loop.

window_group

This returns the window group that owns this window. See "SINGLE VS MULTIPLE WINDOWS", above.

You can also pass an argument to set it, but you should only do so if you know what you are doing, as it does not update the window group's list. Consider using WWW::Scripter::WindowGroup's "attach" method (which itself uses this method).

find_target ( $name )

This finds the WWW::Scripter object (window or frame) in which a link will be opened.

If $name is not an empty string, it returns the window corresponding to $name.

If $name is the empty string or undefined, it returns the default target for this window, based on the first "<base target>" element.

If a named window cannot be found: in multiple-window mode, a new window is opened and returned; in single-window mode, "undef" is returned.

Methods for Fetching Images

fetch_images ( $new_val )

A boolean indicating whether images should be fetched. Some sites use images with special URLs as cookies and refuse to work if those images are not fetched. Most of the time, however, you probably want to leave this off, for speed's sake.

Setting this does not affect any pages that are already loaded.

image_handler ( $coderef )

A subroutine for handling any images that are fetched. The subroutine will be passed three arguments: 0) the WWW::Scripter object, 1) the image or input element and 2) the response object.

Methods for Plugins, Scripting, etc.

eval ( $code [, $scripting_language] )

Evaluates the $code passed to it. This method dies if there is no script handler registered for the $scripting_language.

use_plugin ( $plugin_name [, @options] )

This will automatically "require()" the plugin for you, and then initialise it. To pass extra options to the plugin after loading it, just use the same syntax again. This will return the plugin object if the plugin has one.

plugin ( $plugin_name )

This will return the plugin object, if it has one. Some plugins may provide this as a way to communicate directly with the plugin.

You can also use the return value as a boolean, to see whether a plugin is loaded.

dom_enabled ( $new_val )

This returns a boolean indicating whether HTML pages are parsed and turned into a DOM tree. It is true by default. You can disable HTML parsing by passing a false value. Of course, if you are using WWW::Scripter to begin with, you won't want to turn this off will you? Nevertheless, this is useful for fetching files behind the scenes when just the file contents are needed.

scripts_enabled ( $new_val )

This returns a boolean indicating whether scripts are enabled. It is true by default. You can disable scripts by passing a false value. When you disable scripts, event handlers are also disabled, as is the registration of event handlers by HTML event attributes.

script_handler ( $language_re, $object )

A script handler is a special object that knows how to run scripts in a particular language. Use this method to register such an object.

$language_re is a regular expression that will be matched against a scripting language name (from a 'language' HTML attribute) or MIME type (<script type=...). You can also use the special value 'default'.

$object is the script handler object. For its interface, see "SCRIPT HANDLERS", below.

class_info ( \%interfaces )

With this you can provide information for binding Perl classes to scripting languages, so that scripts can handle objects of those classes.

You should pass a hash ref that has the structure described in HTML::DOM::Interface, except that this method also accepts a "_constructor" hash element, which should be set to the name of the method to be called when the constructor function is called from the scripting language (e.g., "_constructor => 'new'") or a subroutine reference.

The return value is a list of all hashrefs passed to "class_info" so far plus a few that WWW::Scripter has by default (to support the DOM). You can call it without any arguments just to get that list.

Other Methods

forward

The equivalent of hitting the 'forward' button in a browser. This, of course, only works after "back".

clear_history ( $including_current_page )

This clears the history, preventing "back" from working until after the next request, and freeing up some memory. If supplied with a true argument, it also clears the current page. It returns $w.

max_history

max_history ( $new_value )

max_docs

max_docs ( $new_value )

These two return what was passed to the constructor, optionally setting it.

Notes About WWW::Mechanize Methods

links

WWW::Scripter overrides the "_extract_links" method that "links", "find_link" and "follow_link" use behind the scenes, to make it use the HTML DOM tree instead of the source code of the page.

This overridden method tries hard to match WWW::Mechanize as closely as possible, which means it includes link tags, (i)frames, and meta tags with http-equiv set to 'refresh'.

This is significantly different from "$w->document->links", an HTML::DOM method that follows the W3C DOM spec and returns only 'a' and 'area' elements.

Handlers

From within LWP's "request_*" and "response_*" handlers, you can call "WWW::Scripter::abort" to abort the request and prevent a new entry from being created in browser history. (The JavaScript plugin does this with javascript: URLs.)

WWW::Scripter will export this function upon request:

  use WWW::Scripter qw[ abort ];

or you can call it with a fully qualified name:

  WWW::Scripter::abort();