Mozilla::Mechanize - Like WWW::Mechanize but using Gtk2::MozEmbed
use Mozilla::Mechanize; my $moz = Mozilla::Mechanize->new(); $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, );
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 was quickly ported from Win32::IE::Mechanize. The docs are incomplete and may still refer to the Win32 module. Some methods are unimplemented.
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.
This initializes a new browser window and sets all the properties that are passed via the %options hash(ref). Currently supported options are: quiet, onwarn, onerror.
%options
XXX: most `set_property' %options aren't currently supported. Currently supported Browser options are: height, width, visible, fullscreen. See set_property().
set_property()
XXX: this method is currently not supported. You can only set certain options through `new' (which see).
Allows you to set these supported properties:
Set the visibility of the Browser window. Setting this to 0 iconifies the window, while setting it to 1 deiconifies it. I'd be very happy if it wasn't necessary to even create a window, but I don't believe it's possible because of the way Mozilla is implemented (layout and DOM are apparently tightly coupled).
Set the height of the Browser window.
Set the width of the Browser window.
Set the visibility of the addressbar
Set the Browser window to fullscreen. Setting it false unfullscreens.
Set the resize-ability
Set the visibility of the statusbar
Set the visibility of the toolbar
Set the left coordinate of the Browser window
Set the top-coordinate of the Browser window
Close the Browser.
Return a reference to the Browser object.
Fetch $url.
$url
Reload the page.
Go back a page in the browser history.
XXX: I don't know how to implement this yet. So this always returns true for now. In fact, if a URL doesn't exist, it'll pop up a dialog. :/
Return the URI of this document (as a URI object). Note: whenever you do a submit, Mozilla appends a question mark followed by any form input (name=value pairs separated by ampersands).
Fetch the content-type of the document.
Returns the current form as a Mozilla::Mechanize::Form object.
Mozilla::Mechanize::Form
Return true if this is an HTML Document.
Fetch the title from the document.
title
Fetch the HTML of the document. This won't exactly match the HTML that's sent by the server... (The DOCTYPE/DTD will not be there, the <html> element is kind of generated so its attributes might be rearranged, and some linebreaks might be missing.)
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.
Mozilla::Mechanize::Link
Uses the $self->find_link() interface to locate a link and $self->get() it.
$self->find_link()
$self->get()
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.
url()
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.
get()
follow_link()
Note that <FRAME SRC="..."> tags are parsed out of the the HTML and treated as links so this method works with them.
<FRAME SRC="...">
You can select which link to find by passing in one or more of these key/value pairs:
text => 'string', and text_regex => qr/regex/,
text => 'string',
text_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
text
$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
text_regex
$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.
<a> foo </a>
url => 'string', and url_regex => qr/regex/,
url => 'string',
url_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 and url_abs_regex => regex
url_abs => string
url_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 and name_regex => regex
name => string
name_regex => regex
Matches the name of the link against string or regex, as appropriate.
tag => string and tag_regex => regex
tag => string
tag_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:
tag_regex
$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".
n
text*
url*
text => "download", n => 3
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/ );
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().
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()
find_all_links() with no parameters returns all links in the page.
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.
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. (XXX: not sure if this is true for Mozilla::Mechanize)
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.
alt => 'string' and alt_regex => qr/regex/,
alt => 'string'
alt_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
alt
$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
alt_regex
$moz->find_image( alt_regex => qr/download/i );
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.
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.
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>.
<img>
<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.
$self->content
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.
find_image()
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()
find_all_images() with no parameters returns all images in the page.
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.
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.
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.
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).
form_name()
form_number()
The optional $number parameter is used to distinguish between two fields with the same name. The fields are numbered from 1.
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).
select
$value
{n =
form()
Returns 1 on successfully setting the value. On failure, returns undef and calls $self-warn()> with an error message.
$self-
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).
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
@criteria
$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".
OPTION
The possible field specifier types are: "text", "password", "hidden", "textarea", "file", "image", "submit", "radio", "checkbox" and "select".
This method was ported from WWW::Mechanize.
'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.
Causes the checkbox to be unticked. Shorthand for tick( $name, $value, undef)
tick( $name, $value, undef)
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.
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.
$button
Note: inputs are searched in the order: buttons, images, submits.
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. XXX: this isn't currently working. It will select the Nth button if you assume they're gotten in the order: button, image, submit. This will presumably get fixed sometime, so I'd advise not relying on it.
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.
<INPUT type=>
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.
Submit()
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.
onSubmit
<FORM>
click_button()
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())
set_fields()
button => button
Clicks on button button (calls click())
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.
submit()
Returns true on success.
XXX: don't know how to add headers, so this is unsupported
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:
undef
$moz->add_header( Referer => undef );
Returns the number of name/value pairs added.
Removes HTTP headers from the agent's list of special headers.
NOTE: This might not work like it does with WWW::Mechanize
WWW::Mechanize
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
Returns the URL to the source of the frame with name eq $frame_name
name eq $frame_name
$self->get( $self->find_frame( $frame_name ))
Convenience method to get the Window (Mozilla::DOM::Window). (This is the `window' browser object in JavaScript.)
Convenience method to get the Document (Mozilla::DOM::Document). (This is the `document' browser object in JavaScript.)
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.
Set the user name and password to be used for a realm.
$netloc looks like hostname:port.
$netloc
hostname:port
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.
_extra_headers
$realm
$uri
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.
Sets the authentication realm to $realm for $netloc. An empty value unsets the realm for $netloc.
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.
Close the browser.
Return a list of forms. All forms are mapped onto the Mozilla::Mechanize::Form interface that mimics HTML::Form.
The links come from the following:
Note: only works within a <frameset>
Note: this must be like <iframe ...></iframe>
Return a list of images. All images are mapped onto the Mozilla::Mechanize::Image interface that mimics WWW::Mechanize::Image.
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. (Note therefore that you can only call this when you expect a new page to load.)
Centralized warning method, for diagnostics and non-fatal problems. Defaults to calling CORE::warn, but may be overridden by setting onwarn in the construcotr.
CORE::warn
onwarn
Centralized error method. Defaults to calling CORE::die, but may be overridden by setting onerror in the constructor.
CORE::die
onerror
(XXX: Not implemented.) For the moment we only support basic authentication.
Check to see if we support the property $key and return a validated value or the default value from %moz_properties.
$key
%moz_properties
(XXX: Not implemented.) Return a HTTP "Authorization: Basic xxx" header.
Send bugs directly to me or use http://rt.cpan.org/NoAuth/Bugs.html?Dist=Mozilla-Mechanize.
Mozilla::DOM, Gtk2::MozEmbed, Win32::IE::Mechanize, WWW::Mechanize
See Credits. In particular, I acknowledge having copied a lot of the code from Win32::IE::Mechanize, by Abe Timmerman.
Copyright 2005,2009 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.
To install Mozilla::Mechanize, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Mozilla::Mechanize
CPAN shell
perl -MCPAN -e shell install Mozilla::Mechanize
For more information on module installation, please visit the detailed CPAN module installation guide.