=pod

=head1 NAME

WWW::Mechanize::Firefox::Cookbook - Recipes for using WWW::Mechanize::Firefox

=head1 Introduction

Note that WWW::Mechanize::Firefox is quite similar in its API to L<WWW::Mechanize>,
so many of the recipes in L<WWW::Mechanize::Cookbook> apply to it as well.

=head1 Basics

=head2 Launch WWW::Mechanize::Firefox

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

=head2 Launch WWW::Mechanize::Firefox if Firefox is not running

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

=head2 Use an existing tab

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

=head2 Use the current tab

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

=head2 Bring the tab to the foreground at start

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

=head2 Bring the tab to the foreground later

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

=head2 Fetch a page to a file

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      tab => 'current',
  );
  $mech->get('http://google.com',
      ':content_file' => 'google_com.html' );

=head2 Fetch a page to a file with all images

  use WWW::Mechanize::Firefox;
  my $mech = WWW::Mechanize::Firefox->new(
      tab => 'current',
  );
  $mech->get('http://google.com');
  $mech->save_content('google_com.html', 'google_com files');

=head1 Advanced HTML interaction

=head2 Wait until an element appears

Some sites generate content after the C<DOMContentLoaded>
event has fired. To wait until an element becomes available,
use the following code:

    # The submit button is generated after the page has loaded

    my $retries = 10;
    while ($retries-- and ! $mech->is_visible( xpath => '//*[@id="submit"]' )) {
          sleep 1;
    };
    die "Timeout" unless $retries;
    
    # Now the element exists
    $mech->click({xpath => '//*[@id="submit"]'});

=head2 Wait until an element disappears

Some sites display an hourglass or some other indicator to
tell you to wait. 
To wait until such an element becomes invisible,
use the following code:

    my $retries = 10;
    while ($retries-- and $mech->is_visible( xpath => '//*[@id="hourglass"]' )) {
          sleep 1;
    };
    die "Timeout while waiting for application" unless $retries;
    
    # Now the hourglass is not visible anymore

=head1 UI interaction

=head2 Keep the tab open after your program quits

In the case that you want to navigate the user to a specific place and
then take over manually, you can prevent the automatic closing of the browser
tab. Either create your C<$mech> object like this:

  my $mech = WWW::Mechanize::Firefox->new(
      autoclose => 0,
  );

or decide at runtime whether to close the tab:

  $mech->autoclose_tab(0);

This does currently not work.

=head2 Get notified when the current tab changes

    my $browser = $mech->repl->expr('window.getBrowser()');

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

    while (1) {
        $mech->repl->poll();
        sleep 1;
    };


=head1 Images

=head2 Save the current page as PNG

This will take a "screenshot" which also includes plugins like Flash.

  my $png = $mech->content_as_png();
  open my $fh, '>', 'page.png'
      or die "Couldn't save to 'page.png': $!";
  binmode $fh;
  print {$fh} $png;
  close $fh;

Also see the file C<screenshot.pl> included and installed through the
distribution.

=head3 Save top left corner of the current page as PNG

  my $rect = {
    left  =>    0,
    top   =>    0,
    width  => 200,
    height => 200,
  };
  my $png = $mech->content_as_png(undef, $rect);
  open my $fh, '>', 'page.png'
      or die "Couldn't save to 'page.png': $!";
  binmode $fh;
  print {$fh} $png;
  close $fh;

=head1 Javascript

=head2 Check that your Page has no Javascript compile errors

  $mech->get('mypage');
  my @errors = map {$_->{message}} $mech->js_errors();
  if (@errors) {
      die "Found errors on page: @errors";
  };

=head3 Override the Javascript C<alert()> function

  $mech->eval_in_page('alert("Hello");',
      { alert => sub { print "Captured alert: '@_'\n" } }
  );

=head3 Set a value without triggering Javascript events

Just pass empty lists for the lists of events to invoke

  $mech->field( 'myfield', 'myvalue', [], [] );

=head1 Not working yet

=head2 Upload a file to an C<ftp> server

B< Not implemented > - this requires instantiating and passing
a C< nsIURI > object instead of a C< nsILocalFile >.

You can use C<< ->save_url >> to I<transfer> files. C<$localname>
can be a local filename, a C<file://> URL or any other URL that allows
uploads, like C<ftp://>.

  $mech->save_url('file://path/to/my/file.txt'
      => 'ftp://myserver.example/my/file.txt');

=head1 AUTHOR

Max Maischein C<corion@cpan.org>

Contributed examples contain the original author's name.

=head1 COPYRIGHT

Copyright 2010, Max Maischein.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

=cut
