NAME

WWW::Scripter::Plugin::JavaScript - JavaScript plugin for WWW::Scripter

VERSION

Version 0.009 (alpha)

SYNOPSIS

  use WWW::Scripter;
  $w = new WWW::Scripter;
  
  $w->use_plugin('JavaScript');
  $w->get('http://www.cpan.org/');
  $w->get('javascript:alert("Hello!")'); # prints Hello!
  
  $w->use_plugin(JavaScript =>
          engine  => 'SpiderMonkey',
          init    => \&init, # initialisation function
  );                         # for the JS environment

DESCRIPTION

This module is a plugin for WWW::Scripter that provides JavaScript capabilities (who would have guessed?).

To load the plugin, just use WWW::Scripter's "use_plugin" method:

  $w = new WWW::Scripter;
  $w->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, the only two back ends available are JE, a pure-Perl JavaScript interpreter, and WWW::Scripter::Plugin::SpiderMonkey (that back end is bundled separately). The SpiderMonkey back end is just a proof-of-concept as of July, 2010, but may become the default in a future version. JE is now the default.
If this option is not specified, either JE or SpiderMonkey 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".
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 WWW::Scripter object. You can use this, for instance, to make your own functions available to JavaScript.

METHODS

WWW::Scripter's "use_plugin" method will return a plugin object. The same object can be retrieved via "$w->plugin('JavaScript')" after the plugin is loaded. The same plugin object is used for every page and frame, and for every new window derived from the WWW::Scripter object. The following methods can be called on that object:

eval

This evaluates the JavaScript code passed to it. The WWW::Scripter object is the first argument; the string of code the second. You can optionally pass two more arguments: the file name or URL, and the first line number.

This method sets $@ and returns "undef" if there is an error.

set

Sets the named variable to the value given. The first argument is the WWW::Scripter object. The last argument is the value. The intervening arguments are the names of properties, so if you want to assign to a property of a property ... of a global property, you can pass each property name separately like this:

  $w->plugin('JavaScript')->set(
      $w, 'document', 'location', 'href' => 'http://www.perl.org/'
  );

new_function

This creates a new global JavaScript function out of a coderef. This function is added to every JavaScript environment the plugin has access to. Pass the WWW::Scripter object as the first argument, the name as the second and the code ref as the third.

bind_classes

Instead of using this method, you might consider WWW::Scripter's "class_info" method, which is more general-purpose (it applies also to whatever other scripting languages might be available).

With this you can bind Perl classes to JavaScript, so that JavaScript can handle objects of those classes. These class bindings will persist from one page to the next.

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 within JavaScript; e.g., "_constructor => 'new'".

back_end

This returns the back end corresponding to the WWW::Scripter object passed to it, creating it if necessary. This is intended mostly for back ends themselves to use, for accessing frames, etc.

FEATURES AVAILABLE TO JAVASCRIPT

The members of the HTML DOM that are available depend on the versions of HTML::DOM and CSS::DOM installed. See HTML::DOM::Interface and CSS::DOM::Interface.

For a list of the properties of the window object, see WWW::Scripter.

BACK ENDS

A back end has to be in the WWW::Scripter::Plugin::JavaScript:: name space. It will be "require"d by this plugin implicitly when its name is passed to the "engine" option.

The following methods must be implemented:

Class methods

new

This method is passed a window (WWW::Scripter) object.

It has to create a JavaScript environment, in which the global object delegates to the window object for the members listed in %WWW::Scripter::WindowInterface.

When the window object or its frames collection (WWW::Scripter::Frames object) is passed to the JavaScript environment, the global object must be returned instead.

This method can optionally create "window", "self" and "frames" properties that refer to the global object, but this is not necessary. It might make things a little more efficient.

Finally, it has to return an object that implements the interface below.

The back end has to do some magic to make sure that, when the global object is passed to another JS environment, references to it automatically point to a new global object when the user (or calling code) browses to another page.

For instance, it could wrap up the global object in a proxy object that delegates to whichever global object corresponds to the document.

Object Methods

eval

This should accept up to three arguments: a string of code, the file name or URL, and the first line number.

It must set $@ and return "undef" if there is an error.

new_function

set

bind_classes

These correspond to those listed above for the plugin object. Unlike the above, though, this "set" is not passed a window as its first argument. Also, "bind_classes" and "new_function" are only expected to act on a single JavaScript environment. The plugin's own methods of the same names make sure every JavaScript environment's methods are called.

"new_function" must also accept a third argument, indicating the return type. This (when specified) will be the name of a JavaScript function that does the type conversion. Only 'Number' is used right now. This requirement may be removed before version 1.

event2sub ($code, $elem, $url, $first_line)

This method needs to turn the event handler code in $code into an object with a "call_with" method and then return it. That object's "call_with" method will be called with the event target and the event object as its two arguments. Its return value, if defined, will be used to determine whether the event's "preventDefault" method is called.

The function's scope must contain the following objects: the global object, the document, the element's form (if there is one) and the element itself.

If the $code could not be compiled, this method must set $@ and return "undef", just like "eval".

define_setter

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.

Note: This is actually not used right now. The requirement for this may be removed some time before version 1.

PREREQUISITES

perl 5.8.4 or higher

HTML::DOM 0.032 or higher

JE 0.056 or later (if the SpiderMonkey binding even becomes stable enough it will become optional)

CSS::DOM

WWW::Scripter 0.022 or higher

URI

Hash::Util::FieldHash::Compat

LWP 5.815 or higher

BUGS

There is currently no system in place for preventing pages from different sites from communicating with each other.

To report bugs, please e-mail "mailto:bug-WWW-Scripter-Plugin-JavaScript@rt.cpan.org" in bug-WWW-Scripter-Plugin-JavaScript@rt.cpan.org.

AUTHOR & COPYRIGHT

This program is free software; you may redistribute it and/or modify it under the same terms as perl.

ACKNOWLEDGEMENTS

Thanks to Oleg G for providing a bug fix.

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 438:: You forgot a '=back' before '=head1'