NAME
WWW::Mechanize::Plugin::JavaScript - JavaScript plugin for WWW::Mechanize
VERSION
Version 0.001
WARNING: This is an alpha release. The API is subject to change without notice.
This set of modules is at a very early stage. Only a few features have been implemented so far. Whether it will work for a particular case is hard to say. Try it and see. (And patches are always welcome.)
SYNOPSIS
use WWW::Mechanize;
$m = new WWW::Mechanize;
$m->use_plugin('JavaScript');
$m->get('http://www.cpan.org/');
$m->get('javascript:alert("Hello!")'); # prints Hello!
$m->use_plugin(JavaScript =>
engine => 'SpiderMonkey',
alert => \&alert, # custom alert function
confirm => \&confirm,
prompt => \&prompt,
init => \&init, # initialisation function
); # for the JS environmentDESCRIPTION
This module is a plugin for WWW::Mechanize that provides JavaScript capabilities (who would have guessed?).
To load the plugin, just use WWW::Mechanize's use_plugin method (note that the current stable release of that module doesn't support this; see "PREREQUISITES", below):
$m = new WWW::Mechanize;
$m->use_plugin('JavaScript');You can pass options to the plugin via the use_plugin method. It takes hash-style arguments and they are as follows:
- engine
-
Which JavaScript back end to use. Currently, this module only supports JE, a pure-Perl JavaScript interpreter. Later it will support SpiderMonkey via the JavaScript::SpiderMonkey module. If this option is not specified, either SpiderMonkey or JE will be used, whichever is available. It is possible to write one's own bindings for a particular JavaScript engine. See below, under "BACK ENDS".
- alert
-
Use this to provide a custom
alertfunction. The default one will print its arguments followed by a new line. - confirm
-
Like
alert, but for theconfirmfunction instead. There is no default. - prompt
-
Likewise.
- init
-
Pass to this option a reference to a subroutine and it will be run every time a new JavaScript environment is initialised. This happens after the functions above have been created. The first argument will be the plugin object (more on that below). You can use this, for instance, to make your own functions available to JavaScript.
METHODS
WWW::Mechanize's use_plugin method will return a plugin object. The same object can be retrieved via $m->plugin('JavaScript') after the plugin is loaded. The following methods can be called on that object:
- eval
-
This evaluates the JavaScript code passed to it. You can optionally pass two more arguments: the file name or URL, and the first line number.
- new_function
-
This creates a new global JavaScript function out of a coderef. Pass the name as the first argument and the code ref as the second.
- set
-
Sets the named variable to the value given. If you want to assign to a property of a property ... of a global property, pass each property name as a separate argument:
$m->plugin('JavaScript')->set( 'document', 'location', 'href' => 'http://www.perl.org/' ); - bind_classes
-
With this you can bind Perl classes to JavaScript, so that JavaScript 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
_constructorhash element, which should be set to the name of the method to be called when the constructor function is called within JavaScript; e.g.,_constructor => 'new'.
BACK ENDS
A back end has to be in the WWW::Mechanize::Plugin::JavaScript:: name space. It will be required by this plugin implicitly when its name is passed to the engine option.
It must provide a class method named new. This method simply has to create a JavaScript environment, with window and self properties that refer to the global object, and return an object.
The object must have methods corresponding to those listed above for the plugin object. Those methods are simply delegated to the back end.
In addition, an object method named event2sub must exist. It will be passed the source code for an event handler as the first argument, and the element to which it belongs as the second argument. It needs to turn that event handler code into a coderef, on an object that can be used as such, and then return it. That coderef will be called with an HTML::DOM::Event object as its sole argument. It's return value, if defined, will be used to determine whether the event's preventDefault method should be called.
You also need to provide a define_setter method. This will be called with a list of property names representing the 'path' to the property. The last argument will be a coderef that must be called with the value assigned to the property.
PREREQUISITES
perl 5.8.3 or later (actually, this module doesn't use any features that perl 5.6 doesn't provide, but its prerequisites require 5.8.3)
HTML::DOM 0.009 or later
JE 0.019 or later (when there is a SpiderMonkey binding available it will become optional)
The experimental version of WWW::Mechanize available at http://www-mechanize.googlecode.com/svn/branches/plugins/
BUGS
Need plenty of placeholders here :-)
AUTHOR & COPYRIGHT
Copyright (C) 2007 Father Chrysostomos <join '@', sprout => join '.', reverse org => 'cpan'>
This program is free software; you may redistribute it and/or modify it under the same terms as perl.