The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Win32-IE-Mechanize-0.009_17
++
/ Win32::IE::Mechanize

NAME

Win32::IE::Mechanize - Like "the mech" but with IE as user-agent

SYNOPSIS

    use Win32::IE::Mechanize;

    my $ie = Win32::IE::Mechanize->new( visible => 1 );

    $ie->get( $url );

    $ie->follow_link( text => $link_txt );

    $ie->form_name( $form_name );
    $ie->set_fields(
        username => 'yourname',
        password => 'dummy'
    );
    $ie->click( $btn_name );

    # Or all in one go:
    $ie->submit_form(
        form_name => $form_name,
        fields    => {
            username => 'yourname',
            password => 'dummy',
        },
        # tick the bar value and untick the baz value
        # of the foo checkboxes
        tick      => {
            foo => { bar => 1, baz => 0 },
        },
        button    => $btn_name,
    );

Now also tries to support Basic-Authentication like LWP::UserAgent

    use Win32::IE::Mechanize;

    my $ie = Win32::IE::Mechanize->new( visible => 1 );

    $ie->credentials( 'pause.perl.org:443', 'PAUSE', 'abeltje', '********' );
    $ie->get( 'https://pause.perl.org/pause/authenquery' );

DESCRIPTION

This module tries to be a sort of drop-in replacement for WWW::Mechanize. It uses Win32::OLE to manipulate the Internet Explorer.

Don't expect it to be like the mech in that the class is not derived from the user-agent class (like LWP).

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). Where ever possible and needed I will also implement LWP::UserAgent methods that the mech inherits and will help make this thing useful.

Thank you Andy Lester for WWW::Mechanize. I ported a lot of that code and nicked most of your documentation!

For more information on the OLE2 interface for InternetExplorer, google for InternetExplorer.Application+msdn.

CONSTRUCTION AND PROPERTIES

Win32::IE::Mechanize->new( [%options] )

This initialises a new InternetExplorer.Application through Win32::OLE and sets all the properties that are passed via the %options hash(ref).

See set_property() for supported options.

$ie->set_property( %opt )

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

$ie->close

Close the InternetExplorer instance.

$ie->open()

Create a InternetExplorer.Application OLE object, set all its properties and enable the DWebBrowserEvents2 event-handle.

$ie->agent

Return a reference to the InternetExplorer automation object.

PAGE-FETCHING METHODS

$ie->get( $url )

Use the Navigate method of the IE object to get the $url and wait for it to be loaded.

$ie->reload()

Use the Refresh method of the IE object and wait for it to be loaded.

$ie->back()

Use the GoBack method of the IE object and wait for it to be loaded.

STATUS METHODS

$ie->success

Return true for ReadyState >= 2;

$ie->uri

Return the URI of this document (as an URI object).

$ie->ct

Fetch the mimeType from the $ie->Document. IE does not return the MIME type in a way we expect.

$ie->current_form

Returns the current form as an Win32::IE::Form object.

$ie->is_html

Return true if this is an HTML Document.

$ie->title

Fetch the title from the $ie->Document.

CONTENT-HANDLING METHODS

$ie->content

Fetch the outerHTML from the $ie->Document->documentElement.

I have found no way to get to the exact contents of the document. This is basically the interpretation of IE of what the HTML looks like and beware all tags are upcased :(

LINK METHODS

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 Win32::IE::Link objects.

$ie->follow_link( %opt )

Uses the $self->find_link() interface to locate a link and $self->get() it.

$ie->find_link( [%options] )

This method finds a link in the currently fetched page. It returns a Win32::IE::Link object which describes the link. (You will 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 is 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', and 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

        $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 pages links are trimmed. For example, <a> foo </a> is stored as 'foo', and searching for leading or trailing spaces will fail.

  • url => 'string', and 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 is coded on the page.

  • url_abs => string and 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 is relative in the page.

  • name => string and name_regex => regex

    Matches the name of the link against string or regex, as appropriate.

  • tag => string and 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:

        $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 do not 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:

    $ie->find_link( text => "News", url_regex => qr/cnn\.com/ );

$ie->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

$ie->images

Lists all the images on the current page. Each image is a Win32::IE::Image object. In list context, returns a list of all images. In scalar context, returns an array reference of all images.

NOTE: Althoug 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.

$ie->find_image()

Finds an image in the current page. It returns a Win32::IE::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' and alt_regex => qr/regex/,

    alt matches the ALT attribute of the image against string, which must be an exact match. To select a image with an ALT tag that is exactly "download", use

        $ie->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

        $ie->find_image( alt_regex => qr/download/i );

  • url => 'string', and url_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 and url_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 and tag_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:

        $ie->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 do not 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:

    $ie->find_image( image => "News", url_regex => qr/cnn\.com/ );

The return value is a reference to an array containing a Win32::IE::Image object for every image in $self->content.

$ie->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 Win32::IE::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

$ie->forms

Lists all the forms on the current page. Each form is an Win32::IE::Form object. In list context, returns a list of all forms. In scalar context, returns an array reference of all forms.

$ie->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.

$ie->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.

$ie->field( $name[, $value[, $index]] )

$ie->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.

$ie->select( $name, $value )

$ie->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.

$ie->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 fields 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
        $ie->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).

$ie->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

    $ie->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

    $ie->set_visible( [ radio => "KCRW" ] ) ;

Field values and specifiers can be intermixed, hence

    $ie->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.

$ie->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.

$ie->untick( $name, $value )

Causes the checkbox to be unticked. Shorthand for tick( $name, $value, undef)

$ie->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.

$ie->click( $button[, $nowait] )

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.

$ie->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, Win32::IE::Mechanize takes all buttonish types of <INPUT type=> into accout: button, image and submit.

NOTE: Because buttons can be purely scripted in IE, you may need to specify an extra argument nowait => 1. This tels Win32::IE::Mechanize not to hook into the eventloop in order to prevent "hanging".

$ie->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.

$ie->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())

  • tick => checkboxes

    Ticks and unticks the values specified for each checkboxgroup in the hashref checkboxes.

        tick => { foo => { bar => 1, baz => 0 } }

    This option is not in WWW::Mechanize.

  • 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

