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',
    },
    button    => $btn_name,
);

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.

Page-fetching methods

$ie->get( $url )

Navigate to the $url and wait for it to be loaded.

$ie->reload()

Use the Refresh method of the IE object.

$ie->back()

Use the GoBack method of the IE object.

Link-following methods

$ie->follow_link( %opt )

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

Form field filling methods

$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]] )

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

Form submission methods

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

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

$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())
button => button

Clicks on button button (calls click())

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.

Status methods

$ie->success

Return true for ReadyState >= 2;

$ie->uri

Return the URI of this document.

$ie->ct

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

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

$ie->forms

When called in a list context, returns a list of the forms found in the last fetched page. In a scalar context, returns a reference to an array with those forms. The forms returned are all Win32::IE::Form objects.

$ie->current_form

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

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

$ie->is_html

Return true if this is an HTML Document.

$ie->title

Fetch the title from the $ie->Document.

Content-handling methods

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

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
```
$a->find_link( text => "download" );
```
text_regex => 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
```
$a->find_link( text_regex => qr/download/i );
```
url => string

Matches the URL of the link against string, which must be an exact match. This is similar to the text parm.
url_regex => regex

Matches the URL of the link against regex. This is similar to the text_regex parm.
n => number

Matches against the nth link.

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:

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

$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

$ie->load_frame( $frame_name )

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

Internal-only methods

$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=...>"

$self->_wait_while_busy()

This is still a mess, but we need to poll IE to see if it is ready loading and displaying the page, before we can move on.

$self->warn( $msg )

Uses Carp::carp as that seems more useful.

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.

__setup_matchfunc( %opt )

Stolen from WWW::Mechanize, but adjusted for the use in this module.

PACKAGE

Win32::IE::Form - Like <HTML::Form> but for the IE form object.

METHODS

Win32::IE::Form->new( $form_obj );: Initialize a new object, it is only a ref to a scalar, the rest is done through the methods.
$form->method( [$new_method] ): Get/Set the method used to submit the from (i.e. GET or POST).
$form->action( [$new_action] ): Get/Set the action for submitting the form.
$form->enctype( [$new_enctype] ): Get/Set the enctype of the form.
$form->attr( $name[, $new_value] ): Get/Set any of the attributes from the FORM-tag.
$form->name(): Return the name of this form.
$form->inputs(): Returns a list of Win32::IE::Input objects. In scalar context it will return the number of inputs.
$form->find_input( $name[, $type[, $index]] ): See HTML::Form::find_input
$form->value( $name[, $new_value] ): Get/Set the value for the input-contol with spcified name.
$form->submit(): Submit this form.

PACKAGE

Win32::IE::Input - A small class to interface with the IE input objects.

METHODS

Win32::IE::Input->new( $ie_input ): Initialize a new object (like Win32::IE::Form).
$input->name: Return the input-control name.
$input->type: Return the type of the input control.
$input->value( [$value] ): Get/Set the value of the input control.

PACKAGE

Win32::IE::Link - A bit like WWW::Mechanize::Link

METHODS

Win32::IE::Link->new( $element )

$element is Win32::OLE object with a tagName() of IFRAME, FRAME, <AREA> or <A>.

Note: Although it supports the same methods as WWW::Mechanize::Link it is a completely different implementation.

COPYRIGHT

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.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 810:: Can't have a 0 in =over 0

To install Win32::IE::Mechanize, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Win32::IE::Mechanize

CPAN shell

perl -MCPAN -e shell
install Win32::IE::Mechanize

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Construction and properties

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

$ie->set_property( %opt )

$ie->close

Page-fetching methods

$ie->get( $url )

$ie->reload()

$ie->back()

Link-following methods

$ie->follow_link( %opt )

Form field filling methods

$ie->form_number( $number )

$ie->form_name( $name )

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

$ie->set_fields( %arguments )

$ie->tick( $name, $value[, $set] )

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

Form submission methods

$ie->click( $button )

$ie->submit( )

$ie->submit_form( %opt )

Status methods

$ie->success

$ie->uri

$ie->ct

$ie->content

$ie->forms

$ie->current_form

$ie->links

$ie->is_html

$ie->title

Content-handling methods

$ie->find_link( [%options] )

$ie->find_all_links( %opt )

$ie->quiet( [$state] )

$ie->find_frame( $frame_name )

$ie->load_frame( $frame_name )

Internal-only methods

$ie->_extract_forms()

$self->_extract_links()

$self->_wait_while_busy()

$self->warn( $msg )

Internal only non-methods

__prop_value( $key[, $value] )

__setup_matchfunc( %opt )

PACKAGE

METHODS

PACKAGE

METHODS

PACKAGE

METHODS

COPYRIGHT

Module Install Instructions