# NAME

WWW::Mechanize::Firefox - use Firefox as if it were WWW::Mechanize

# SYNOPSIS

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new();
  $mech->get('http://google.com');

  $mech->eval_in_page('alert("Hello Firefox")');
  my $png = $mech->content_as_png();

This module will let you automate Firefox through the
Mozrepl plugin. You you need to have installed
that plugin in your Firefox.

For more examples see [WWW::Mechanize::Firefox::Examples](http://search.cpan.org/search?mode=module&query=WWW::Mechanize::Firefox::Examples).

# METHODS

## C<< $mech->new( %args ) >>

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new();

Creates a new instance and connects it to Firefox.

Note that Firefox must have the `mozrepl`
extension installed and enabled.

The following options are recognized:

- * 

`tab` - regex for the title of the tab to reuse. If no matching tab is
found, the constructor dies.

If you pass in the string `current`, the currently
active tab will be used instead.

- *

`create` - will create a new tab if no existing tab matching
the criteria given in `tab` can be found.

- * 

`launch` - name of the program to launch if we can't connect to it on
the first try.

- *

`frames` - an array reference of ids of subframes to include when 
searching for elements on a page.

If you want to always search through all frames, just pass `1`. This
is the default.

To prevent searching through frames, pass

          frames => 0

To whitelist frames to be searched, pass the list
of frame selectors:

          frames => ['#content_frame']

- * 

`log` - array reference to log levels, passed through to [MozRepl::RemoteObject](http://search.cpan.org/search?mode=module&query=MozRepl::RemoteObject)

- *

`bufsize` - [Net::Telnet](http://search.cpan.org/search?mode=module&query=Net::Telnet) buffer size, if the default of 1MB is not enough

- * 

`events` - the set of default Javascript events to listen for while
waiting for a reply

- * 

`repl` - a premade [MozRepl::RemoteObject](http://search.cpan.org/search?mode=module&query=MozRepl::RemoteObject) instance or a connection string
suitable for initializing one.

- * 

`pre_events` - the events that are sent to an input field before its
value is changed. By default this is `[focus]`.

- * 

`post_events` - the events that are sent to an input field after its
value is changed. By default this is `[blur, change]`.

# JAVASCRIPT METHODS

## C<< $mech->allow( %options ) >>

Enables or disables browser features for the current tab.
The following options are recognized:

- * 

`plugins` 	 - Whether to allow plugin execution.

- * 

`javascript` 	 - Whether to allow Javascript execution.

- * 

`metaredirects` - Attribute stating if refresh based redirects can be allowed.

- * 

`frames`, `subframes` 	 - Attribute stating if it should allow subframes (framesets/iframes) or not.

- * 

`images` 	 - Attribute stating whether or not images should be loaded.

Options not listed remain unchanged.

### Disable Javascript

  $mech->allow( javascript => 0 );

## C<< $mech->js_errors() >>

  print $_->{message}
      for $mech->js_errors();

An interface to the Javascript Error Console

Returns the list of errors in the JEC

Maybe this should be called `js_messages` or
`js_console_messages` instead.

## C<< $mech->clear_js_errors >>

    $mech->clear_js_errors();

Clears all Javascript messages from the console

## C<< $mech->eval_in_page( $str [, $env [, $document]] ) >>

## C<< $mech->eval( $str [, $env [, $document]] ) >>

  my ($value, $type) = $mech->eval( '2+2' );

Evaluates the given Javascript fragment in the
context of the web page.
Returns a pair of value and Javascript type.

This allows access to variables and functions declared
"globally" on the web page.

The returned result needs to be treated with 
extreme care because
it might lead to Javascript execution in the context of
your application instead of the context of the webpage.
This should be evident for functions and complex data
structures like objects. When working with results from
untrusted sources, you can only safely use simple
types like `string`.

If you want to modify the environment the code is run under,
pass in a hash reference as the second parameter. All keys
will be inserted into the `this` object as well as
`this.window`. Also, complex data structures are only
supported if they contain no objects.
If you need finer control, you'll have to
write the Javascript yourself.

This method is special to WWW::Mechanize::Firefox.

Also, using this method opens a potential __security risk__ as
the returned values can be objects and using these objects
can execute malicious code in the context of the Firefox application.

## C<< $mech->unsafe_page_property_access( ELEMENT ) >>

Allows you unsafe access to properties of the current page. Using
such properties is an incredibly bad idea.

This is why the function `die`s. If you really want to use
this function, edit the source code.

# UI METHODS

## C<< $mech->addTab( %options ) >>

Creates a new tab and returns it.
The tab will be automatically closed upon program exit.

If you want the tab to remain open, pass a false value to the the ` autoclose `
option.

The recognized options are:

- *

`repl` - the repl to use. By default it will use `$mech->repl`.

- *

`autoclose` - whether to automatically close the tab at program exit. Default is
to close the tab.

## C<< $mech->closeTab( $tab [,$repl] ) >>

Close the given tab.

## C<< $mech->tab >>

Gets the object that represents the Firefox tab used by WWW::Mechanize::Firefox.

This method is special to WWW::Mechanize::Firefox.

## C<< $mech->autodie( [$state] ) >>

  $mech->autodie(0);

Accessor to get/set whether warnings become fatal.

## C<< $mech->progress_listener( $source, %callbacks ) >>

    my $eventlistener = progress_listener(
        $browser,
        onLocationChange => \&onLocationChange,
    );

Sets up the callbacks for the `nsIWebProgressListener` interface
to be the Perl subroutines you pass in.

Returns a handle. Once the handle gets released, all callbacks will
get stopped. Also, all Perl callbacks will get deregistered from the
Javascript bridge, so make sure not to use the same callback
in different progress listeners at the same time.

## C<< $mech->repl >>

  my ($value,$type) = $mech->repl->expr('2+2');

Gets the [MozRepl::RemoteObject](http://search.cpan.org/search?mode=module&query=MozRepl::RemoteObject) instance that is used.

This method is special to WWW::Mechanize::Firefox.

## C<< $mech->events >>

  $mech->events( ['load'] );

Sets or gets the set of Javascript events that WWW::Mechanize::Firefox
will wait for after requesting a new page. Returns an array reference.

This method is special to WWW::Mechanize::Firefox.

## C<< $mech->cookies >>

  my $cookie_jar = $mech->cookies();

Returns a [HTTP::Cookies](http://search.cpan.org/search?mode=module&query=HTTP::Cookies) object that was initialized
from the live Firefox instance.

__Note:__ `->set_cookie` is not yet implemented,
as is saving the cookie jar.

## C<< $mech->highlight_node( @nodes ) >>

    my @links = $mech->selector('a');
    $mech->highlight_node(@links);

Convenience method that marks all nodes in the arguments
with

  background: red;
  border: solid black 1px;
  display: block; /* if the element was display: none before */

This is convenient if you need visual verification that you've
got the right nodes.

There currently is no way to restore the nodes to their original
visual state except reloading the page.

# NAVIGATION METHODS

## C<< $mech->get( $url, %options ) >>

  $mech->get( $url, ':content_file' => $tempfile );

Retrieves the URL `URL` into the tab.

It returns a faked [HTTP::Response](http://search.cpan.org/search?mode=module&query=HTTP::Response) object for interface compatibility
with [WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize).

## C<< $mech->get_local( $filename , %options ) >>

  $mech->get_local('test.html');

Shorthand method to construct the appropriate
`file://` URI and load it into Firefox. Relative
paths will be interpreted as relative to `$0`.

This method is special to WWW::Mechanize::Firefox but could
also exist in WWW::Mechanize through a plugin.

## C<< $mech->synchronize( $event, $callback ) >>

Wraps a synchronization semaphore around the callback
and waits until the event `$event` fires on the browser.
If you want to wait for one of multiple events to occur,
pass an array reference as the first parameter.

Usually, you want to use it like this:

  my $l = $mech->xpath('//a[@onclick]', single => 1);
  $mech->synchronize('DOMFrameContentLoaded', sub {
      $l->__click()
  });

It is necessary to synchronize with the browser whenever
a click performs an action that takes longer and
fires an event on the browser object.

The `DOMFrameContentLoaded` event is fired by Firefox when
the whole DOM and all `iframe`s have been loaded.
If your document doesn't have frames, use the `DOMContentLoaded`
event instead.

If you leave out `$event`, the value of `->events()` will
be used instead.



## C<< $mech->res >> / C<< $mech->response >>

    my $response = $mech->response();

Returns the current response as a [HTTP::Response](http://search.cpan.org/search?mode=module&query=HTTP::Response) object.

## C<< $mech->success >>

    $mech->get('http://google.com');
    print "Yay"
        if $mech->success();

Returns a boolean telling whether the last request was successful.
If there hasn't been an operation yet, returns false.

This is a convenience function that wraps `$mech->res->is_success`.

## C<< $mech->status >>

    $mech->get('http://google.com');
    print $mech->status();
    # 200

Returns the HTTP status code of the response.
This is a 3-digit number like 200 for OK, 404 for not found, and so on.

## C<< $mech->reload( [$bypass_cache] ) >>

    $mech->reload();

Reloads the current page. If `$bypass_cache`
is a true value, the browser is not allowed to
use a cached page. This is the difference between
pressing `F5` (cached) and `shift-F5` (uncached).

Returns the (new) response.

## C<< $mech->back >>

    $mech->back();

Goes one page back in the page history.

Returns the (new) response.

## C<< $mech->forward >>

    $mech->forward();

Goes one page back in the page history.

Returns the (new) response.

## C<< $mech->uri >>

    print "We are at " . $mech->uri;

Returns the current document URI.

# CONTENT METHODS

## C<< $mech->document >>

Returns the DOM document object.

This is WWW::Mechanize::Firefox specific.

## C<< $mech->docshell >>

    my $ds = $mech->docshell;

Returns the `docShell` Javascript object.

This is WWW::Mechanize::Firefox specific.

## C<< $mech->content >>

  print $mech->content;

Returns the current content of the tab as a scalar. The content
does not decoded according to the encoding. It is returned
as raw octets.

This is likely not binary-safe.

It also currently only works for HTML pages.

## C<< $mech->content_utf8 >>

    print $mech->content_utf8;

This always returns the content as a Unicode string. It tries
to decode the raw content according to its input encoding.

This method is very experimental.

Don't use this method when trying to get at binary data.

## C<< $mech->content_encoding >>

    print "The content is encoded as ", $mech->content_encoding;

Returns the encoding that the content is in. This can be used
to convert the content to UTF-8.

## C<< $mech->update_html( $html ) >>

  $mech->update_html($html);

Writes `$html` into the current document. This is mostly
implemented as a convenience method for [HTML::Display::MozRepl](http://search.cpan.org/search?mode=module&query=HTML::Display::MozRepl).

## C<< $mech->set_tab_content $tab, $html [,$repl] >>

This is a more general method that allows you to replace
the HTML of an arbitrary tab, and not only the tab that
WWW::Mechanize::Firefox is associated with.

## C<< $mech->save_content( $localname [, $resource_directory] [, %options ] ) >>

  $mech->get('http://google.com');
  $mech->save_content('google search page','google search page files');

Saves the given URL to the given filename. The URL will be
fetched from the cache if possible, avoiding unnecessary network
traffic.

If `$resource_directory` is given, the whole page will be saved.
All CSS, subframes and images
will be saved into that directory, while the page HTML itself will
still be saved in the file pointed to by `$localname`.

Returns a `nsIWebBrowserPersist` object through which you can cancel the
download by calling its `->cancelSave` method. Also, you can poll
the download status through the `->{currentState}` property.

If you are interested in the intermediate download progress, create
a ProgressListener through `$mech->progress_listener`
and pass it in the `progress` option.

The download will
continue in the background. It will not show up in the
Download Manager.

## C<< $mech->save_url( $url, $localname, [%options] ) >>

  $mech->save_url('http://google.com','google_index.html');

Saves the given URL to the given filename. The URL will be
fetched from the cache if possible, avoiding unnecessary network
traffic.

Returns a `nsIWebBrowserPersist` object through which you can cancel the
download by calling its `->cancelSave` method. Also, you can poll
the download status through the `->{currentState}` property.

If you are interested in the intermediate download progress, create
a ProgressListener through `$mech->progress_listener`
and pass it in the `progress` option.

The download will
continue in the background. It will also not show up in the
Download Manager.

## C<< $mech->base >>

  print $mech->base;

Returns the URL base for the current page.

The base is either specified through a `base`
tag or is the current URL.

This method is specific to WWW::Mechanize::Firefox

## C<< $mech->content_type >>

## C<< $mech->ct >>

  print $mech->content_type;

Returns the content type of the currently loaded document

## C<< $mech->is_html() >>

  print $mech->is_html();

Returns true/false on whether our content is HTML, according to the
HTTP headers.

## C<< $mech->title >>

  print "We are on page " . $mech->title;

Returns the current document title.

# EXTRACTION METHODS

## C<< $mech->links >>

  print $_->text . " -> " . $_->url . "\n"
      for $mech->links;

Returns all links in the document as [WWW::Mechanize::Link](http://search.cpan.org/search?mode=module&query=WWW::Mechanize::Link) objects.

Currently accepts no parameters. See `->xpath`
or `->selector` when you want more control.

## C<< $mech->find_link_dom( %options ) >>

  print $_->{innerHTML} . "\n"
      for $mech->find_link_dom( text_contains => 'CPAN' );

A method to find links, like [WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize)'s
`->find_links` method. This method returns DOM objects from
Firefox instead of WWW::Mechanize::Link objects.

Note that Firefox
might have reordered the links or frame links in the document
so the absolute numbers passed via `n`
might not be the same between
[WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize) and [WWW::Mechanize::Firefox](http://search.cpan.org/search?mode=module&query=WWW::Mechanize::Firefox).

Returns the DOM object as [MozRepl::RemoteObject](http://search.cpan.org/search?mode=module&query=MozRepl::RemoteObject)::Instance.

The supported options are:

- *

`text` and `text_contains` and `text_regex`

Match the text of the link as a complete string, substring or regular expression.

Matching as a complete string or substring is a bit faster, as it is
done in the XPath engine of Firefox.

- *

`id` and `id_contains` and `id_regex`

Matches the `id` attribute of the link completely or as part

- *

`name` and `name_contains` and `name_regex`

Matches the `name` attribute of the link

- *

`url` and `url_regex`

Matches the URL attribute of the link (`href`, `src` or `content`).

- *

`class` - the `class` attribute of the link

- *

`n` - the (1-based) index. Defaults to returning the first link.

- *

`single` - If true, ensure that only one element is found. Otherwise croak
or carp, depending on the `autodie` parameter.

- *

`one` - If true, ensure that at least one element is found. Otherwise croak
or carp, depending on the `autodie` parameter.

The method `croak`s if no link is found. If the `single` option is true,
it also `croak`s when more than one link is found.

## C<< $mech->find_link( %options ) >>

  print $_->text . "\n"
      for $mech->find_link_dom( text_contains => 'CPAN' );

A method quite similar to [WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize)'s method.
The options are documented in `->find_link_dom`.

Returns a [WWW::Mechanize::Link](http://search.cpan.org/search?mode=module&query=WWW::Mechanize::Link) object.

This defaults to not look through child frames.

## C<< $mech->find_all_links( %options ) >>

  print $_->text . "\n"
      for $mech->find_link_dom( text_regex => qr/google/i );

Finds all links in the document.
The options are documented in `->find_link_dom`.

Returns them as list or an array reference, depending
on context.

This defaults to not look through child frames.

## C<< $mech->find_all_links_dom %options >>

  print $_->{innerHTML} . "\n"
      for $mech->find_link_dom( text_regex => qr/google/i );

Finds all matching linky DOM nodes in the document.
The options are documented in `->find_link_dom`.

Returns them as list or an array reference, depending
on context.

This defaults to not look through child frames.

## C<< $mech->follow_link $link >>

## C<< $mech->follow_link %options >>

  $mech->follow_link( xpath => '//a[text() = "Click here!"]' );

Follows the given link. Takes the same parameters that `find_link_dom`
uses.

## C<< $mech->click $name [,$x ,$y] >>

  $mech->click( 'go' );
  $mech->click({ xpath => '//button[@name="go"]' });

Has the effect of clicking a button on the current form. The first argument
is the `name` of the button to be clicked. The second and third arguments
(optional) allow you to specify the (x,y) coordinates of the click.

If there is only one button on the form, `$mech->click()` with
no arguments simply clicks that one button.

If you pass in a hash reference instead of a name,
the following keys are recognized:

- *

`selector` - Find the element to click by the CSS selector

- *

`xpath` - Find the element to click by the XPath query

- *

`synchronize` - Synchronize the click (default is 1)

Synchronizing means that WWW::Mechanize::Firefox will wait until
one of the events listed in `events` is fired. You want to switch
it off when there will be no HTTP response or DOM event fired, for
example for clicks that only modify the DOM.

Returns a [HTTP::Response](http://search.cpan.org/search?mode=module&query=HTTP::Response) object.

As a deviation from the WWW::Mechanize API, you can also pass a 
hash reference as the first parameter. In it, you can specify
the parameters to search much like for the `find_link` calls.

# FORM METHODS

## C<< $mech->current_form >>

  print $mech->current_form->{name};

Returns the current form.

This method is incompatible with [WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize).
It returns the DOM `<form>` object and not
a [HTML::Form](http://search.cpan.org/search?mode=module&query=HTML::Form) instance.

## C<< $mech->form_name $name [, %options] >>

  $mech->form_name( 'search' );

Selects the current form by its name. The options
are identical to those accepted by the L</$mech->xpath> method.

## C<< $mech->form_id $id [, %options] >>

  $mech->form_id( 'login' );

Selects the current form by its `id` attribute.
The options
are identical to those accepted by the L</$mech->xpath> method.

This is equivalent to calling

    $mech->selector("#$id",single => 1,%options)

## C<< $mech->form_number $number [, %options] >>

  $mech->form_number( 2 );

Selects the _number_th form.
The options
are identical to those accepted by the L</$mech->xpath> method.

## C<< $mech->form_with_fields [$options], @fields >>

  $mech->form_with_fields(
      'user', 'password'
  );

Find the form which has the listed fields.

If the first argument is a hash reference, it's taken
as options to `->xpath`.

See also L</$mech->submit_form>.

## C<< $mech->forms %options >>

  my @forms = $mech->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 options
are identical to those accepted by the L</$mech->selector> method.



The returned elements are the DOM `<form>` elements.

## C<< $mech->field $name, $value, [,\@pre_events [,\@post_events]] >>

  $mech->field( user => 'joe' );
  $mech->field( not_empty => '', [], [] ); # bypass JS validation

Sets the field with the name to the given value.
Returns the value.

Note that this uses the `name` attribute of the HTML,
not the `id` attribute.

By passing the array reference `PRE EVENTS`, you can indicate which
Javascript events you want to be triggered before setting the value.
`POST EVENTS` contains the events you want to be triggered
after setting the value.

By default, the events set in the
constructor for `pre_events` and `post_events`
are triggered.

## C<< $mech->value( $name_or_element, [%options] ) >>

    print $mech->value( 'user' );

Returns the value of the field named `NAME` or of the
DOM element passed in.

The legacy form of

    $mech->value( name => value );

is also still supported but will likely be deprecated
in favour of the `->field` method.

## C<< $mech->get_set_value( %options ) >>

Allows fine-grained access to getting/setting a value
with a different API. Supported keys are:

  pre
  post
  name
  value

in addition to all keys that `$mech->xpath` supports.

## C<< $mech->submit >>

  $mech->submit;

Submits the current form. Note that this does __not__ fire the `onClick`
event and thus also does not fire eventual Javascript handlers.
Maybe you want to use `$mech->click` instead.

## C<< $mech->submit_form( %options ) >>

  $mech->submit_form(
      with_fields => {
          user => 'me',
          pass => 'secret',
      }
  );

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 => $mech->current_form()`

Specifies the form to be filled and submitted. Defaults to the current form.

- *

`fields => \%fields`

Specifies the fields to be filled in the current form

- *

`with_fields => \%fields`

Probably all you need for the common case. It combines a smart form selector
and data setting in one operation. It selects the first form that contains
all fields mentioned in \%fields. This is nice because you don't need to
know the name or number of the form to do this.

(calls L</$mech->form_with_fields()> and L</$mech->set_fields()>).

If you choose this, the form_number, form_name, form_id and fields options
will be ignored.

## C<< $mech->set_fields( $name => $value, ... ) >>

  $mech->set_fields(
      user => 'me',
      pass => 'secret',
  );

This method sets multiple fields of the current 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.

## C<< $mech->set_visible( @values ) >>

  $mech->set_visible( $username, $password );

This method sets fields of the current 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 (or use the
`mech-dump` utility, installed with [WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize)) to see what
the field names are; you can just say

  $mech->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 specifiers that are possible in [WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize) are not yet supported.

## C<< $mech->is_visible $element >>

## C<< $mech->is_visible %options >>

  if ($mech->is_visible( selector => '#login' )) {
      print "You can log in now.";
  };

Returns true if the element is visible, that is, it is
a member of the DOM and neither it nor its ancestors have
a CSS `visibility` attribute of `hidden` or
a `display` attribute of `none`.

You can either pass in a DOM element or a set of key/value
pairs to search the document for the element you want.

- *

`xpath` - the XPath query

- *

`selector` - the CSS selector

The remaining options are passed through to either the
L</$mech->xpath|xpath> or L</$mech->selector|selector> method.

## C<< $mech->wait_until_invisible $element >>

## C<< $mech->wait_until_invisible %options >>

  $mech->wait_until_invisible( $please_wait );

Waits until an element is not visible anymore.

Takes the same options as L<$mech->is_visible/->is_visible>.

In addition, the following options are accepted:

- *

`timeout` - the timeout after which the function will `croak`. To catch
the condition and handle it in your calling program, use an [eval](http://search.cpan.org/search?mode=module&query=eval) block.
A timeout of `0` means to never time out.

- *

`sleep` - the interval in seconds used to [sleep](http://search.cpan.org/search?mode=module&query=sleep). Subsecond
intervals are possible.

## C<< $mech->clickables >>

    print "You could click on\n";
    for my $el ($mech->clickables) {
        print $el->{innerHTML}, "\n";
    };

Returns all clickable elements, that is, all elements
with an `onclick` attribute.

## C<< $mech->xpath $query, %options >>

    my $link = $mech->xpath('//a[id="clickme"]', one => 1);
    # croaks if there is no link or more than one link found

    my @para = $mech->xpath('//p');
    # Collects all paragraphs

Runs an XPath query in Firefox against the current document.

The options allow the following keys:

- *

`document` - document in which the query is to be executed. Use this to
search a node within a specific subframe of `$mech->document`.

- *

`frames` - if true, search all documents in all frames and iframes.
This may or may not conflict with `node`. This will default to the
`frames` setting of the WWW::Mechanize::Firefox object.

- *

`node` - node relative to which the query is to be executed

- *

`single` - If true, ensure that only one element is found. Otherwise croak
or carp, depending on the `autodie` parameter.

- *

`one` - If true, ensure that at least one element is found. Otherwise croak
or carp, depending on the `autodie` parameter.

- *

`maybe` - If true, ensure that at most one element is found. Otherwise
croak or carp, depending on the `autodie` parameter.

- *

`all` - If true, return all elements found. This is the default.
You can use this option if you want to use `->xpath` in scalar context
to count the number of matched elements, as it will otherwise emit a warning
for each usage in scalar context without any of the above restricting options.

Returns the matched nodes.

You can pass in a list of queries as an array reference for the first parameter.

This is a method that is not implemented in WWW::Mechanize.

In the long run, this should go into a general plugin for
[WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize).

## C<< $mech->selector $css_selector, %options >>

  my @text = $mech->selector('p.content');

Returns all nodes matching the given CSS selector. If
$css_selector is an array reference, it returns
all nodes matched by any of the CSS selectors in the array.

This takes the same options that `->xpath` does.

In the long run, this should go into a general plugin for
[WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize).

## C<< $mech->expand_frames $spec >>

  my @frames = $mech->expand_frames();

Expands the frame selectors (or `1` to match all frames)
into their respective DOM document nodes according to the current
document. All frames will be visited in breadth first order.

This is mostly an internal method.

# IMAGE METHODS

## C<< $mech->content_as_png [$tab, \%coordinates ] >>

    my $png_data = $mech->content_as_png();

Returns the given tab or the current page rendered as PNG image.

All parameters are optional. 
 

TAB defaults to current TAB.

If the coordinates are given, that rectangle will be cut out.
The coordinates should be a hash with the four usual entries,
`left`,`top`,`width`,`height`.

This is specific to WWW::Mechanize::Firefox.

Currently, the data transfer between Firefox and Perl
is done Base64-encoded. It would be beneficial to find what's
necessary to make JSON handle binary data more gracefully.

## C<< $mech->element_as_png $element >>

    my $shiny = $mech->selector('#shiny', single => 1);
    my $i_want_this = $mech->element_as_png($shiny);

Returns PNG image data for a single element

## C<< $mech->element_coordinates $element >>

    my $shiny = $mech->selector('#shiny', single => 1);
    my ($pos) = $mech->element_coordinates($shiny);
    print $pos->{x},',', $pos->{y};

Returns the page-coordinates of the `$element`
in pixels as a hash with four entries, `left`, `top`, `width` and `height`.

This function might get moved into another module more geared
towards rendering HTML.

# COOKIE HANDLING

Firefox cookies will be read through [HTTP::Cookies::MozRepl](http://search.cpan.org/search?mode=module&query=HTTP::Cookies::MozRepl). This is
relatively slow currently.

# INCOMPATIBILITIES WITH WWW::Mechanize

As this module is in a very early stage of development,
there are many incompatibilities. The main thing is
that only the most needed WWW::Mechanize methods
have been implemented by me so far.

## Link attributes

In Firefox, the `name` attribute of links seems always
to be present on links, even if it's empty. This is in
difference to WWW::Mechanize, where the `name` attribute
can be `undef`.

## Unsupported Methods

- *

`->find_all_inputs`

This function is likely best implemented through `$mech->selector`.

- *

`->find_all_submits`

This function is likely best implemented through `$mech->selector`.

- *

`->images`

This function is likely best implemented through `$mech->selector`.

- *

`->find_image`

This function is likely best implemented through `$mech->selector`.

- *

`->find_all_images`

This function is likely best implemented through `$mech->selector`.

- *

`->field`

- *

`->select`

- *

`->tick`

- *

`->untick`

## Functions that will likely never be implemented

These functions are unlikely to be implemented because
they make little sense in the context of Firefox.

- *

`->add_header`

- *

`->delete_header`

- *

`->clone`

- *

`->credentials( $username, $password )`

- *

`->get_basic_credentials( $realm, $uri, $isproxy )`

- *

`->clear_credentials()`

- *

`->put`

I have no use for it

- *

`->post`

I have no use for it

# TODO

- *

Add `limit` parameter to `->xpath()` to allow an early exit-case
when searching through frames.

- *

Implement download progress via `nsIWebBrowserPersist.progressListener`
and our own `nsIWebProgressListener`.

- *

Make `->click` use `->click_with_options`

- *

Rip out parts of Test::HTML::Content and graft them
onto the `links()` and `find_link()` methods here.
Firefox is a conveniently unified XPath engine.

Preferrably, there should be a common API between the two.

- *

Spin off XPath queries (`->xpath`) and CSS selectors (`->selector`)
into their own Mechanize plugin(s).

# INSTALLING

- *

Install the `mozrepl` add-on into Firefox

- *

Start the `mozrepl` add-on or you will see test failures/skips
in the module when calling `->new`. You may want to set
`mozrepl` to start when the browser starts.

# SEE ALSO

- *

The MozRepl Firefox plugin at <http://wiki.github.com/bard/mozrepl>

- *

[WWW::Mechanize](http://search.cpan.org/search?mode=module&query=WWW::Mechanize) - the module whose API grandfathered this module

- *

[WWW::Scripter](http://search.cpan.org/search?mode=module&query=WWW::Scripter) - another WWW::Mechanize-workalike with Javascript support

- *

<https://developer.mozilla.org/En/FUEL/Window> for JS events relating to tabs

- *

<https://developer.mozilla.org/en/Code_snippets/Tabbed_browser#Reusing_tabs>
for more tab info

- *

<https://developer.mozilla.org/en/Document_Loading_-_From_Load_Start_to_Finding_a_Handler>
for information on how to possibly override the "Save As" dialog

# REPOSITORY

The public repository of this module is 
<http://github.com/Corion/www-mechanize-firefox>.

# AUTHOR

Max Maischein `corion@cpan.org`

# COPYRIGHT (c)

Copyright 2009-2010 by Max Maischein `corion@cpan.org`.

# LICENSE

This module is released under the same terms as Perl itself.