$ie->add_header( name => $value [, name => $value... ] )

Sets HTTP headers for the agent to add or remove from the HTTP request.

    $ie->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:

    $ie->add_header( Referer => undef );

Returns the number of name/value pairs added.

$ie->delete_header( name [, name ... ] )

Removes HTTP headers from the agents list of special headers.

NOTE: This might not work like it does with WWW::Mechanize

$ie->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

$ie->find_frame( $frame_name )

Returns the URL to the source of the frame with name eq $frame_name.

NOTEThis method is depricate. Please use find_link()!

$ie->load_frame( $frame_name )

$self->get( $self->find_frame( $frame_name ))

NOTEThis method is depricated. Please use follow_link()!

LWP COMPATABILITY METHODS

$ie->credentials( $netloc, $realm, $uid, $pass )

Set the user name and password to be used for a realm.

$netloc looks like hostname:port.

$ie->get_basic_credentials( $realm, $uri )

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.

$ie->set_realm( $netloc, $realm );

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

We need to close the IE-instance, at least when not visible!

$ie->_extract_forms()

Return a list of forms using the $ie->Document->forms interface. All forms are mapped onto the Win32::IE::Form interface that mimics HTML::Form.

$self->_extract_links()

The links come from the following:

"<A HREF=...>"
"<AREA HREF=...>"
"<FRAME SRC=...>"
"<IFRAME SRC=...>"

$ie->_extract_images()

Return a list of images using the $ie->Document->images interface. All images are mapped onto the Win32::IE::Image interface that mimics WWW::Mechanize::Images.

$self->_wait_while_busy( $nowait )

Start hooking into the browser events.

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 %ie_properties.

__authorization_basic( $user, $pass )

Return a HTTP "Authorization: Basic xxx" header.

ACCESS TO SUBPACKAGES

These subs just supply an interface to the Win32::IE::* sub objects.

__new_form( $form_obj )

Retuns a new Win32::IE::Form. NOT a method!

__new_input( $input_obj )

Retuns a new Win32::IE::Input. NOT a method!

__new_link( $link_obj )

Retuns a new Win32::IE::Link. NOT a method!

__new_image( $image_obj )

Retuns a new Win32::IE::Image. NOT a method!

CAVEATS

The InternetExplorer automation object does not provide an interface to the options menus. This means that you will need to set all options needed for this automation before you start. This means that you may need to set your security settings to a low and possibly unsafe level.

The InternetExplorer automation object does not provide an interface to "popup windows" generated by security settings or JScript contained in the page.

The InternetExplorer automation object does not provide an interface to the content of frames from the toplevel document. This means that you need to load the frame explicitly (using the follow_link() method).

The basic authentication support is quite wonky and will only work with the get() method.

BUGS

Yes, there are bugs. The test-suite doesn't fully cover the codebase.

frames

Some reports have come in regarding frames. So far nobody has been able to provide me with a testcase, so I can't realy "fix" those.

forks

Gabor Szabo reported problems with forking and use Win32::IE::Mechanize. His workaround is to change the "global" use Win32::IE::Mechanize with localized require Win32::IE::Mechanize in the child's code.

encodings

Gabor Szabo reported problems with pages that use non-standard encoding. In his case it turns out that somewhere along the line, the right-to-left hebrew contents are lost.

Please report bugs using http://rt.cpan.org

COPYRIGHT AND LICENSE

Copyright MMIV, Abe Timmerman <abeltje@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.