NAME
Mozilla::Mechanize - Like WWW::Mechanize but using Gtk2::MozEmbed
SYNOPSIS
use Mozilla::Mechanize;
my $moz = Mozilla::Mechanize->new( visible => 1 );
$moz->get( $url );
$moz->follow_link( text => $link_txt );
$moz->form_name( $form_name );
$moz->set_fields(
username => 'yourname',
password => 'dummy'
);
$moz->click( $btn_name );
# Or all in one go:
$moz->submit_form(
form_name => $form_name,
fields => {
username => 'yourname',
password => 'dummy',
},
button => $btn_name,
);
DESCRIPTION
This module tries to be a sort of drop-in replacement for WWW::Mechanize. It uses Mozilla's Gecko HTML-rendering engine via the modules Mozilla::DOM and Gtk2::MozEmbed.
Don't expect it to be like WWW::Mechanize in that the class is not derived from the user-agent class (like LWP).
WARNING: this has been very quickly ported from Win32::IE::Mechanize, and I don't expect it to even be working yet. The docs are incomplete and may still refer to the Win32 module. Some methods are unimplemented.
WARNING: This is a work in progress and my first priority will be to implement the WWW::Mechanize interface (which is still in full development). Wherever possible and needed I will also implement LWP::UserAgent methods that the mech inherits and will help make this thing useful.
Comment from Abe, which I echo: Thank you Andy Lester for WWW::Mechanize. I ported a lot of that code and nicked most of your documentation!
Ditto from me regarding Abe Timmerman's Win32::IE::Mechanize.
CONSTRUCTION AND PROPERTIES
Mozilla::Mechanize->new( [%options] )
This initialises a new browser window and sets all the properties that are passed via the %options
hash(ref).
XXX: %options isn't currently supported
See set_property()
for supported options.
$moz->set_property( %opt )
XXX: properties aren't currently supported
Allows you to set these supported properties:
- addressbar
-
Set the visibility of the addressbar
- fullscreen
-
Set the window of IE to fullscreen (like F11)
- resizable
-
Set the resize-ability
- statusbar
-
Set the visibility of the statusbar
- toolbar
-
Set the visibility of the toolbar
- visible
-
Set the visibility of the IE window
- height
-
Set the height of the IE window
- width
-
Set the width of the IE window
- left
-
Set the left coordinate of the IE window
- top
-
Set the top-coordinate of the IE window
$moz->close
Close the Browser.
$moz->agent
Return a reference to the Browser object.
PAGE-FETCHING METHODS
$moz->get( $url )
Fetch $url
.
$moz->reload()
Reload the page.
$moz->back()
Go back a page in the browser history.
STATUS METHODS
$moz->success
XXX: I don't know how to implement this yet. So this always returns true for now.
$moz->uri
Return the URI of this document (as a URI object).
$moz->ct
Fetch the content-type of the document.
$moz->current_form
Returns the current form as a Mozilla::Mechanize::Form
object.
$moz->is_html
Return true if this is an HTML Document.
$moz->title
Fetch the title
from the document.
CONTENT-HANDLING METHODS
$moz->content
Fetch the HTML of the document. This won't exactly match the HTML that's sent by the server... (For one thing, the DOCTYPE will not be there. Also, some linebreaks might be missing.)
LINK METHODS
$moz->links
When called in a list context, returns a list of the links found in the last fetched page. In a scalar context it returns a reference to an array with those links. The links returned are all Mozilla::Mechanize::Link
objects.
$moz->follow_link( %opt )
Uses the $self->find_link()
interface to locate a link and $self->get()
it.
$moz->find_link( [%options] )
This method finds a link in the currently fetched page. It returns a Mozilla::Mechanize::Link object which describes the link. (You'll probably be most interested in the url()
property.) If it fails to find a link it returns undef.
You can take the URL part and pass it to the get()
method. If that's your plan, you might as well use the follow_link()
method directly, since it does the get()
for you automatically.
Note that <FRAME SRC="...">
tags are parsed out of the the HTML and treated as links so this method works with them.
You can select which link to find by passing in one or more of these key/value pairs:
text => 'string',
andtext_regex => qr/regex/,
text
matches the text of the link against string, which must be an exact match. To select a link with text that is exactly "download", use$mech->find_link( text => "download" );
text_regex
matches the text of the link against regex. To select a link with text that has "download" anywhere in it, regardless of case, use$mech->find_link( text_regex => qr/download/i );
Note that the text extracted from the page's links are trimmed. For example,
<a> foo </a>
is stored as 'foo', and searching for leading or trailing spaces will fail.url => 'string',
andurl_regex => qr/regex/,
Matches the URL of the link against string or regex, as appropriate. The URL may be a relative URL, like foo/bar.html, depending on how it's coded on the page.
url_abs => string
andurl_abs_regex => regex
Matches the absolute URL of the link against string or regex, as appropriate. The URL will be an absolute URL, even if it's relative in the page.
name => string
andname_regex => regex
Matches the name of the link against string or regex, as appropriate.
tag => string
andtag_regex => regex
Matches the tag that the link came from against string or regex, as appropriate. The
tag_regex
is probably most useful to check for more than one tag, as in:$mech->find_link( tag_regex => qr/^(a|frame)$/ );
The tags and attributes looked at are defined below, at $mech-find_link() : link format>.
n => number
The n
parms can be combined with the text*
or url*
parms as a numeric modifier. For example, text => "download", n => 3
finds the 3rd link which has the exact text "download".
If n
is not specified, it defaults to 1. Therefore, if you don't specify any parms, this method defaults to finding the first link on the page.
Note that you can specify multiple text or URL parameters, which will be ANDed together. For example, to find the first link with text of "News" and with "cnn.com" in the URL, use:
$moz->find_link( text => "News", url_regex => qr/cnn\.com/ );
$moz->find_all_links( %opt )
Returns all the links on the current page that match the criteria. The method for specifying link criteria is the same as in find_link()
. Each of the links returned is in the same format as in find_link()
.
In list context, find_all_links()
returns a list of the links. Otherwise, it returns a reference to the list of links.
find_all_links()
with no parameters returns all links in the page.
IMAGE METHODS
$moz->images
Lists all the images on the current page. Each image is a Mozilla::Mechanize::Image object. In list context, returns a list of all images. In scalar context, returns an array reference of all images.
(XXX: not sure if this is true for Mozilla::Mechanize) NOTE: Although WWW::Mechanize explicitly only supports <INPUT type=submit src="..."> constructs, this is not supported by IE, it must be: <INPUT type=image src="..."> for IE to behave as expected.
$moz->find_image()
Finds an image in the current page. It returns a Mozilla::Mechanize::Image object which describes the image. If it fails to find an image it returns undef.
You can select which link to find by passing in one or more of these key/value pairs:
alt => 'string'
andalt_regex => qr/regex/,
alt
matches the ALT attribute of the image against string, which must be a n exact match. To select a image with an ALT tag that is exactly "download", use$moz->find_image( alt => "download" );
alt_regex
matches the ALT attribute of the image against a regular expression. To select an image with an ALT attribute that has "download" anywhere in it, regardless of case, use$moz->find_image( alt_regex => qr/download/i );
url => 'string',
andurl_regex => qr/regex/,
Matches the URL of the image against string or regex, as appropriate. The URL may be a relative URL, like foo/bar.html, depending on how it's coded on the page.
url_abs => string
andurl_abs_regex => regex
Matches the absolute URL of the image against string or regex, as appropriate. The URL will be an absolute URL, even if it's relative in the page.
tag => string
andtag_regex => regex
Matches the tag that the image came from against string or regex, as appropriate. The
tag_regex
is probably most useful to check for more than one tag, as in:$moz->find_image( tag_regex => qr/^(img|input)$/ );
The tags supported are
<img>
and<input>
.
If n
is not specified, it defaults to 1. Therefore, if you don't specify any parms, this method defaults to finding the first image on the page.
Note that you can specify multiple ALT or URL parameters, which will be ANDed together. For example, to find the first image with ALT text of "News" and with "cnn.com" in the URL, use:
$moz->find_image( image => "News", url_regex => qr/cnn\.com/ );
The return value is a reference to an array containing a Mozilla::Mechanize::Image object for every image in $self->content
.
$moz->find_all_images( ... )
Returns all the images on the current page that match the criteria. The method for specifying image criteria is the same as in find_image()
. Each of the images returned is a Mozilla::Mechanize::Image object.
In list context, find_all_images()
returns a list of the images. Otherwise, it returns a reference to the list of images.
find_all_images()
with no parameters returns all images in the page.
FORM METHODS
$moz->forms
Lists all the forms on the current page. Each form is an Mozilla::Mechanize::Form object. In list context, returns a list of all forms. In scalar context, returns an array reference of all forms.
$moz->form_number( $number )
Selects the numberth form on the page as the target for subsequent calls to field() and click(). Also returns the form that was selected. Emits a warning and returns undef if there is no such form. Forms are indexed from 1, so the first form is number 1, not zero.
$moz->form_name( $name )
Selects a form by name. If there is more than one form on the page with that name, then the first one is used, and a warning is generated. Also returns the form itself, or undef if it is not found.
$moz->field( $name[, $value[, $index]] )
$moz->field( $name, \@values[, $number ] )
Given the name of a field, set its value to the value specified. This applies to the current form (as set by the form_name()
or form_number()
method or defaulting to the first form on the page).
The optional $index parameter is used to distinguish between two fields with the same name. The fields are numbered from 1.
$moz->select( $name, $value )
$moz->select( $name, \@values )
Given the name of a select
field, set its value to the value specified. If the field is not <select multiple> and the $value
is an array, only the first value will be set. Passing $value
as a hash with an n
key selects an item by number (e.g. {n =
3> or {n =
[2,4]}>). The numbering starts at 1. This applies to the current form (as set by the form()
method or defaulting to the first form on the page).
Returns 1 on successfully setting the value. On failure, returns undef and calls $self-
warn()> with an error message.
$moz->set_fields( %arguments )
This method sets multiple fields of a form. It takes a list of field name and value pairs. If there is more than one field with the same name, the first one found is set. If you want to select which of the duplicate field to set, use a value which is an anonymous array which has the field value and its number as the 2 elements.
# set the second foo field
$moz->set_fields( $name => [ 'foo', 2 ] ) ;
The fields are numbered from 1.
This applies to the current form (as set by the form_name()
or form_number()
method or defaulting to the first form on the page).
$moz->set_visible( @criteria )
This method sets fields of a form without having to know their names. So if you have a login screen that wants a username and password, you do not have to fetch the form and inspect the source to see what the field names are; you can just say
$moz->set_visible( $username, $password ) ;
and the first and second fields will be set accordingly. The method is called set_visible because it acts only on visible fields; hidden form inputs are not considered. The order of the fields is the order in which they appear in the HTML source which is nearly always the order anyone viewing the page would think they are in, but some creative work with tables could change that; caveat user.
Each element in @criteria
is either a field value or a field specifier. A field value is a scalar. A field specifier allows you to specify the type of input field you want to set and is denoted with an arrayref containing two elements. So you could specify the first radio button with
$moz->set_visible( [ radio => "KCRW" ] ) ;
Field values and specifiers can be intermixed, hence
$moz->set_visible( "fred", "secret", [ select => "Checking" ] ) ;
would set the first two fields to "fred" and "secret", and the next OPTION
menu field to "Checking".
The possible field specifier types are: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" and "select".
This method was ported from WWW::Mechanize.
$moz->tick( $name, $value[, $set] )
'Ticks' the first checkbox that has both the name and value assoicated with it on the current form. Dies if there is no named check box for that value. Passing in a false value as the third optional argument will cause the checkbox to be unticked.
$moz->untick( $name, $value )
Causes the checkbox to be unticked. Shorthand for tick( $name, $value, undef)
$mech->value( $name, $number )
Given the name of a field, return its value. This applies to the current form (as set by the form()
method or defaulting to the first form on the page).
The option $number parameter is used to distinguish between two fields with the same name. The fields are numbered from 1.
If the field is of type file (file upload field), the value is always cleared to prevent remote sites from downloading your local files. To upload a file, specify its file name explicitly.
$moz->click( $button )
Call the click method on an INPUT object with the name $button
Has the effect of clicking a button on a form. The first argument is the name of the button to be clicked. I have not found a way to set the (x,y) coordinates of the click in IE.
$moz->click_button( %args )
Has the effect of clicking a button on a form by specifying its name, value, or index. Its arguments are a list of key/value pairs. Only one of name, number, or value must be specified.
name => name
Clicks the button named name.
number => n
Clicks the nth button in the form.
value => value
Clicks the button with the value value.
NOTE: Unlike WWW::Mechanize, Mozilla::Mechanize takes all buttonish types of <INPUT type=>
into account: button, image and submit.
$moz->submit( )
Submits the page, without specifying a button to click. Actually, no button is clicked at all.
This will call the Submit()
method of the currently selected form.
NOTE: It looks like this method does not call the onSubmit
handler specified in the <FORM>
-tag, that only seems to work if you call the click_button()
method with submit button.
$moz->submit_form( %opt )
This method lets you select a form from the previously fetched page, fill in its fields, and submit it. It combines the form_number/form_name, set_fields and click methods into one higher level call. Its arguments are a list of key/value pairs, all of which are optional.
form_number => n
Selects the nth form (calls
form_number()
). If this parm is not specified, the currently-selected form is used.form_name => name
Selects the form named name (calls
form_name()
)fields => fields
Sets the field values from the fields hashref (calls
set_fields()
)button => button
Clicks on button button (calls
click()
)button => { value => value }
When you specify a hash_ref for button it calls
click_button()
If no form is selected, the first form found is used.
If button is not passed, then the submit()
method is used instead.
Returns true on success.
MISCELANEOUS METHODS
XXX: don't know how to add headers, so this is unsupported
$moz->add_header( name => $value [, name => $value... ] )
Sets HTTP headers for the agent to add or remove from the HTTP request.
$moz->add_header( Encoding => 'text/klingon' );
If a value is undef
, then that header will be removed from any future requests. For example, to never send a Referer header:
$moz->add_header( Referer => undef );
Returns the number of name/value pairs added.
$moz->delete_header( name [, name ... ] )
XXX: don't know how to add headers, so this is unsupported
Removes HTTP headers from the agent's list of special headers.
NOTE: This might not work like it does with WWW::Mechanize
$moz->quiet( [$state] )
Allows you to suppress warnings to the screen.
$a->quiet(0); # turns on warnings (the default)
$a->quiet(1); # turns off warnings
$a->quiet(); # returns the current quietness status
$moz->find_frame( $frame_name )
Returns the URL to the source of the frame with name eq $frame_name
$moz->load_frame( $frame_name )
$self->get( $self->find_frame( $frame_name ))
DOM CONVENIENCE METHODS
$moz->get_window;
Convenience method to get the Window (Mozilla::DOM::Window). (This is the `window' browser object in JavaScript.)
$moz->get_document;
Convenience method to get the Document (Mozilla::DOM::Document). (This is the `document' browser object in JavaScript.)
$moz->get_document_element;
Convenience method to get the document element (Mozilla::DOM::Element). (Actually this is a Mozilla::DOM::HTMLHtmlElement, i.e. <html>, if you want to QueryInterface to it). This is useful for calling GetElementsByTagName.
LWP COMPATABILITY METHODS
$moz->credentials( $netloc, $realm, $uid, $pass )
XXX: don't know how to add headers, so this is unsupported
Set the user name and password to be used for a realm.
$netloc
looks like hostname:port
.
$moz->get_basic_credentials( $realm, $uri )
XXX: don't know how to add headers, so this is unsupported
This is called by _extra_headers
to retrieve credentials for documents protected by Basic Authentication. The arguments passed in are the $realm
and the $uri
requested.
The method should return a username and password. It should return an empty list to abort the authentication resolution attempt.
The base implementation simply checks a set of pre-stored member variables, set up with the credentials() method.
$moz->set_realm( $netloc, $realm );
XXX: don't know how to add headers, so this is unsupported
Sets the authentication realm to $realm
for $netloc
. An empty value unsets the realm for $netloc
.
$netloc
looks like hostname:port
.
As I have not found a way to access response-headers, I cannot find out the authentication realm (if any) and automagically set the right headers. You will have to do some bookkeeping for now.
INTERNAL-ONLY METHODS
DESTROY
Close the browser.
$moz->_extract_forms()
Return a list of forms using the $moz->Document->forms
interface. All forms are mapped onto the Mozilla::Mechanize::Form interface that mimics HTML::Form.
$self->_extract_links()
The links come from the following:
$moz->_extract_images()
Return a list of images using the $moz->Document->images
interface. All images are mapped onto the Mozilla::Mechanize::Image interface that mimics WWW::Mechanize::Images.
$self->_wait_while_busy()
This adds a "single-shot" idle callback that does Gtk2->main_quit, then does Gtk2->main. The result is that whenever the UI becomes idle it will exit the main loop. Thanks to muppet for the idea. This is repeated until the net_stop event fires, indicating that the new page has finished loading.
warn( @messages )
Centralized warning method, for diagnostics and non-fatal problems. Defaults to calling CORE::warn
, but may be overridden by setting onwarn
in the construcotr.
die( @messages )
Centralized error method. Defaults to calling CORE::die
, but may be overridden by setting onerror
in the constructor.
$self->_extra_headers( )
For the moment we only support basic authentication.
INTERNAL ONLY NON-METHODS
__prop_value( $key[, $value] )
Check to see if we support the property $key
and return a validated value or the default value from %moz_properties
.
__authorization_basic( $user, $pass )
Return a HTTP "Authorization: Basic xxx" header.
BUGS
Send bugs directly to me or use http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mozilla-Mechanize.
SEE ALSO
Mozilla::DOM, Gtk2::MozEmbed, Win32::IE::Mechanize, WWW::Mechanize
CREDITS
See Credits. In particular, I acknowledge having copied a lot of the code from Win32::IE::Mechanize, by Abe Timmerman.
COPYRIGHT AND LICENSE
Copyright 2005, Scott Lanning <slanning@cpan.org>. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.